@faapi/agent 3.0.0 → 3.2.0

package/README.md

@@ -6,7 +6,7 @@
 
 - **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 + defaultTools + sub-agent，提供 `run` / `stream` / `asTool`
+- **Agent 类**（Phase 3.4）—— 按 `agent.name` 查找元数据、加载 handler、组装 agent.tools + sub-agent，提供 `run` / `stream` / `asTool`
 - **递归防护** —— `maxTurns` + `maxAgentDepth`（来自 `config.agent` 或 agent 自身 `config` 块）
 
 ## 与 faapi 核心的关系

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { LlmConfig, AgentMetadata, ToolMetadata, ToolModule, AgentModule, AgentToolDescriptor, FaapiPlugin } from '@faapi/faapi';
+import { LlmConfig, AgentToolDescriptor, AgentCore, AgentMetadata, ToolMetadata, ToolModule, AgentModule, FaapiPlugin } from '@faapi/faapi';
 
 /**
  * LLM Provider 错误
@@ -20,7 +20,8 @@ declare class LLMProviderError extends Error {
 /**
  * 创建 OpenAI 兼容 LLMProvider
  *
- * @param config LLM 提供方配置（apiKey / model / baseURL / 透传字段）
+ * @param config LLM 提供方配置（apiKey / baseURL / models + provider 级透传字段,
+ *                model 级字段在 `models[modelName]` 下覆盖 provider 级同名字段）
  * @returns LLMProvider 实例（含 complete + stream 方法）
  */
 declare function createOpenAIProvider(config: LlmConfig): LLMProvider;
