개요
Flue 是一个 TypeScript 框架，专为构建代理而设计，内置代理 harness，支持多种沙箱，可部署到任何环境，强调运行时无关性和可编程性。
README 미리보기
> **Experimental** — Flue is under active development. APIs may change.\n>\n> Looking for `v0.0.x`? [See here.](https://github.com/withastro/flue/tree/v0.0.x)\n\n# Flue\n\nFlue is **The Agent Harness Framework.** If you know how to use Claude Code (or Codex, OpenCode, Pi, etc)... then you already know the basics of how to build agents with Flue.\n\nFlue is a TypeScript framework for building the next generation of agents, designed around a built-in **agent harness**. It's like Claude Code, but 100% headless and programmable. There's no baked-in assumption like requiring a human operator to function. No TUI. No GUI. Just TypeScript.\n\nBut using Flue feels like using Claude Code. The agents you build act autonomously to solve problems and complete tasks. They require very little code to run — most of the "logic" lives in Markdown: skills, context, and `AGENTS.md`.\n\nFlue isn't another AI SDK. It's a proper runtime-agnostic framework — think Astro or Next.js, but for agents. Write once, build, and deploy your agents anywhere (Node.js, Cloudflare, GitHub Actions, GitLab CI/CD, etc).\n\n## Packages\n\n| Package | Description |\n| ----------------------------- | --------------------------------------- |\n| [`@flue/sdk`](packages/sdk) | Core SDK: build system, sessions, tools |\n| [`@flue/cli`](packages/cli) | CLI for building and running agents |\n\n## Examples\n\n### Quickstart\n\nThe simplest agent — no container, no tools, just a prompt and a typed result.\n\nUnless you opt-in to initializing a full container sandbox, Flue will default to a virtual sandbox for every agent, powered by [just-bash](https://github.com/vercel-labs/just-bash). A virtual sandbox is going to be dramatically faster, cheaper, and more scalable than running a full container for every agent, which makes it perfect for building high-traffic/high-scale agents.\n\n```ts\n// .flue/agents/hello-world.ts\nimport type { FlueContext } from '@flueFAQ (5)
문제 해결Anthropic overloaded API errors로 인한 flue workflow 충돌을 방지하는 방법?
Anthropic의 과부하 오류와 같은 일시적인 model-provider 실패는 이제 exponential backoff를 사용하여 자동으로 재시도됩니다. commit 666289f 이상을 포함하는 버전으로 업그레이드하세요.
문제 해결Bun을 사용할 때 flue CLI가 'upgrade Node.js' 오류를 표시하는 이유는 무엇인가요?
오류는 @flue/cli (v0.6.2 및 이하)가 Bun에서 실행 중일 때도 조건 없이 Node.js 버전을 확인하기 때문에 발생합니다. Bun은 TypeScript를 기본적으로 처리하므로 Node.js 버전 요구 사항은 불필요합니다. 48549d9 커밋부터 CLI는 Bun을 감지하고, Bun 버전이 너무 오래된 경우 잘못된 Node.js 오류 대신 Bun 특정 업그레이드 메시지를 제공합니다. 해결하려면 최신 @flue/cli 버전으로 업그레이드하세요. 이전 버전의 경우 환경 변수 FLUE_NO_NODE_VERSION_CHECK=1을 사용하여 확인을 우회하거나, 일시적으로 Node.js로 CLI를 실행하는 것이 해결 방법입니다.
문제 해결Flue를 Codex/OpenAI와 함께 사용할 때 'Invalid prompt_cache_key: string too long' 오류를 수정하는 방법은 무엇인가요?
Flue를 최신 버전으로 업그레이드하세요. 오류는 세션 어피니티 키가 64자 제한을 초과하여 발생했습니다. 수정 사항(commit a783a7c)은 긴 키를 제한된 불투명 aff_<ULID> 키로 대체합니다. 즉시 업그레이드할 수 없는 경우 임시 해결 방법으로, 긴 어피니티 키를 피하기 위해 컴포넌트 이름과 세션 이름을 짧게 유지하세요.
문제 해결flue의 내장 작업 도구가 session.prompt() 중에 'Session is already running prompt' 오류와 함께 실패하는 이유는 무엇인가요?
이는 flue v0.8.0 미만 버전에서 알려진 버그입니다. task tool이 이미 prompt를 실행 중인 동일한 parent session을 잘못 차지하려고 시도합니다. flue v0.8.0 이상으로 업그레이드하여 문제를 해결하십시오.
문제 해결'Cannot create binding for class FlueRegistry' 오류(코드 10061)가 Flue 0.7.0으로 Cloudflare Workers를 배포할 때 발생하는 경우 해결 방법은?
Flue 0.7.0에서 새 내부 Durable Object 'FlueRegistry'에 대한 마이그레이션이 생성된 wrangler.jsonc의 기존 마이그레이션보다 앞서 나타납니다. Wrangler는 적용되지 않은 마이그레이션이 이미 적용된 마이그레이션 뒤에 와야 하므로 이를 거부합니다. 해결 방법: dist/wrangler.jsonc를 수동으로 편집하고 'flue-class-FlueRegistry' 태그를 마이그레이션 배열의 끝으로 이동합니다. 영구적인 해결을 위해 Flue 0.9.0+로 업그레이드하세요. 이 버전은 더 이상 마이그레이션을 생성하지 않습니다. 올바른 순서로 자체 wrangler.json을 관리하세요.