@faapi/agent 0.0.0-canary.0 → 3.0.0

package/dist/index.d.ts

@@ -0,0 +1,602 @@
+import { LlmConfig, AgentMetadata, ToolMetadata, ToolModule, AgentModule, AgentToolDescriptor, FaapiPlugin } from '@faapi/faapi';
+
+/**
+ * LLM Provider 错误
+ *
+ * 含 HTTP 状态码（网络错误为 `undefined`）和响应体摘要,
+ * 业务方可通过 `instanceof LLMProviderError` 区分 LLM 错误与其他错误。
+ */
+declare class LLMProviderError extends Error {
+    /** HTTP 状态码（网络错误 / JSON 解析错误为 undefined） */
+    readonly status?: number;
+    /** 响应体摘要（前 500 字符,便于诊断） */
+    readonly body?: string;
+    constructor(message: string, options?: {
+        status?: number;
+        body?: string;
+        cause?: unknown;
+    });
+}
+/**
+ * 创建 OpenAI 兼容 LLMProvider
+ *
+ * @param config LLM 提供方配置（apiKey / model / baseURL / 透传字段）
+ * @returns LLMProvider 实例（含 complete + stream 方法）
+ */
+declare function createOpenAIProvider(config: LlmConfig): LLMProvider;
+
+/**
+ * LLM Provider 抽象层
+ *
+ * 统一 `complete` / `stream` 接口，屏蔽 OpenAI / Anthropic 等 LLM 服务差异。
+ * [reactLoop](./reactLoop.md) 与 [Agent 类](./agent.md) 通过此接口调用 LLM，
+ * 与具体 provider 解耦。
+ *
+ * 详见 [provider.md](./provider.md)。
+ */
+/**
+ * 对话消息
+ *
+ * 四种 role 与 OpenAI chat completions 一致：
+ * - `system` —— 系统提示词（agent 的 systemPrompt）
+ * - `user` —— 用户输入
+ * - `assistant` —— LLM 回复（可能含 toolCalls）
+ * - `tool` —— tool 执行结果（需带 toolCallId 标识对应哪个 tool_call）
+ */
+interface LLMMessage {
+    role: 'system' | 'user' | 'assistant' | 'tool';
+    /** 消息内容（assistant 角色 + tool_calls 时可能为空字符串） */
+    content: string;
+    /** role='tool' 时:对应的 tool_call ID（用于 LLM 关联 tool 结果） */
+    toolCallId?: string;
+    /** role='assistant' 时:LLM 请求的 tool 调用（reactLoop 据此执行 tool） */
+    toolCalls?: LLMToolCall[];
+}
+/**
+ * LLM 请求的 tool 调用
+ *
+ * 由 LLM 在 assistant 消息中返回。`arguments` 已 JSON.parse，
+ * reactLoop 直接传给 tool 函数。
+ */
+interface LLMToolCall {
+    /** tool call ID（provider 分配，用于匹配 tool 结果） */
+    id: string;
+    /** tool 名（匹配 LLMToolDefinition.name） */
+    name: string;
+    /** tool 参数（已 JSON.parse 的对象） */
+    arguments: Record<string, unknown>;
+}
+/**
+ * Tool 定义
+ *
+ * 由 [reactLoop](./reactLoop.md) 从 [toolRegistry](../../faapi/src/injection/toolRegistry.md)
+ * + [agentRegistry.resolveSubAgents](../../faapi/src/injection/agentRegistry.md) 组装：
+ * - 常规 tool：`input` 来自 AST 提取的 zod schema（JSON Schema 形式）
+ * - agent-as-tool：`input` 为自由 schema（agent 参数开放）
+ */
+interface LLMToolDefinition {
+    /** tool 名（如 `weather.getWeather` 或 `agent.researcher`） */
+    name: string;
+    /** tool 描述（对 LLM 可见，引导 LLM 选择调用） */
+    description?: string;
+    /** JSON Schema 对象（描述 tool 参数结构） */
+    input: Record<string, unknown>;
+}
+/**
+ * complete / stream 的入参
+ *
+ * `model` / `temperature` / `maxTokens` 优先级高于 [LlmConfig](../../faapi/src/config/configTypes.md)
+ * （agent 自身 `config.model` 覆盖全局默认）。
+ */
+interface LLMCompleteRequest {
+    /** 对话消息（含历史 + 当前轮） */
+    messages: LLMMessage[];
+    /** 可用 tool 列表（未提供时 LLM 不会发起 tool_call） */
+    tools?: LLMToolDefinition[];
+    /** 覆盖 LlmConfig.model（agent 自身配置优先） */
+    model?: string;
+    /** 采样温度（0~2） */
+    temperature?: number;
+    /** 最大生成 token 数 */
+    maxTokens?: number;
+}
+/**
+ * LLM 响应的停止原因
+ *
+ * - `stop` —— LLM 主动结束（自然结束 / 遇到 stop 序列）
+ * - `tool_calls` —— LLM 请求调用 tool（reactLoop 据此进入下一轮）
+ * - `length` —— 达到 max_tokens 上限
+ * - `content_filter` —— 内容过滤触发
+ * - `other` —— 其他原因（未识别的 finish_reason）
+ */
+type LLMStopReason = 'stop' | 'tool_calls' | 'length' | 'content_filter' | 'other';
+/**
+ * complete 的返回
+ *
+ * `message.toolCalls` 不为空时 stopReason 应为 `'tool_calls'`。
+ */
+interface LLMResponse {
+    /** assistant 消息（含 content + 可选 toolCalls） */
+    message: LLMMessage;
+    /** 停止原因（reactLoop 据此判断是否进入下一轮） */
+    stopReason: LLMStopReason;
+    /** token 用量（部分 provider 不返回） */
+    usage?: LLMUsage;
+}
+/**
+ * Token 用量
+ */
+interface LLMUsage {
+    promptTokens: number;
+    completionTokens: number;
+    totalTokens: number;
+}
+/**
+ * stream 的单个 chunk
+ *
+ * - 内容流：`deltaContent` 为增量 token
+ * - tool 调用：累积完成后在最终 chunk 一并 emit `toolCalls`
+ * - 结束：最终 chunk 含 `finishReason` + 可选 `usage`
+ */
+interface LLMStreamChunk {
+    /** 增量内容（streaming token） */
+    deltaContent?: string;
+    /** 累积完成的 tool 调用（在最终 chunk 出现） */
+    toolCalls?: LLMToolCall[];
+    /** 结束原因（只在最终 chunk 出现） */
+    finishReason?: LLMStopReason;
+    /** token 用量（部分 provider 在最终 chunk 提供） */
+    usage?: LLMUsage;
+}
+/**
+ * LLM Provider 抽象接口
+ *
+ * 实现方：
+ * - [createOpenAIProvider](./providers/openai.md) —— OpenAI 兼容 API
+ *
+ * 消费方：
+ * - [reactLoop](./reactLoop.md) Phase 3.3 —— 调 complete / stream 执行 ReAct 循环
+ * - [Agent 类](./agent.md) Phase 3.4 —— 构造时持有 provider 实例
+ */
+interface LLMProvider {
+    /** 非流式:阻塞到 LLM 返回完整响应 */
+    complete(request: LLMCompleteRequest): Promise<LLMResponse>;
+    /** 流式:异步迭代 chunk(增量 token + tool call + 结束) */
+    stream(request: LLMCompleteRequest): AsyncIterable<LLMStreamChunk>;
+}
+
+/**
+ * 按 `config.provider` 路由到对应的 LLM 适配器
+ *
+ * Phase 3.2 仅支持 `'openai'`,其他值抛错不静默降级（参考 AGENTS.md §6.3）。
+ *
+ * @param config LLM 提供方配置（来自 faapi.config.ts 的 `agent.llm`）
+ * @returns LLMProvider 实例
+ * @throws {Error} 当 `config.provider` 不是已支持的值
+ */
+declare function createProvider(config: LlmConfig): LLMProvider;
+
+/**
+ * ReAct（Reasoning + Acting）循环引擎
+ *
+ * 反复调 LLM、执行 tool、把结果回传 LLM，直到 LLM 给出最终回答或达到 `maxTurns` 上限。
+ *
+ * 详见 [reactLoop.md](./reactLoop.md)。
+ */
+/**
+ * Tool 执行函数
+ *
+ * 由 [Agent 类](./agent.md)提供——reactLoop 不关心 tool 如何被找到和执行。
+ * Agent 类的 `executeTool` 实现：
+ * - 常规 tool → `loadToolModule` 加载 handler 并调用
+ * - agent-as-tool（`agent.` 前缀）→ 递归调子 agent 的 reactLoop（含 `maxAgentDepth` 防护）
+ *
+ * 返回值可以是任意类型——非 string 会被 JSON.stringify 后回传 LLM。
+ */
+type ToolExecutor = (name: string, args: Record<string, unknown>) => Promise<unknown>;
+/**
+ * reactLoop 配置
+ *
+ * 由 [Agent 类](./agent.md)组装并传入。
+ */
+interface ReactLoopConfig {
+    /** LLM provider 实例（由 [createProvider](./provider.md) 创建） */
+    provider: LLMProvider;
+    /** 系统提示词（来自 agent metadata 的 `systemPrompt`） */
+    systemPrompt?: string;
+    /** 可用 tool 列表（由 `resolveAgentTools` + `resolveSubAgents().map(asTool)` 组装） */
+    tools?: LLMToolDefinition[];
+    /** tool 执行函数（由 Agent 类提供，路由到常规 tool 或子 agent） */
+    executeTool: ToolExecutor;
+    /** 最大对话轮数（默认 10，来自 [AgentConfig](../../faapi/src/config/configTypes.md).maxTurns） */
+    maxTurns?: number;
+    /** 覆盖 LLM 模型名（来自 agent metadata 的 `model`） */
+    model?: string;
+    /** 采样温度 */
+    temperature?: number;
+    /** 最大生成 token 数 */
+    maxTokens?: number;
+}
+/**
+ * 非流式循环结果
+ */
+interface ReactLoopResult {
+    /** 最终 assistant 消息内容 */
+    content: string;
+    /** 完整对话历史（system + user + assistant + tool 消息） */
+    messages: LLMMessage[];
+    /** 使用的轮数（含最终轮） */
+    turns: number;
+    /** 最终轮的停止原因 */
+    stopReason: LLMStopReason;
+    /** 累计 token 用量（多轮累加，provider 不返回时为 `undefined`） */
+    usage?: LLMUsage;
+}
+/**
+ * 流式循环的单个 chunk
+ *
+ * 每个 chunk 至多含一个字段：
+ * - `deltaContent` — LLM 增量 token（多次 yield）
+ * - `toolCall` — tool 开始执行
+ * - `toolResult` — tool 执行完成
+ * - `done` — 循环结束（只 yield 一次）
+ */
+interface ReactLoopStreamChunk {
+    /** LLM 增量 token */
+    deltaContent?: string;
+    /** tool 开始执行（LLM 请求调用 tool） */
+    toolCall?: {
+        name: string;
+        arguments: Record<string, unknown>;
+    };
+    /** tool 执行完成（含结果） */
+    toolResult?: {
+        name: string;
+        result: string;
+    };
+    /** 循环结束 */
+    done?: {
+        content: string;
+        turns: number;
+        stopReason: LLMStopReason;
+        usage?: LLMUsage;
+    };
+}
+/**
+ * reactLoop 系统级错误
+ *
+ * 目前仅用于 `maxTurns` 超限。tool 执行错误不抛此类型——它们被 catch 后回传 LLM。
+ */
+declare class ReactLoopError extends Error {
+    /** 配置的 maxTurns 值 */
+    readonly maxTurns: number;
+    constructor(message: string, maxTurns: number);
+}
+/**
+ * 执行 ReAct 循环（非流式）
+ *
+ * 反复调 `provider.complete()` → 执行 tool → 回传结果，直到 LLM 返回 `stop`（或其他非 `tool_calls` 原因）或超出 `maxTurns`。
+ *
+ * @param input 用户输入
+ * @param config 循环配置
+ * @returns 最终结果（content + messages + turns + stopReason + usage）
+ * @throws {ReactLoopError} 超出 maxTurns
+ * @throws {Error} provider.complete 抛错时立即传播
+ */
+declare function reactLoop(input: string, config: ReactLoopConfig): Promise<ReactLoopResult>;
+/**
+ * 执行 ReAct 循环（流式）
+ *
+ * 使用 `provider.stream()` 异步迭代 chunks，yield `deltaContent` + `toolCall` + `toolResult` + `done`。
+ *
+ * @param input 用户输入
+ * @param config 循环配置
+ * @yields {ReactLoopStreamChunk} 流式 chunk
+ * @throws {ReactLoopError} 超出 maxTurns
+ * @throws {Error} provider.stream 抛错时立即传播
+ */
+declare function reactLoopStream(input: string, config: ReactLoopConfig): AsyncIterable<ReactLoopStreamChunk>;
+
+/**
+ * 全局 agent 配置覆盖
+ *
+ * 来自 faapi.config.ts 的 `agent` 块，提供全局默认值。
+ * agent 自身 `config.maxTurns` / `config.model` 优先于全局配置。
+ */
+interface AgentRuntimeConfig {
+    /** 默认最大对话轮数（agent 自身 maxTurns 优先） */
+    maxTurns?: number;
+    /** agent 调用 agent 的最大递归深度（默认 3） */
+    maxAgentDepth?: number;
+    /** 默认 tool 列表，所有 agent 都可用 */
+    defaultTools?: string[];
+}
+/**
+ * tool schema 解析结果
+ *
+ * 由 Phase 3.5 的注入器实现，提供 JSON Schema（给 LLM）和校验函数（给执行前校验）。
+ * - `jsonSchema` —— 发给 LLM 作为 tool 参数描述
+ * - `validate` —— 执行前校验 LLM 返回的参数，失败时返回 `{ error }` 回传 LLM 重试
+ */
+interface ToolSchemaResolution {
+    /** tool 参数的 JSON Schema（发给 LLM） */
+    jsonSchema: Record<string, unknown>;
+    /** 执行前校验函数（成功返回 coerce 后的 value，失败返回 error） */
+    validate: (input: Record<string, unknown>) => {
+        ok: true;
+        value: Record<string, unknown>;
+    } | {
+        ok: false;
+        error: string;
+    };
+}
+/**
+ * Agent 运行时依赖（依赖注入）
+ *
+ * Agent 类**不直接 import** faapi 核心的注册表/加载器，而是通过此接口接收访问器函数。
+ * 原因：
+ * - **可测试**——测试传 mock 访问器，无需启动真实注册表
+ * - **解耦**——Agent 类不依赖核心运行时模块
+ * - **phase 边界**——Phase 3.4 实现 Agent 类逻辑，Phase 3.5 注入真实访问器
+ *
+ * 访问器签名与 faapi 核心对称（见 [agent.md](./agent.md) 依赖注入章节）。
+ */
+interface AgentDeps {
+    /** LLM provider 实例 */
+    provider: LLMProvider;
+    /** 当前 agent 名 */
+    agentName: string;
+    /** 项目根目录（Phase 3.5 接线时用于加载器） */
+    rootDir: string;
+    /** 全局 agent 配置覆盖 */
+    config?: AgentRuntimeConfig;
+    /** 查 agent 元数据（对应 agentRegistry.getAgent） */
+    getAgent: (name: string) => AgentMetadata | undefined;
+    /** 查 tool 元数据（对应 toolRegistry.getTool） */
+    getTool: (name: string) => ToolMetadata | undefined;
+    /** 解析 agent 可用常规 tool（对应 agentRegistry.resolveAgentTools） */
+    resolveAgentTools: (name: string) => ToolMetadata[];
+    /** 解析 agent 可调用 sub-agent 列表（对应 agentRegistry.resolveSubAgents） */
+    resolveSubAgents: (name: string) => AgentMetadata[];
+    /** 动态 import tool handler（对应 loadToolModule） */
+    loadToolModule: (filePath: string, functionName: string) => Promise<ToolModule>;
+    /** 动态 import agent handler（对应 loadAgentModule） */
+    loadAgentModule: (filePath: string, hasConfig: boolean, hasRun: boolean) => Promise<AgentModule>;
+    /** tool input 的 schema 解析（Phase 3.5 实现，可选） */
+    resolveToolSchema?: (tool: ToolMetadata) => Promise<ToolSchemaResolution | undefined>;
+}
+/**
+ * Agent 系统级错误
+ *
+ * agent 未注册等不可恢复错误时抛出（调用方负责捕获）。
+ * sub-agent 递归超限用 {@link AgentRecursionError}。
+ */
+declare class AgentError extends Error {
+    constructor(message: string);
+}
+/**
+ * sub-agent 递归超 `maxAgentDepth` 时抛出
+ *
+ * 被 [reactLoop](./reactLoop.md) catch 后错误消息回传 LLM，LLM 可据此调整策略。
+ */
+declare class AgentRecursionError extends AgentError {
+    /** 配置的 maxAgentDepth 值 */
+    readonly maxDepth: number;
+    /** 当前递归深度（超出 maxDepth） */
+    readonly currentDepth: number;
+    constructor(maxDepth: number, currentDepth: number);
+}
+/**
+ * faapi Agent
+ *
+ * 组装 [reactLoop](./reactLoop.md) 配置、执行 tool、递归 sub-agent 的运行时入口。
+ */
+declare class Agent {
+    private readonly deps;
+    /** 当前递归深度（根 agent 为 1，sub-agent 递增） */
+    private readonly depth;
+    /**
+     * tool schema 解析缓存（按 tool.name 缓存，含 undefined 结果）
+     *
+     * `buildToolDefinitions` 组装 LLM tool 列表时解析一次 schema（取 jsonSchema），
+     * `executeTool` 执行前校验时复用同一份 schema（取 validate）——
+     * 避免每次 tool 执行都重新 `loadToolSchema` + `z.toJSONSchema`。
+     *
+     * 实例级缓存：sub-agent 各有独立 cache（tool 集合可能不同）。
+     */
+    private readonly schemaCache;
+    /**
+     * @param deps 运行时依赖（访问器 + provider + config）
+     * @param depth 递归深度（默认 1 = 根 agent；sub-agent 递归时传入 depth+1）
+     */
+    constructor(deps: AgentDeps, depth?: number);
+    /**
+     * 非流式执行——组装 config 调 [reactLoop](./reactLoop.md)
+     *
+     * @param input 用户输入
+     * @returns 最终结果（content + messages + turns + stopReason + usage）
+     * @throws {AgentError} agent 未注册
+     * @throws {ReactLoopError} 超出 maxTurns
+     * @throws {Error} provider.complete 抛错时立即传播
+     */
+    run(input: string): Promise<ReactLoopResult>;
+    /**
+     * 流式执行——组装 config 调 [reactLoopStream](./reactLoop.md)
+     *
+     * @param input 用户输入
+     * @yields 流式 chunk（deltaContent / toolCall / toolResult / done）
+     * @throws {AgentError} agent 未注册
+     * @throws {ReactLoopError} 超出 maxTurns
+     * @throws {Error} provider.stream 抛错时立即传播
+     */
+    stream(input: string): AsyncIterable<ReactLoopStreamChunk>;
+    /**
+     * 把自身包装为 `AgentToolDescriptor` 供 LLM 当 tool 调用
+     *
+     * 与 [agentRegistry.asTool](../../faapi/src/injection/agentRegistry.md) 同构——
+     * Agent 类自带此方法便于在注入器场景直接调用（不必再过注册表）。
+     *
+     * @returns `AgentToolDescriptor` 或 `undefined`（agent 未注册）
+     */
+    asTool(): AgentToolDescriptor | undefined;
+    /**
+     * 查询 tool schema（带缓存）
+     *
+     * `buildToolDefinitions` 与 `executeTool` 共用此方法——
+     * 首次调用触发 `deps.resolveToolSchema`（加载 zod.js + 生成 JSON Schema），
+     * 后续命中缓存直接返回（含 `undefined` 结果，用 `has` 区分未解析 vs 解析为空）。
+     *
+     * `deps.resolveToolSchema` 未提供时直接返回 `undefined`，不写缓存。
+     */
+    private getToolSchema;
+    /**
+     * 组装 ReactLoopConfig
+     *
+     * 1. 查 agent 元数据（未注册抛 AgentError）
+     * 2. buildToolDefinitions 组装 tool 列表
+     * 3. config 字段优先级：agent 元数据 > 全局 AgentRuntimeConfig
+     */
+    private buildLoopConfig;
+    /**
+     * 组装 LLM 可见 tool 列表
+     *
+     * 合并三个来源（按 `name` 去重，先入者保留）：
+     * 1. **resolveAgentTools** —— agent 显式声明的 `tools` 引用
+     * 2. **全局 defaultTools** —— `config.defaultTools` 中的 tool 名（所有 agent 共享）
+     * 3. **sub-agent** —— `resolveSubAgents` 每个包装为 `agent.<name>`
+     *
+     * 每个常规 tool 的 `input`：
+     * - `resolveToolSchema` 提供 → 用其 `jsonSchema`
+     * - 未提供 / tool 无 `inputTypeName` → 自由 schema `{ type: 'object' }`
+     *
+     * sub-agent 的 `input` 始终为 `{ type: 'object' }`（agent 参数开放）。
+     */
+    private buildToolDefinitions;
+    /**
+     * tool 执行路由（由 reactLoop 调用）
+     *
+     * - `agent.` 前缀 → {@link executeSubAgent} 递归
+     * - 常规 tool → `loadToolModule` 加载 handler + 可选 input 校验 → 调用
+     *
+     * **常规 tool 校验失败**：不抛错，返回 `{ error }` 对象——reactLoop stringify 后
+     * 作为 tool 结果回传 LLM，LLM 可据此修正参数重试。
+     *
+     * **tool 未找到 / 加载失败**：抛错，被 reactLoop catch 后同样回传 LLM。
+     */
+    private executeTool;
+    /**
+     * sub-agent 递归执行
+     *
+     * 1. `maxAgentDepth` 防护——超限抛 {@link AgentRecursionError}
+     * 2. sub-agent handler 导出 `run` 时调自定义 `mod.run(args)`
+     * 3. 无 `run` 时调 `subAgent.run(JSON.stringify(args))` 走默认 reactLoop
+     *
+     * 自定义 run 接收原始 args 对象；默认 reactLoop 接收 stringify 后的 args
+     * 作为 user 消息（agent-as-tool input 为开放式 JSON）。
+     */
+    private executeSubAgent;
+}
+
+/**
+ * agent handle——注入到 handler 的 `agent` 参数,提供可调用的 agent 运行入口
+ *
+ * faapi 核心的 [agentHandle](../../faapi/src/injection/agentHandle.md) 工厂注册机制
+ * 让本包的 [plugin](./plugin.md) 在 setup 时注册工厂函数,injectParams 在
+ * `agent` 参数注入时调工厂拿到 `AgentHandle` 实例。
+ *
+ * `Agent` 类满足此接口（结构化类型）,plugin 的工厂直接返回 `Agent` 实例,
+ * 无需额外包装层。handler 通过 `AgentHandle` 类型获得类型安全:
+ *
+ * ```ts
+ * import type { AgentHandle } from '@faapi/agent';
+ *
+ * // src/api/chat/handler.ts
+ * export function POST(agent: AgentHandle, body: { input: string }) {
+ *   const result = await agent.run(body.input);
+ *   return { content: result.content, turns: result.turns };
+ * }
+ * ```
+ *
+ * 工厂未注册（`@faapi/agent` 插件未加载或 `config.agent.llm` / `defaultAgent` 未配置）
+ * 时注入 `undefined`,handler 需自行处理。
+ *
+ * 详见 [agentHandle.md](./agentHandle.md)。
+ */
+interface AgentHandle {
+    /**
+     * 非流式执行 agent
+     *
+     * 组装 ReAct 循环 config（systemPrompt + tools + maxTurns）→ 调
+     * [reactLoop](./reactLoop.md) → 返回最终结果。
+     *
+     * @param input 用户输入文本
+     * @returns 循环结果（content + messages + turns + stopReason + usage）
+     * @throws {AgentError} agent 未注册
+     * @throws {ReactLoopError} 超出 maxTurns
+     * @throws {Error} LLM provider 抛错时立即传播
+     */
+    run(input: string): Promise<ReactLoopResult>;
+    /**
+     * 流式执行 agent
+     *
+     * 组装 config → 调 [reactLoopStream](./reactLoop.md) → yield 流式 chunk。
+     * 适用于 LLM token 流式输出、tool 调用过程展示等场景。
+     *
+     * @param input 用户输入文本
+     * @yields 流式 chunk（deltaContent / toolCall / toolResult / done）
+     * @throws {AgentError} agent 未注册
+     * @throws {ReactLoopError} 超出 maxTurns
+     * @throws {Error} LLM provider 抛错时立即传播
+     */
+    stream(input: string): AsyncIterable<ReactLoopStreamChunk>;
+    /**
+     * 把自身包装为 `AgentToolDescriptor` 供 LLM 当 tool 调用
+     *
+     * 用于 agent-as-tool 场景：父 agent 把子 agent 包装为 tool,
+     * 加入 LLM 可见 tool 列表,LLM 调用时触发 sub-agent 递归执行。
+     *
+     * @returns `AgentToolDescriptor` 或 `undefined`（agent 未注册）
+     */
+    asTool(): AgentToolDescriptor | undefined;
+}
+
+/**
+ * @faapi/agent faapi 插件——注册 agent handle 工厂,让 handler 的 `agent` 参数注入可用的 Agent 实例
+ *
+ * 在 faapi.config.ts 中声明：
+ * ```ts
+ * import type { FaapiConfig } from '@faapi/faapi';
+ *
+ * export default {
+ *   agent: {
+ *     llm: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' },
+ *     defaultAgent: 'researcher',
+ *     maxTurns: 10,
+ *   },
+ *   plugins: ['@faapi/agent'],
+ * } satisfies FaapiConfig;
+ * ```
+ *
+ * 插件 setup 时：
+ * 1. 读 `config.agent.llm` → `createProvider` → LLMProvider 实例（单例）
+ * 2. 读 `config.agent.defaultAgent` / `maxTurns` / `maxAgentDepth` / `defaultTools`
+ * 3. 从 `@faapi/faapi` import 注册表/加载器访问器（getAgent / getTool / resolveAgentTools /
+ *    resolveSubAgents / loadAgentModule / loadToolModule）
+ * 4. `registerAgentHandleFactory` 注册工厂——每次请求时构造 [Agent](./agent.md) 实例注入到
+ *    handler 的 `agent` 参数
+ *
+ * 配置缺失时（`agent.llm` 或 `agent.defaultAgent` 未设置）跳过工厂注册并打印警告,
+ * handler 的 `agent` 参数注入 `undefined`。
+ *
+ * 详见 [plugin.md](./plugin.md)。
+ */
+
+/**
+ * @faapi/agent faapi 插件入口
+ *
+ * 在 faapi.config.ts 的 `plugins` 字段中声明 `'@faapi/agent'` 即可启用。
+ * 插件加载后,handler 的 `agent` 参数可注入可用的 [AgentHandle](./agentHandle.md)。
+ */
+declare const agentPlugin: FaapiPlugin;
+
+export { Agent, type AgentDeps, AgentError, type AgentHandle, AgentRecursionError, type AgentRuntimeConfig, type LLMCompleteRequest, type LLMMessage, type LLMProvider, LLMProviderError, type LLMResponse, type LLMStopReason, type LLMStreamChunk, type LLMToolCall, type LLMToolDefinition, type LLMUsage, type ReactLoopConfig, ReactLoopError, type ReactLoopResult, type ReactLoopStreamChunk, type ToolExecutor, type ToolSchemaResolution, createOpenAIProvider, createProvider, agentPlugin as default, reactLoop, reactLoopStream };