@@ -170,12 +171,134 @@ interface LLMProvider {
  *
  * Phase 3.2 仅支持 `'openai'`,其他值抛错不静默降级（参考 AGENTS.md §6.3）。
  *
- * @param config LLM 提供方配置（来自 faapi.config.ts 的 `agent.llm`）
+ * @param config LLM 提供方配置（来自 faapi.config.ts 的 `agent.llms[key]`）
  * @returns LLMProvider 实例
  * @throws {Error} 当 `config.provider` 不是已支持的值
  */
 declare function createProvider(config: LlmConfig): LLMProvider;
 
+/**
+ * 单次 agent.run() / agent.stream() 的结构化调用明细
+ *
+ * 默认开启（`enableTracing` 默认 `true`）,业务方在生产主路径显式
+ * `enableTracing: false` 关闭以零开销运行。详见 [trace.md](./trace.md)。
+ */
+interface AgentTrace {
+    /** agent 名 */
+    agentName: string;
+    /** 开始时间（performance.now() ms,相对进程启动,便于算相对耗时） */
+    startedAt: number;
+    /** 总耗时 ms（done 时填充,抛错时也填充） */
+    durationMs?: number;
+    /** 总轮数（与 ReactLoopResult.turns 一致） */
+    turns: number;
+    /** 累计 token 用量（与 ReactLoopResult.usage 一致） */
+    usage?: LLMUsage;
+    /** 最终停止原因（与 ReactLoopResult.stopReason 一致） */
+    stopReason?: LLMStopReason;
+    /** 最终 assistant 内容（与 ReactLoopResult.content 一致） */
+    content?: string;
+    /** agent 抛错时的错误消息（agent.run 抛错时填充） */
+    error?: string;
+    /** 按发生顺序的事件列表 */
+    events: AgentTraceEvent[];
+}
+/**
+ * trace 事件（discriminated union,按 `type` 区分）
+ *
+ * 一次 agent.run() 内的事件序列示例：
+ *   llm_call(turn=1) → tool_call(turn=1) → llm_call(turn=2) → done
+ *
+ * sub-agent 调用作为 `subagent_call` 事件,内嵌 sub-trace（递归结构）。
+ */
+type AgentTraceEvent = LlmCallEvent | ToolCallEvent | SubAgentCallEvent;
+/**
+ * LLM 调用事件——每轮调 provider.complete() / provider.stream() 触发一次
+ */
+interface LlmCallEvent {
+    type: 'llm_call';
+    /** 第几轮（从 1 开始） */
+    turn: number;
+    startedAt: number;
+    durationMs?: number;
+    /** 该轮调用的 model 名 */
+    model: string;
+    /** 该轮发给 LLM 的输入消息快照（浅拷贝数组,消息对象引用共享） */
+    inputMessages: LLMMessage[];
+    /** 该轮 LLM 返回的 assistant 消息（含 toolCalls 若有） */
+    response: LLMMessage;
+    /** 该轮的停止原因 */
+    stopReason: LLMStopReason;
+    /** 该轮的 token 用量（provider 不返回时 undefined） */
+    usage?: LLMUsage;
+}
+/**
+ * 常规 tool 调用事件——executeTool 返回 unknown 时触发
+ */
+interface ToolCallEvent {
+    type: 'tool_call';
+    turn: number;
+    startedAt: number;
+    durationMs?: number;
+    /** LLM 分配的 tool_call_id（与 messages 里 tool 消息的 toolCallId 一致） */
+    toolCallId: string;
+    /** tool 名 */
+    name: string;
+    /** tool 参数（已 JSON.parse 的对象） */
+    arguments: Record<string, unknown>;
+    /** tool 执行结果（stringifyResult 后的字符串,与 messages 里 tool 消息一致） */
+    result: string;
+    /** tool 抛错时填充（result 为 stringifyError 后的字符串） */
+    error?: string;
+}
+/**
+ * sub-agent 调用事件——executeTool 返回 TracingToolResult 时触发
+ *
+ * sub-agent 的 trace 嵌入 `trace` 字段（递归结构）,业务方可还原完整调用树。
+ */
+interface SubAgentCallEvent {
+    type: 'subagent_call';
+    turn: number;
+    startedAt: number;
+    durationMs?: number;
+    toolCallId: string;
+    /** 被调用的 sub-agent 名 */
+    agentName: string;
+    /** 喂给 sub-agent 的输入（args JSON.stringify 后） */
+    input: string;
+    /** sub-agent 自己的 trace（递归） */
+    trace: AgentTrace;
+    /** sub-agent 返回的最终内容（sub-trace.content 的副本,便于不展开 sub-trace 也能读到结果） */
+    result?: string;
+    /** sub-agent 抛错时填充 */
+    error?: string;
+}
+/**
+ * sub-agent 调用的特殊返回值——reactLoop 据此识别 sub-agent 调用并发出 subagent_call 事件
+ *
+ * [Agent.executeSubAgent](./agent.md) 在 `enableTracing=true` 时返回此类型;
+ * `enableTracing=false` 时返回 `unknown`（与常规 tool 一致）。
+ *
+ * `__trace` 是标记字段,避免与普通对象返回值冲突。reactLoop 通过
+ * `typeof result === 'object' && result !== null && result.__trace === true`
+ * 判断是否为 TracingToolResult。
+ */
+interface TracingToolResult {
+    /** 标记字段（避免与普通对象返回值冲突） */
+    __trace: true;
+    /** sub-agent 返回的业务结果（stringifyResult 后会作为 tool 消息内容） */
+    result: unknown;
+    /** sub-agent 自己的 trace */
+    trace: AgentTrace;
+}
+/**
+ * 类型守卫：判断 ToolExecutor 返回值是否为 TracingToolResult
+ *
+ * reactLoop 用此函数区分 sub-agent 调用（发出 subagent_call 事件）
+ * 与常规 tool 调用（发出 tool_call 事件）。
+ */
+declare function isTracingToolResult(value: unknown): value is TracingToolResult;
+
 /**
  * ReAct（Reasoning + Acting）循环引擎
  *
@@ -192,8 +315,11 @@ declare function createProvider(config: LlmConfig): LLMProvider;
  * - agent-as-tool（`agent.` 前缀）→ 递归调子 agent 的 reactLoop（含 `maxAgentDepth` 防护）
  *
  * 返回值可以是任意类型——非 string 会被 JSON.stringify 后回传 LLM。
+ *
+ * sub-agent 调用时,若 `enableTracing=true`,返回 [TracingToolResult](./trace.md)
+ * 携带 sub-agent 的 trace,reactLoop 据此发出 `subagent_call` 事件（嵌套递归 trace）。
  */
-type ToolExecutor = (name: string, args: Record<string, unknown>) => Promise<unknown>;
+type ToolExecutor = (name: string, args: Record<string, unknown>) => Promise<unknown | TracingToolResult>;
 /**
  * reactLoop 配置
  *
@@ -216,6 +342,13 @@ interface ReactLoopConfig {
     temperature?: number;
     /** 最大生成 token 数 */
     maxTokens?: number;
+    /**
+     * 启用 tracing（默认 true）。开启时填充 `ReactLoopResult.trace` /
+     * `ReactLoopStreamChunk.traceEvent`,详见 [trace.md](./trace.md)。
+     *
+     * 业务方在生产主路径显式传 `false` 关闭以零开销运行。
+     */
+    enableTracing?: boolean;
 }
 /**
  * 非流式循环结果
@@ -231,6 +364,11 @@ interface ReactLoopResult {
     stopReason: LLMStopReason;
     /** 累计 token 用量（多轮累加，provider 不返回时为 `undefined`） */
     usage?: LLMUsage;
