@faapi/agent 0.0.0-canary.0 → 3.1.0

package/dist/index.d.ts

@@ -0,0 +1,688 @@
+import { LlmConfig, AgentToolDescriptor, AgentCore, AgentMetadata, ToolMetadata, ToolModule, AgentModule, 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 / baseURL / models + provider 级透传字段,
+ *                model 级字段在 `models[modelName]` 下覆盖 provider 级同名字段）
+ * @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.llms[key]`）
+ * @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 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)。
+ */
+/**
+ * `agent.run` / `agent.stream` 的 options 参数——临时覆盖本次调用的 LLM 配置
+ *
+ * 所有字段可选,不传或 `undefined` 时回落到下一优先级（agent 元数据 → 全局配置）。
+ * **不修改 agent 自身状态**——下一次调用仍用默认配置。
+ *
+ * `model` 是字符串 key,支持三种形式（解析规则见 [agentHandle.md](./agentHandle.md) 的
+ * 「`options.model` 字符串 key 解析规则」）：
+ * - llms 的 key 精确匹配（如 `'openai'`）
+ * - `provider/model` 一体化（如 `'openai/gpt-4o'`）
+ * - 纯 model 名（如 `'gpt-4o'`）—— 在所有 provider 的 `models` 里查找,唯一时切到对应 provider
+ *
+ * 优先级（高 → 低）：`options` > agent 元数据（`config.model` / `config.maxTurns`）> 全局
+ * `AgentRuntimeConfig` / `defaultLlm` provider。详见 [agentHandle.md](./agentHandle.md) 的
+ * Run-level 覆盖优先级表。
+ *
+ * @example
+ * ```ts
+ * // 按请求切模型（纯 model 名,在 llms 里唯一时切到对应 provider）
+ * await agent.run(input, { model: 'gpt-4o-mini' });
+ *
+ * // provider/model 一体化形式（精确切换）
+ * await agent.run(input, { model: 'anthropic/claude-3-5-sonnet' });
+ * ```
+ */
+interface AgentRunOptions {
+    /**
+     * 切换 provider + model 的字符串 key（支持 llms key / `provider/model` / 纯 model 名）
+     *
+     * 不传时用 `defaultLlm` provider + agent 元数据 `config.model`。
+     */
+    model?: string;
+    /** 采样温度（透传给 LLM API,覆盖 provider/model 级 temperature） */
+    temperature?: number;
+    /** 最大生成 token 数（透传给 LLM API） */
+    maxTokens?: number;
+}
+interface AgentHandle {
+    /**
+     * 非流式执行 agent
+     *
+     * 组装 ReAct 循环 config（systemPrompt + tools + maxTurns + 应用 `options` 覆盖）→ 调
+     * [reactLoop](./reactLoop.md) → 返回最终结果。
+     *
+     * @param input 用户输入文本
+     * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens
+     *                （不修改 agent 自身状态,详见 {@link AgentRunOptions}）
+     * @returns 循环结果（content + messages + turns + stopReason + usage）
+     * @throws {AgentError} agent 未注册
+     * @throws {ReactLoopError} 超出 maxTurns
+     * @throws {Error} LLM provider 抛错时立即传播
+     */
+    run(input: string, options?: AgentRunOptions): Promise<ReactLoopResult>;
+    /**
+     * 流式执行 agent
+     *
+     * 组装 config（应用 `options` 覆盖）→ 调 [reactLoopStream](./reactLoop.md) → yield 流式 chunk。
+     * 适用于 LLM token 流式输出、tool 调用过程展示等场景。
+     *
+     * @param input 用户输入文本
+     * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens
+     *                （不修改 agent 自身状态,详见 {@link AgentRunOptions}）
+     * @yields 流式 chunk（deltaContent / toolCall / toolResult / done）
+     * @throws {AgentError} agent 未注册
+     * @throws {ReactLoopError} 超出 maxTurns
+     * @throws {Error} LLM provider 抛错时立即传播
+     */
+    stream(input: string, options?: AgentRunOptions): AsyncIterable<ReactLoopStreamChunk>;
+    /**
+     * 把自身包装为 `AgentToolDescriptor` 供 LLM 当 tool 调用
+     *
+     * 用于 agent-as-tool 场景：父 agent 把子 agent 包装为 tool,
+     * 加入 LLM 可见 tool 列表,LLM 调用时触发 sub-agent 递归执行。
+     *
+     * @returns `AgentToolDescriptor` 或 `undefined`（agent 未注册）
+     */
+    asTool(): AgentToolDescriptor | undefined;
+}
+
+/**
+ * 全局 agent 配置覆盖
+ *
+ * 来自 faapi.config.ts 的 `agent` 块，提供全局默认值。
+ * agent 自身 `config.maxTurns` / `config.model` 优先于全局配置。
+ */
+interface AgentRuntimeConfig {
+    /** 默认最大对话轮数（agent 自身 maxTurns 优先） */
+    maxTurns?: number;
+    /** agent 调用 agent 的最大递归深度（默认 3） */
+    maxAgentDepth?: number;
+}
+/**
+ * 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 实例映射（key 是 provider 名，来自 config.agent.llms） */
+    providers: Map<string, LLMProvider>;
+    /** 默认 provider 实例（config.agent.defaultLlm 对应，或 llms 第一个 key） */
+    defaultProvider: LLMProvider;
+    /** LLM provider 配置映射（含 models，用于 options.model key 解析） */
+    llms: Record<string, LlmConfig>;
+    /** 默认 provider key（config.agent.defaultLlm，或 llms 第一个 key） */
+    defaultLlm: string;
+    /** 当前 agent 名 */
+    agentName: string;
+    /** 项目根目录（Phase 3.5 接线时用于加载器） */
+    rootDir: string;
+    /** 全局 agent 配置覆盖 */
+    config?: AgentRuntimeConfig;
+    /** 查 agent LLM 可见元数据（对应 agentRegistry.getAgent,返回 AgentCore） */
+    getAgent: (name: string) => AgentCore | undefined;
+    /** 查 agent 完整元数据（对应 agentRegistry.getAgentEntry,返回 AgentMetadata 含 filePath/hasRun） */
+    getAgentEntry: (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,返回 AgentCore[]） */
+    resolveSubAgents: (name: string) => AgentCore[];
+    /** 动态 import tool handler（对应 loadToolModule） */
+    loadToolModule: (filePath: string, functionName: string) => Promise<ToolModule>;
+    /** 动态 import agent handler（对应 loadAgentModule,仅 hasRun 参数,无 hasConfig） */
+    loadAgentModule: (filePath: string, 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 运行时依赖（访问器 + providers Map + defaultProvider + llms + config）
+     * @param depth 递归深度（默认 1 = 根 agent；sub-agent 递归时传入 depth+1）
+     */
+    constructor(deps: AgentDeps, depth?: number);
+    /**
+     * 非流式执行——组装 config 调 [reactLoop](./reactLoop.md)
+     *
+     * @param input 用户输入
+     * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens
+     *                （不修改 agent 自身状态,详见 [agentHandle](./agentHandle.md)）
+     * @returns 最终结果（content + messages + turns + stopReason + usage）
+     * @throws {AgentError} agent 未注册
+     * @throws {ReactLoopError} 超出 maxTurns
+     * @throws {Error} provider.complete 抛错时立即传播
+     */
+    run(input: string, options?: AgentRunOptions): Promise<ReactLoopResult>;
+    /**
+     * 流式执行——组装 config 调 [reactLoopStream](./reactLoop.md)
+     *
+     * @param input 用户输入
+     * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens
+     *                （不修改 agent 自身状态,详见 [agentHandle](./agentHandle.md)）
+     * @yields 流式 chunk（deltaContent / toolCall / toolResult / done）
+     * @throws {AgentError} agent 未注册
+     * @throws {ReactLoopError} 超出 maxTurns
+     * @throws {Error} provider.stream 抛错时立即传播
+     */
+    stream(input: string, options?: AgentRunOptions): 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）——用 `getAgent` 拿 AgentCore
+     *    (LLM-facing 字段:systemPrompt / model / maxTurns)
+     * 2. buildToolDefinitions 组装 tool 列表
+     * 3. config 字段优先级（高 → 低）：`options` > agent 元数据 > 全局 AgentRuntimeConfig / deps.defaultProvider
+     *
+     * `options.model` 是字符串 key,由 {@link resolveModelKey} 解析为 provider + model
+     * （支持 llms key 精确匹配 / `provider/model` 一体化 / 纯 model 名模糊匹配）。
+     * 不传 `options.model` 时用 `deps.defaultProvider` + agent 元数据 `config.model`。
+     * 详见 [agentHandle.md](./agentHandle.md) 的「`options.model` 字符串 key 解析规则」。
+     */
+    private buildLoopConfig;
+    /**
+     * 解析 `options.model` 字符串 key → provider + model
+     *
+     * 规则见 [agentHandle.md](./agentHandle.md) 的「`options.model` 字符串 key 解析规则」：
+     * 1. `undefined` → `deps.defaultProvider` + `meta.model`
+     * 2. 精确匹配 `deps.providers` 的 key → 该 provider + 其 `models` 第一个 key
+     * 3. 含 `/` → `provider/model` 形式,`deps.providers.get(provider)` + 该 model
+     *    （要求该 model 在 `deps.llms[provider].models` 里）
+     * 4. 不含 `/` 且非 provider key → 在所有 provider 的 `models` 里按 model 名查找
+     *    - 唯一 → 该 provider + 该 model
+     *    - 多个 → 抛 `AgentError`（要求用 `provider/model` 消歧）
+     *    - 无 → 抛 `AgentError`
+     *
+     * @throws {AgentError} key 解析失败（provider/model 不存在或歧义）
+     */
+    private resolveModelKey;
+    /**
+     * 组装 LLM 可见 tool 列表
+     *
+     * 合并两个来源（按 `name` 去重，先入者保留）：
+     * 1. **resolveAgentTools** —— agent 显式声明的 `tools` 引用
+     * 2. **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）。
+     *
+     * 加载 handler.js 用 `getAgentEntry`(返回 AgentMetadata,含 filePath/hasRun),
+     * 而非 `getAgent`(返回 AgentCore,无代码加载细节)。DB skill 无文件,
+     * `getAgentEntry` 返回 `undefined`,走默认 reactLoop。
+     */
+    private executeSubAgent;
+}
+
+/**
+ * @faapi/agent faapi 插件——注册 agent handle 工厂,让 handler 的 `agent` 参数注入可用的 Agent 实例
+ *
+ * 在 faapi.config.ts 中声明：
+ * ```ts
+ * import type { FaapiConfig } from '@faapi/faapi';
+ *
+ * export default {
+ *   agent: {
+ *     llms: {
+ *       openai: {
+ *         provider: 'openai',
+ *         apiKey: process.env.OPENAI_API_KEY,
+ *         baseURL: 'https://api.openai.com/v1',
+ *         models: { 'gpt-4o': {}, 'gpt-4o-mini': { temperature: 0.5 } },
+ *       },
+ *     },
+ *     defaultLlm: 'openai',
+ *     defaultAgent: 'researcher',
+ *     maxTurns: 10,
+ *   },
+ *   plugins: ['@faapi/agent'],
+ * } satisfies FaapiConfig;
+ * ```
+ *
+ * 插件 setup 时：
+ * 1. 遍历 `config.agent.llms` → 每项调 `createProvider` → `Map<providerKey, LLMProvider>`
+ * 2. 读 `config.agent.defaultLlm` → `defaultProvider`（未设时用 `llms` 第一个 key）
+ * 3. 读 `config.agent.defaultAgent` / `maxTurns` / `maxAgentDepth`
+ * 4. 从 `@faapi/faapi` import 注册表/加载器访问器（getAgent / getTool / resolveAgentTools /
+ *    resolveSubAgents / loadAgentModule / loadToolModule）
+ * 5. `registerAgentHandleFactory` 注册工厂——每次请求时构造 [Agent](./agent.md) 实例注入到
+ *    handler 的 `agent` 参数
+ *
+ * 配置缺失时（`agent.llms` 或 `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 AgentRunOptions, 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 };