# @faapi/agent 中文文档

规范地址：https://npmcn.com/package/%40faapi/agent/

版本：7\.21\.0
npm 元数据更新时间：2026-10-31T23:22:13.337Z
中文译文更新时间：2026-11-01T03:11:45.747Z
软件包许可：MIT

本文由上游 README 机器翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40faapi/agent
原文对照：https://npmcn.com/package/%40faapi/agent/?lang=original
项目主页：https://github.com/faapi/faapi#readme
源码仓库：https://github.com/faapi/faapi

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：531 kB，7 个文件
- 模块格式：ES Module
- TypeScript 类型：包内自带
- Node.js 要求：\>=24
- 运行依赖：0 个
- peer 依赖：zod ^4\.4\.3，typescript \>=5\.7\.0，@faapi/faapi ^7\.21\.0
- 首次发布：2026-08-19T09:07:09.540Z
- 最新版本发布：2026-10-31T23:22:12.988Z
- 已发布版本数：102（近 12 个月 102 个）

## 中文简介

代理运行时faapi - llm驱动的ReAct循环扫描代理/工具注册表

## 安装

```sh
npm install @faapi/agent
```

也可以使用：`pnpm add @faapi/agent`、`yarn add @faapi/agent`、`bun add @faapi/agent`

## README

# @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 分发、递归控制、流式输出。

## 安装

```bash
pnpm add @faapi/agent
# 或
npm install @faapi/agent
```

要求 Node.js >= 24。

> 当前处于持续开发阶段（Phase 3.x），API 可能在稳定前调整。

## 启用方式

在 `faapi.config.ts` 的 `plugins` 中声明即启用 agent 运行时（Phase 3.5 集成）：

```ts
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：

```ts
// 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](https://npmcn.com/AGENTS.md)）：

```
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](https://npmcn.com/AGENTS.md) 清单配置）。

## 许可证

[MIT](https://github.com/faapi/faapi/blob/main/LICENSE)

## 常见问题

### @faapi/agent 是什么？

代理运行时faapi - llm驱动的ReAct循环扫描代理/工具注册表

### 如何安装 @faapi/agent？

在项目目录运行 npm install @faapi/agent，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：zod（^4\.4\.3）、@faapi/faapi（^7\.21\.0）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

### @faapi/agent 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package\.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

### @faapi/agent 支持 ESM 还是 CommonJS？

以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。

### @faapi/agent 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=24。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

### @faapi/agent 可以商用吗？

@faapi/agent 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

### @faapi/agent 还在维护吗？

最新版本 7\.21\.0 发布于 2026/11/01（2 天前）；至今共发布 102 个版本，其中过去 12 个月发布了 102 个；首次发布于 2026/08/19。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。