跳转到内容
Flue

输入关键词开始搜索文档。

快速开始

最后更新 查看 Markdown 源文件

Flue 是一个开源智能体框架，由 Astro 的创建者开发。使用类似 React 的 hooks API，在 TypeScript 中使用你喜欢的 LLM 构建智能体。在本地运行或部署到任何地方：Node.js、Cloudflare、GitHub Actions、GitHub CI/CD 等。

前置条件

  • Node.js — 最低版本要求 >=22.19.0。
  • LLM — 连接到你喜欢的模型提供商所需的 API 密钥。Flue 基于 Pi 构建，开箱即用地支持所有 Pi 提供商。Flue 的Cloudflare 运行时提供内置的 cloudflare/* AI 网关，无需 API 密钥。

自动安装

Read https://flueframework.cn/start.md then help create my first agent...

复制此提示并粘贴到你的编码智能体中。你的智能体将引导你在新项目或现有项目中设置智能体，并帮助你解答过程中遇到的任何问题。

你的编码智能体将运行 flue init 在你选择的目录中自动初始化一个新的 Flue 项目。如果你愿意，也可以自己运行此命令。

手动安装

强烈推荐大多数用户使用上面的 AI 引导提示。如果你更喜欢自己设置，请按照以下步骤操作。

在新目录中，安装运行时和 CLI：

npm install @flue/runtime @flue/cli

然后，创建一个基本的 flue.config.ts 文件：

flue.config.ts
import { defineConfig } from '@flue/runtime/config';

export default defineConfig({
	target: 'node', // 或 'cloudflare'
});

最后，创建你的第一个 src/agents/assistant.ts：

src/agents/assistant.ts
// 'use agent' 指令将下面的 Assistant() 函数标记为 Flue 智能体。
'use agent';
import { useModel } from '@flue/runtime';

// 这是你的第一个智能体：Assistant。
// 它的返回值是智能体的指令，这些指令会成为智能体的"系统"指令。
// 像 useModel() 这样的 Flue Hooks 允许你自定义和修改智能体的能力。
export function Assistant() {
	useModel('anthropic/claude-haiku-4-5');
	return '你是一个有用的助手。回复要简短。';
}

恭喜，你刚刚构建了你的第一个智能体！从这里你可以塑造它的行为并添加能力——或者继续前进，将它放到真实的服务器后面。

你可以使用 Pi 支持的任何模型/提供商。在上面的示例中，我们使用 Claude Haiku。无论你选择哪个，请确保向智能体运行时提供所需的 API 密钥。建议使用 .env 文件来管理你的 API 密钥：

# .env
ANTHROPIC_API_KEY="your-api-key"

在本地运行你的智能体

你现在可以从终端启动新的智能体，在本地机器上运行：

npx flue run src/agents/assistant.ts --message "Say hello in five words or fewer."

智能体是可寻址的，因此你可以通过传递智能体 ID（--id）与特定智能体进行消息交互。智能体对话是持久的——第二条消息会记住第一条。请参阅 flue run 了解完整的标志集。

npx flue run src/agents/assistant.ts --id hello-1 --message "What's a good name for a pet crab?"
npx flue run src/agents/assistant.ts --id hello-1 --message "Give me three more."

恭喜！你刚刚运行了你的第一个 Flue 智能体。你可以使用 flue run 在本地机器上运行智能体，或在 CI 环境中运行，如 GitHub Actions 和 GitLab CI/CD。

部署你的智能体

要远程托管你的智能体，你需要部署它。Flue 使用 Hono 和 Vite 分别为其服务器框架和构建流水线提供支持。请按照以下步骤为部署构建你的智能体。

1. 安装依赖

npm install @flue/vite hono vite

2. 配置项目

在项目根目录创建两个小的配置文件：

vite.config.ts
import { flue } from '@flue/vite';
import { defineConfig } from 'vite';

export default defineConfig({
	plugins: [flue()],
});

如果你要部署到 Cloudflare，那么你还应该安装 @cloudflare/vite-plugin 并在 Vite 插件数组中的 flue() 之后添加 cloudflare()。请参阅Cloudflare 运行时指南了解更多信息。

3. 构建你的应用路由

src/app.ts 是你的 Flue 应用路由所在的特殊文件。创建你的 Hono 应用实例，挂载你的智能体，并导出它以便构建过程能够识别。

src/app.ts
import { createAgentRouter } from '@flue/runtime/routing';
import { Hono } from 'hono';
import { Assistant } from './agents/assistant.ts';

// 1. 创建你的 Hono 应用实例。
const app = new Hono();
// 2. 定义你的智能体路由。
app.route('/agents/assistant', createAgentRouter(Assistant));
// 3. 导出你的应用。
export default app;

createAgentRouter() 辅助函数将定义和挂载你的智能体路由：POST /:id、GET /:id、POST /:id/abort 等。请参阅路由了解 Flue 中路由工作原理的完整演练。

4. 启动开发服务器

如前所述，Flue 利用 Vite 来支持其开发和构建流水线。要启动你的开发服务器，请运行 vite dev：

npx vite dev

Vite 启动你的 app.ts（默认在 http://localhost:5173）应用程序，并在你定义的路由上提供你的智能体服务。通过向你的智能体发送消息来测试你的设置——每条消息一个 POST，接收时返回 202：

curl -X POST http://localhost:5173/agents/assistant/hello-1 \
  -H 'content-type: application/json' \
  -d '{"kind":"user","body":"Tell me a joke."}'

URL 中的 hello-1 是智能体 ID，与你上面传递给 flue run 的 --id 相同。使用 curl "http://localhost:5173/agents/assistant/hello-1?view=history" 读回对话，或在你准备好构建真实产品体验时使用Flue 智能体 SDK和React hooks。

vite build 将为 "node" 运行时目标生成可运行的 dist/server.mjs 构建输出，或在配置了 "cloudflare" 运行时目标时生成可部署的 Cloudflare Worker。

恭喜，你已经完成了我们的快速入门指南！你已经创建了你的第一个 Flue 智能体，在本地运行了它，并成功为生产环境构建了它。

后续步骤

  • 智能体 — 配置模型，添加能力，并了解对话如何随时间持久化。
  • 工具、技能和沙盒 — 为你的智能体提供真实的能力和工作空间。
  • 路由 — 在 app.ts 中挂载额外的智能体和应用路由。
  • 部署到 Cloudflare 或 Node.js — 为真实流量托管你的智能体。
  • 智能体 SDK 和 React — 在已部署的智能体之上构建产品体验。