+    /**
+     * 结构化调用明细（`enableTracing=true` 时填充,否则 `undefined` 零开销）。
+     * 详见 [trace.md](./trace.md)。
+     */
+    trace?: AgentTrace;
 }
 /**
  * 流式循环的单个 chunk
@@ -239,6 +377,7 @@ interface ReactLoopResult {
  * - `deltaContent` — LLM 增量 token（多次 yield）
  * - `toolCall` — tool 开始执行
  * - `toolResult` — tool 执行完成
+ * - `traceEvent` — trace 事件（`enableTracing=true` 时增量推送,与上述字段互斥）
  * - `done` — 循环结束（只 yield 一次）
  */
 interface ReactLoopStreamChunk {
@@ -254,6 +393,11 @@ interface ReactLoopStreamChunk {
         name: string;
         result: string;
     };
+    /**
+     * trace 事件（`enableTracing=true` 时增量推送）。
+     * 与 deltaContent / toolCall / toolResult / done 互斥,一个 chunk 至多一个字段。
+     */
+    traceEvent?: AgentTraceEvent;
     /** 循环结束 */
     done?: {
         content: string;
@@ -297,6 +441,119 @@ declare function reactLoop(input: string, config: ReactLoopConfig): Promise<Reac
  */
 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;
+    /**
+     * 启用 tracing（默认沿用全局 `config.agent.enableTracing`,全局默认 `true`）。
+     *
+     * 开启时 `ReactLoopResult.trace` / `ReactLoopStreamChunk.traceEvent` 填充
+     * 结构化调用明细,详见 [trace.md](./trace.md)。
+     *
+     * 业务方在生产主路径显式传 `false` 关闭以零开销运行。
+     */
+    enableTracing?: boolean;
+}
+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 配置覆盖
  *
@@ -308,8 +565,16 @@ interface AgentRuntimeConfig {
     maxTurns?: number;
     /** agent 调用 agent 的最大递归深度（默认 3） */
     maxAgentDepth?: number;
-    /** 默认 tool 列表，所有 agent 都可用 */
-    defaultTools?: string[];
+    /**
+     * 启用 tracing 的全局默认值（默认 true）。
+     *
+     * 开启时 `ReactLoopResult.trace` / `ReactLoopStreamChunk.traceEvent` 填充
+     * 结构化调用明细,详见 [trace.md](./trace.md)。
+     *
+     * 单次调用可通过 `AgentRunOptions.enableTracing` 覆盖。
+     * 业务方在生产主路径显式设 `false` 关闭以零开销运行。
+     */
+    enableTracing?: boolean;
 }
 /**
  * tool schema 解析结果
@@ -342,26 +607,34 @@ interface ToolSchemaResolution {
  * 访问器签名与 faapi 核心对称（见 [agent.md](./agent.md) 依赖注入章节）。
  */
 interface AgentDeps {
-    /** LLM provider 实例 */
-    provider: LLMProvider;
+    /** 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 元数据（对应 agentRegistry.getAgent） */
-    getAgent: (name: string) => AgentMetadata | undefined;
+    /** 查 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） */
-    resolveSubAgents: (name: string) => AgentMetadata[];
+    /** 解析 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） */
-    loadAgentModule: (filePath: string, hasConfig: boolean, hasRun: boolean) => Promise<AgentModule>;
+    /** 动态 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>;
 }
@@ -406,30 +679,37 @@ declare class Agent {
      */
     private readonly schemaCache;
     /**
-     * @param deps 运行时依赖（访问器 + provider + config）
+     * @param deps 运行时依赖（访问器 + providers Map + defaultProvider + llms + config）
      * @param depth 递归深度（默认 1 = 根 agent；sub-agent 递归时传入 depth+1）
      */
     constructor(deps: AgentDeps, depth?: number);
     /**
      * 非流式执行——组装 config 调 [reactLoop](./reactLoop.md)
      *
+     * reactLoop 不知 agent 名（只关心循环逻辑）,返回的 `result.trace.agentName` 为空字符串。
+     * 本方法在 reactLoop 返回后填充 `this.deps.agentName`,让顶层 trace 标识"是哪个 agent 跑的"。
+     *
      * @param input 用户输入
-     * @returns 最终结果（content + messages + turns + stopReason + usage）
+     * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens / enableTracing
+     *                （不修改 agent 自身状态,详见 [agentHandle](./agentHandle.md)）
+     * @returns 最终结果（content + messages + turns + stopReason + usage + trace?）
      * @throws {AgentError} agent 未注册
      * @throws {ReactLoopError} 超出 maxTurns
      * @throws {Error} provider.complete 抛错时立即传播
      */
-    run(input: string): Promise<ReactLoopResult>;
+    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): AsyncIterable<ReactLoopStreamChunk>;
+    stream(input: string, options?: AgentRunOptions): AsyncIterable<ReactLoopStreamChunk>;
     /**
      * 把自身包装为 `AgentToolDescriptor` 供 LLM 当 tool 调用
      *
@@ -452,18 +732,39 @@ declare class Agent {
     /**
      * 组装 ReactLoopConfig
      *
-     * 1. 查 agent 元数据（未注册抛 AgentError）
+     * 1. 查 agent 元数据（未注册抛 AgentError）——用 `getAgent` 拿 AgentCore
+     *    (LLM-facing 字段:systemPrompt / model / maxTurns)
      * 2. buildToolDefinitions 组装 tool 列表
-     * 3. config 字段优先级：agent 元数据 > 全局 AgentRuntimeConfig
+     * 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` 去重，先入者保留）：
+     * 合并两个来源（按 `name` 去重，先入者保留）：
      * 1. **resolveAgentTools** —— agent 显式声明的 `tools` 引用
-     * 2. **全局 defaultTools** —— `config.defaultTools` 中的 tool 名（所有 agent 共享）
-     * 3. **sub-agent** —— `resolveSubAgents` 每个包装为 `agent.<name>`
+     * 2. **sub-agent** —— `resolveSubAgents` 每个包装为 `agent.<name>`
      *
      * 每个常规 tool 的 `input`：
      * - `resolveToolSchema` 提供 → 用其 `jsonSchema`
@@ -475,9 +776,12 @@ declare class Agent {
     /**
      * tool 执行路由（由 reactLoop 调用）
      *
-     * - `agent.` 前缀 → {@link executeSubAgent} 递归
+     * - `agent.` 前缀 → {@link executeSubAgent} 递归（含 enableTracing + TracingToolResult 包装）
      * - 常规 tool → `loadToolModule` 加载 handler + 可选 input 校验 → 调用
      *
+     * `enableTracing` 由 [buildLoopConfig](#buildLoopConfig) 闭包捕获传入,用于 sub-agent
+     * 调用时决定是否包装 [TracingToolResult](./trace.md) 携带 sub-trace。
+     *
      * **常规 tool 校验失败**：不抛错，返回 `{ error }` 对象——reactLoop stringify 后
      * 作为 tool 结果回传 LLM，LLM 可据此修正参数重试。
      *
@@ -488,76 +792,26 @@ declare class Agent {
      * 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
+     * 2. sub-agent handler 导出 `run` 时调自定义 `mod.run(args)`（无 trace,与常规 tool 一致）
+     * 3. 无 `run` 时调 `subAgent.run(stringify(args), { enableTracing })` 走默认 reactLoop
      *
-     * 组装 ReAct 循环 config（systemPrompt + tools + maxTurns）→ 调
-     * [reactLoop](./reactLoop.md) → 返回最终结果。
+     * **tracing 路径**：`enableTracing=true` 时,subAgent.run 返回的 `result.trace`（agentName
+     * 已被 `Agent.run` 填为 subName）被包装为 [TracingToolResult](./trace.md) 返回给 reactLoop。
+     * reactLoop 通过 `isTracingToolResult` 识别后发出 `subagent_call` 事件,嵌入 sub-trace
+     * （递归结构,业务方可还原完整调用树）。`enableTracing=false` 时返回 `result.content`
+     * （unknown,与常规 tool 一致,零开销）。
      *
-     * @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 调用
+     * **自定义 run 无 trace**：业务方导出 `run` 函数时直接返回业务结果,无法采集 sub-agent
+     * 内部明细——需 trace 时应让 sub-agent 走默认 reactLoop（不导出 `run`）。
      *
-     * 用于 agent-as-tool 场景：父 agent 把子 agent 包装为 tool,
-     * 加入 LLM 可见 tool 列表,LLM 调用时触发 sub-agent 递归执行。
+     * 自定义 run 接收原始 args 对象；默认 reactLoop 接收 stringify 后的 args
+     * 作为 user 消息（agent-as-tool input 为开放式 JSON）。
      *
-     * @returns `AgentToolDescriptor` 或 `undefined`（agent 未注册）
+     * 加载 handler.js 用 `getAgentEntry`(返回 AgentMetadata,含 filePath/hasRun),
+     * 而非 `getAgent`(返回 AgentCore,无代码加载细节)。DB skill 无文件,
+     * `getAgentEntry` 返回 `undefined`,走默认 reactLoop。
      */
-    asTool(): AgentToolDescriptor | undefined;
+    private executeSubAgent;
 }
 
 /**
@@ -569,7 +823,15 @@ interface AgentHandle {
  *
  * export default {
  *   agent: {
- *     llm: { provider: 'openai', apiKey: process.env.OPENAI_API_KEY, model: 'gpt-4o' },
+ *     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,
  *   },
@@ -578,14 +840,15 @@ interface AgentHandle {
  * ```
  *
  * 插件 setup 时：
- * 1. 读 `config.agent.llm` → `createProvider` → LLMProvider 实例（单例）
- * 2. 读 `config.agent.defaultAgent` / `maxTurns` / `maxAgentDepth` / `defaultTools`
- * 3. 从 `@faapi/faapi` import 注册表/加载器访问器（getAgent / getTool / resolveAgentTools /
+ * 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）
- * 4. `registerAgentHandleFactory` 注册工厂——每次请求时构造 [Agent](./agent.md) 实例注入到
+ * 5. `registerAgentHandleFactory` 注册工厂——每次请求时构造 [Agent](./agent.md) 实例注入到
  *    handler 的 `agent` 参数
  *
- * 配置缺失时（`agent.llm` 或 `agent.defaultAgent` 未设置）跳过工厂注册并打印警告,
+ * 配置缺失时（`agent.llms` 或 `agent.defaultAgent` 未设置）跳过工厂注册并打印警告,
  * handler 的 `agent` 参数注入 `undefined`。
  *
  * 详见 [plugin.md](./plugin.md)。
@@ -599,4 +862,4 @@ interface AgentHandle {
  */
 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 };
+export { Agent, type AgentDeps, AgentError, type AgentHandle, AgentRecursionError, type AgentRunOptions, type AgentRuntimeConfig, type AgentTrace, type AgentTraceEvent, type LLMCompleteRequest, type LLMMessage, type LLMProvider, LLMProviderError, type LLMResponse, type LLMStopReason, type LLMStreamChunk, type LLMToolCall, type LLMToolDefinition, type LLMUsage, type LlmCallEvent, type ReactLoopConfig, ReactLoopError, type ReactLoopResult, type ReactLoopStreamChunk, type SubAgentCallEvent, type ToolCallEvent, type ToolExecutor, type ToolSchemaResolution, type TracingToolResult, createOpenAIProvider, createProvider, agentPlugin as default, isTracingToolResult, reactLoop, reactLoopStream };