@faapi/agent
faapi 的 agent 运行时——在已扫描的 agent / tool 注册表之上提供 LLM 驱动的 ReAct 循环
@faapi/agent 组合 faapi 核心包已生成的 faapi-agents.js + faapi-tools.js 清单，提供：
- LLM Provider 抽象（Phase 3.2）—— 统一接口对接 OpenAI / Anthropic 等 provider
- ReAct 循环引擎（Phase 3.3）—— LLM 输出 → 调用 tool / 递归 sub-agent → 把结果回灌给 LLM，循环直到最终回答
- Agent 类（Phase 3.4）—— 按
agent.name查找元数据、加载 handler、组装 agent.tools + sub-agent，提供run/stream/asTool - 递归防护 ——
maxTurns+maxAgentDepth（来自config.agent或 agent 自身config块）
与 faapi 核心的关系
faapi 核心（@faapi/faapi） @faapi/agent（本包）
──────────────────────────── ────────────────────────────
scanAgents → faapi-agents.js ──→ Agent.run / stream
scanTools → faapi-tools.js ──→ reactLoop 组装 tool 列表
agentRegistry / toolRegistry ──→ resolveAgentTools / resolveSubAgents / asTool
loadAgentModule / loadToolModule ──→ reactLoop 执行 tool / sub-agent
config.agent（llm / maxTurns …） ──→ Agent 类构造参数
核心包负责扫描与产物生成（dev/prod 一致），本包负责运行时编排——LLM 调用、tool 分发、递归控制、流式输出。
安装
pnpm add @faapi/agent
# 或
npm install @faapi/agent
要求 Node.js >= 24。
当前处于持续开发阶段（Phase 3.x），API 可能在稳定前调整。
启用方式
在 faapi.config.ts 的 plugins 中声明即启用 agent 运行时（Phase 3.5 集成）：
import type { FaapiConfig } from '@faapi/faapi';
export default {
agent: {
llms: {
openai: {
provider: 'openai',
apiKey: process.env.OPENAI_API_KEY,
models: { 'gpt-4o': {} },
},
},
maxTurns: 10,
maxAgentDepth: 3,
},
plugins: ['@faapi/agent'],
} satisfies FaapiConfig;
无默认 agent / 默认 provider——handler 调用时显式指定 agent 名与 model/provider：
// src/api/chat/handler.ts
import type { AgentHandle } from '@faapi/agent';
export async function POST(agent: AgentHandle, body: { input: string }) {
const result = await agent.run(body.input, { agent: 'researcher', model: 'gpt-4o' });
return { content: result.content, turns: result.turns };
}
CLI 启动时动态加载——未安装时自动跳过，不影响核心功能。需单独安装：pnpm add @faapi/agent。
多 agent 组织
agent 与 tool 的目录约定（由 faapi 核心包扫描，详见 AGENTS.md 5.4）：
src/
├── tools/ ← 所有 tool（agent 通过 config.tools 显式引用）
│ └── weather/handler.ts
├── agents/
│ ├── researcher/ ← agent "researcher"
│ │ └── handler.ts ← export const config / export function run
│ └── writer/
│ └── handler.ts ← config.agents: ['researcher'] → 可调用 researcher
- tool 位置：
src/tools/**（所有 tool 统一放此目录，无 agent 专属 tool 概念） - agent 可用 tool：在 agent 的
config.tools字段显式声明引用 tool 名 - sub-agent：在 agent 的
config.agents字段声明可调用的其他 agent 名
状态
Phase 3.1：包骨架初始化（按 AGENTS.md 6.5 清单配置）。