@faapi/agent 3.0.0 → 3.2.0

package/dist/index.js

@@ -1,6 +1,6 @@
 // src/providers/openai.ts
 var DEFAULT_BASE_URL = "https://api.openai.com/v1";
-var RESERVED_CONFIG_KEYS = /* @__PURE__ */ new Set(["provider", "apiKey", "model", "baseURL"]);
+var RESERVED_CONFIG_KEYS = /* @__PURE__ */ new Set(["provider", "apiKey", "model", "baseURL", "models"]);
 var LLMProviderError = class extends Error {
   /** HTTP 状态码（网络错误 / JSON 解析错误为 undefined） */
   status;
@@ -17,22 +17,40 @@ function createOpenAIProvider(config) {
   const baseURL = (config.baseURL ?? DEFAULT_BASE_URL).replace(/\/$/, "");
   const apiKey = config.apiKey;
   function buildRequestBody(request) {
+    const modelName = request.model ?? Object.keys(config.models)[0];
+    const modelConfig = modelName ? config.models[modelName] : void 0;
     const body = {
-      model: request.model ?? config.model,
+      model: modelName,
       messages: request.messages.map(toOpenAIMessage)
     };
     if (request.tools && request.tools.length > 0) {
       body.tools = request.tools.map(toOpenAITool);
     }
-    if (request.temperature !== void 0) body.temperature = request.temperature;
-    if (request.maxTokens !== void 0) body.max_tokens = request.maxTokens;
+    const mergedConfig = {};
     for (const key of Object.keys(config)) {
       if (RESERVED_CONFIG_KEYS.has(key)) continue;
       const value = config[key];
+      if (value !== void 0) {
+        mergedConfig[key] = value;
+      }
+    }
+    if (modelConfig) {
+      for (const key of Object.keys(modelConfig)) {
+        if (RESERVED_CONFIG_KEYS.has(key)) continue;
+        const value = modelConfig[key];
+        if (value !== void 0) {
+          mergedConfig[key] = value;
+        }
+      }
+    }
+    for (const key of Object.keys(mergedConfig)) {
+      const value = mergedConfig[key];
       if (value !== void 0 && !(key in body)) {
         body[key] = value;
       }
     }
+    if (request.temperature !== void 0) body.temperature = request.temperature;
+    if (request.maxTokens !== void 0) body.max_tokens = request.maxTokens;
     return body;
   }
   function buildHeaders() {
@@ -299,6 +317,11 @@ function createProvider(config) {
   }
 }
 
+// src/trace.ts
+function isTracingToolResult(value) {
+  return typeof value === "object" && value !== null && value.__trace === true;
+}
+
 // src/reactLoop.ts
 var ReactLoopError = class extends Error {
   /** 配置的 maxTurns 值 */
@@ -343,14 +366,29 @@ function buildRequestExtras(config) {
     maxTokens: config.maxTokens
   };
 }
+function nowMs() {
+  return performance.now();
+}
+function extractSubAgentName(toolName) {
+  const prefix = "agent.";
+  if (toolName.startsWith(prefix)) {
+    return toolName.slice(prefix.length);
+  }
+  return toolName;
+}
 async function reactLoop(input, config) {
+  const enableTracing = config.enableTracing ?? true;
   const messages = buildInitialMessages(input, config.systemPrompt);
   const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
   const extras = buildRequestExtras(config);
   let totalUsage;
   let turns = 0;
+  const traceStartedAt = enableTracing ? nowMs() : 0;
+  const traceEvents = enableTracing ? [] : void 0;
   while (turns < maxTurns) {
     turns++;
+    const llmStartedAt = enableTracing ? nowMs() : 0;
+    const inputSnapshot = enableTracing ? [...messages] : void 0;
     const response = await config.provider.complete({
       messages: [...messages],
       ...extras
@@ -358,23 +396,87 @@ async function reactLoop(input, config) {
     if (response.usage) {
       totalUsage = accumulateUsage(totalUsage, response.usage);
     }
+    if (enableTracing) {
+      const llmEndedAt = nowMs();
+      traceEvents.push({
+        type: "llm_call",
+        turn: turns,
+        startedAt: llmStartedAt,
+        durationMs: llmEndedAt - llmStartedAt,
+        model: config.model ?? "",
+        inputMessages: inputSnapshot,
+        response: response.message,
+        stopReason: response.stopReason,
+        usage: response.usage
+      });
+    }
     messages.push(response.message);
     if (response.stopReason !== "tool_calls" || !response.message.toolCalls) {
+      const traceEndedAt = enableTracing ? nowMs() : 0;
       return {
         content: response.message.content,
         messages,
         turns,
         stopReason: response.stopReason,
-        usage: totalUsage
+        usage: totalUsage,
+        trace: enableTracing ? {
+          agentName: "",
+          startedAt: traceStartedAt,
+          durationMs: traceEndedAt - traceStartedAt,
+          turns,
+          usage: totalUsage,
+          stopReason: response.stopReason,
+          content: response.message.content,
+          events: traceEvents
+        } : void 0
       };
     }
     for (const toolCall of response.message.toolCalls) {
+      const toolStartedAt = enableTracing ? nowMs() : 0;
       let resultStr;
+      let rawResult;
+      let toolErr;
+      let hasError = false;
       try {
-        const result = await config.executeTool(toolCall.name, toolCall.arguments);
-        resultStr = stringifyResult(result);
+        rawResult = await config.executeTool(toolCall.name, toolCall.arguments);
+        if (isTracingToolResult(rawResult)) {
+          resultStr = stringifyResult(rawResult.result);
+        } else {
+          resultStr = stringifyResult(rawResult);
+        }
       } catch (err) {
+        hasError = true;
+        toolErr = err;
         resultStr = stringifyError(err);
+        rawResult = void 0;
+      }
+      if (enableTracing) {
+        const toolEndedAt = nowMs();
+        if (isTracingToolResult(rawResult)) {
+          traceEvents.push({
+            type: "subagent_call",
+            turn: turns,
+            startedAt: toolStartedAt,
+            durationMs: toolEndedAt - toolStartedAt,
+            toolCallId: toolCall.id,
+            agentName: extractSubAgentName(toolCall.name),
+            input: JSON.stringify(toolCall.arguments),
+            trace: rawResult.trace,
+            result: resultStr
+          });
+        } else {
+          traceEvents.push({
+            type: "tool_call",
+            turn: turns,
+            startedAt: toolStartedAt,
+            durationMs: toolEndedAt - toolStartedAt,
+            toolCallId: toolCall.id,
+            name: toolCall.name,
+            arguments: toolCall.arguments,
+            result: resultStr,
+            error: hasError ? stringifyError(toolErr) : void 0
+          });
+        }
       }
       messages.push({
         role: "tool",
@@ -389,6 +491,7 @@ async function reactLoop(input, config) {
   );
 }
 async function* reactLoopStream(input, config) {
+  const enableTracing = config.enableTracing ?? true;
   const messages = buildInitialMessages(input, config.systemPrompt);
   const maxTurns = config.maxTurns ?? DEFAULT_MAX_TURNS;
   const extras = buildRequestExtras(config);
@@ -396,9 +499,12 @@ async function* reactLoopStream(input, config) {
   let turns = 0;
   while (turns < maxTurns) {
     turns++;
+    const llmStartedAt = enableTracing ? nowMs() : 0;
+    const inputSnapshot = enableTracing ? [...messages] : void 0;
     let turnContent = "";
     let toolCalls;
     let finishReason;
+    let turnUsage;
     for await (const chunk of config.provider.stream({
       messages: [...messages],
       ...extras
@@ -415,6 +521,7 @@ async function* reactLoopStream(input, config) {
       }
       if (chunk.usage) {
         totalUsage = accumulateUsage(totalUsage, chunk.usage);
+        turnUsage = chunk.usage;
       }
     }
     const assistantMessage = {
@@ -425,6 +532,22 @@ async function* reactLoopStream(input, config) {
       assistantMessage.toolCalls = toolCalls;
     }
     messages.push(assistantMessage);
+    if (enableTracing) {
+      const llmEndedAt = nowMs();
+      yield {
+        traceEvent: {
+          type: "llm_call",
+          turn: turns,
+          startedAt: llmStartedAt,
+          durationMs: llmEndedAt - llmStartedAt,
+          model: config.model ?? "",
+          inputMessages: inputSnapshot,
+          response: assistantMessage,
+          stopReason: finishReason ?? "other",
+          usage: turnUsage
+        }
+      };
+    }
     if (finishReason !== "tool_calls" || !toolCalls) {
       yield {
         done: {
@@ -438,14 +561,57 @@ async function* reactLoopStream(input, config) {
     }
     for (const toolCall of toolCalls) {
       yield { toolCall: { name: toolCall.name, arguments: toolCall.arguments } };
+      const toolStartedAt = enableTracing ? nowMs() : 0;
       let resultStr;
+      let rawResult;
+      let toolErr;
+      let hasError = false;
       try {
-        const result = await config.executeTool(toolCall.name, toolCall.arguments);
-        resultStr = stringifyResult(result);
+        rawResult = await config.executeTool(toolCall.name, toolCall.arguments);
+        if (isTracingToolResult(rawResult)) {
+          resultStr = stringifyResult(rawResult.result);
+        } else {
+          resultStr = stringifyResult(rawResult);
+        }
       } catch (err) {
+        hasError = true;
+        toolErr = err;
         resultStr = stringifyError(err);
+        rawResult = void 0;
       }
       yield { toolResult: { name: toolCall.name, result: resultStr } };
+      if (enableTracing) {
+        const toolEndedAt = nowMs();
+        if (isTracingToolResult(rawResult)) {
+          yield {
+            traceEvent: {
+              type: "subagent_call",
+              turn: turns,
+              startedAt: toolStartedAt,
+              durationMs: toolEndedAt - toolStartedAt,
+              toolCallId: toolCall.id,
+              agentName: extractSubAgentName(toolCall.name),
+              input: JSON.stringify(toolCall.arguments),
+              trace: rawResult.trace,
+              result: resultStr
+            }
+          };
+        } else {
+          yield {
+            traceEvent: {
+              type: "tool_call",
+              turn: turns,
+              startedAt: toolStartedAt,
+              durationMs: toolEndedAt - toolStartedAt,
+              toolCallId: toolCall.id,
+              name: toolCall.name,
+              arguments: toolCall.arguments,
+              result: resultStr,
+              error: hasError ? stringifyError(toolErr) : void 0
+            }
+          };
+        }
+      }
       messages.push({
         role: "tool",
         content: resultStr,
@@ -496,7 +662,7 @@ var Agent = class _Agent {
    */
   schemaCache = /* @__PURE__ */ new Map();
   /**
-   * @param deps 运行时依赖（访问器 + provider + config）
+   * @param deps 运行时依赖（访问器 + providers Map + defaultProvider + llms + config）
    * @param depth 递归深度（默认 1 = 根 agent；sub-agent 递归时传入 depth+1）
    */
   constructor(deps, depth = 1) {
@@ -506,27 +672,38 @@ var Agent = class _Agent {
   /**
    * 非流式执行——组装 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 抛错时立即传播
    */
-  async run(input) {
-    const config = await this.buildLoopConfig();
-    return reactLoop(input, config);
+  async run(input, options) {
+    const config = await this.buildLoopConfig(options);
+    const result = await reactLoop(input, config);
+    if (result.trace) {
+      result.trace.agentName = this.deps.agentName;
+    }
+    return result;
   }
   /**
    * 流式执行——组装 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 抛错时立即传播
    */
-  async *stream(input) {
-    const config = await this.buildLoopConfig();
+  async *stream(input, options) {
+    const config = await this.buildLoopConfig(options);
     yield* reactLoopStream(input, config);
   }
   /**
@@ -570,32 +747,102 @@ var Agent = 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 解析规则」。
    */
-  async buildLoopConfig() {
+  async buildLoopConfig(options) {
     const meta = this.deps.getAgent(this.deps.agentName);
     if (!meta) {
       throw new AgentError(`Agent "${this.deps.agentName}" is not registered`);
     }
     const tools = await this.buildToolDefinitions();
+    const { provider, model } = this.resolveModelKey(options?.model, meta);
+    const enableTracing = options?.enableTracing ?? this.deps.config?.enableTracing ?? true;
     return {
-      provider: this.deps.provider,
+      provider,
       systemPrompt: meta.systemPrompt,
-      model: meta.model,
+      model,
+      temperature: options?.temperature,
+      maxTokens: options?.maxTokens,
       maxTurns: meta.maxTurns ?? this.deps.config?.maxTurns,
       tools,
-      executeTool: async (name, args) => this.executeTool(name, args)
+      enableTracing,
+      executeTool: async (name, args) => this.executeTool(name, args, enableTracing)
     };
   }
+  /**
+   * 解析 `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 不存在或歧义）
+   */
+  resolveModelKey(key, meta) {
+    if (key === void 0) {
+      return { provider: this.deps.defaultProvider, model: meta.model };
+    }
+    const byProviderKey = this.deps.providers.get(key);
+    if (byProviderKey) {
+      const llmConfig = this.deps.llms[key];
+      const firstModel = llmConfig ? Object.keys(llmConfig.models)[0] : void 0;
+      return { provider: byProviderKey, model: firstModel ?? meta.model };
+    }
+    if (key.includes("/")) {
+      const slashIdx = key.indexOf("/");
+      const providerName = key.slice(0, slashIdx);
+      const modelName = key.slice(slashIdx + 1);
+      const provider = this.deps.providers.get(providerName);
+      if (!provider) {
+        throw new AgentError(`Unknown provider "${providerName}" in model key "${key}"`);
+      }
+      const llmConfig = this.deps.llms[providerName];
+      if (!llmConfig || !llmConfig.models[modelName]) {
+        throw new AgentError(
+          `Model "${modelName}" not found in provider "${providerName}". Declare it in config.agent.llms.${providerName}.models.`
+        );
+      }
+      return { provider, model: modelName };
+    }
+    const matches = [];
+    for (const [providerName, provider] of this.deps.providers) {
+      const llmConfig = this.deps.llms[providerName];
+      if (llmConfig && llmConfig.models[key]) {
+        matches.push({ provider, providerName });
+      }
+    }
+    if (matches.length === 1) {
+      return { provider: matches[0].provider, model: key };
+    }
+    if (matches.length > 1) {
+      throw new AgentError(
+        `Model "${key}" is ambiguous (found in providers: ${matches.map((m) => m.providerName).join(", ")}). Use "provider/model" to disambiguate.`
+      );
+    }
+    throw new AgentError(
+      `Model "${key}" not found in any provider. Declare it in config.agent.llms.*.models.`
+    );
+  }
   /**
    * 组装 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`
@@ -614,20 +861,6 @@ var Agent = class _Agent {
         input: schemaRes?.jsonSchema ?? { type: "object" }
       });
     }
-    const defaultTools = this.deps.config?.defaultTools;
-    if (defaultTools) {
-      for (const toolName of defaultTools) {
-        if (definitions.has(toolName)) continue;
-        const tool = this.deps.getTool(toolName);
-        if (!tool) continue;
-        const schemaRes = await this.getToolSchema(tool);
-        definitions.set(tool.name, {
-          name: tool.name,
-          description: tool.description,
-          input: schemaRes?.jsonSchema ?? { type: "object" }
-        });
-      }
-    }
     for (const subAgent of this.deps.resolveSubAgents(this.deps.agentName)) {
       const name = `agent.${subAgent.name}`;
       if (definitions.has(name)) continue;
@@ -642,17 +875,20 @@ var Agent = 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 可据此修正参数重试。
    *
    * **tool 未找到 / 加载失败**：抛错，被 reactLoop catch 后同样回传 LLM。
    */
-  async executeTool(name, args) {
+  async executeTool(name, args, enableTracing) {
     if (name.startsWith("agent.")) {
-      return this.executeSubAgent(name.slice(6), args);
+      return this.executeSubAgent(name.slice(6), args, enableTracing);
     }
     const tool = this.deps.getTool(name);
     if (!tool) {
@@ -674,13 +910,26 @@ var Agent = class _Agent {
    * sub-agent 递归执行
    *
    * 1. `maxAgentDepth` 防护——超限抛 {@link AgentRecursionError}
-   * 2. sub-agent handler 导出 `run` 时调自定义 `mod.run(args)`
-   * 3. 无 `run` 时调 `subAgent.run(JSON.stringify(args))` 走默认 reactLoop
+   * 2. sub-agent handler 导出 `run` 时调自定义 `mod.run(args)`（无 trace,与常规 tool 一致）
+   * 3. 无 `run` 时调 `subAgent.run(stringify(args), { enableTracing })` 走默认 reactLoop
+   *
+   * **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 一致,零开销）。
+   *
+   * **自定义 run 无 trace**：业务方导出 `run` 函数时直接返回业务结果,无法采集 sub-agent
+   * 内部明细——需 trace 时应让 sub-agent 走默认 reactLoop（不导出 `run`）。
    *
    * 自定义 run 接收原始 args 对象；默认 reactLoop 接收 stringify 后的 args
    * 作为 user 消息（agent-as-tool input 为开放式 JSON）。
+   *
+   * 加载 handler.js 用 `getAgentEntry`(返回 AgentMetadata,含 filePath/hasRun),
+   * 而非 `getAgent`(返回 AgentCore,无代码加载细节)。DB skill 无文件,
+   * `getAgentEntry` 返回 `undefined`,走默认 reactLoop。
    */
-  async executeSubAgent(subName, args) {
+  async executeSubAgent(subName, args, enableTracing) {
     const newDepth = this.depth + 1;
     const maxDepth = this.deps.config?.maxAgentDepth ?? DEFAULT_MAX_AGENT_DEPTH;
     if (newDepth > maxDepth) {
@@ -688,14 +937,23 @@ var Agent = class _Agent {
     }
     const subDeps = { ...this.deps, agentName: subName };
     const subAgent = new _Agent(subDeps, newDepth);
-    const meta = this.deps.getAgent(subName);
-    if (meta?.hasRun) {
-      const mod = await this.deps.loadAgentModule(meta.filePath, meta.hasConfig, meta.hasRun);
+    const entry = this.deps.getAgentEntry(subName);
+    if (entry?.hasRun) {
+      const mod = await this.deps.loadAgentModule(entry.filePath, entry.hasRun);
       if (mod.run) {
         return await mod.run(args);
       }
     }
-    const result = await subAgent.run(typeof args === "string" ? args : JSON.stringify(args));
+    const result = await subAgent.run(typeof args === "string" ? args : JSON.stringify(args), {
+      enableTracing
+    });
+    if (enableTracing && result.trace) {
+      return {
+        __trace: true,
+        result: result.content,
+        trace: result.trace
+      };
+    }
     return result.content;
   }
 };
@@ -704,6 +962,7 @@ var Agent = class _Agent {
 import {
   registerAgentHandleFactory,
   getAgent,
+  getAgentEntry,
   getTool,
   resolveAgentTools,
   resolveSubAgents,
@@ -736,9 +995,9 @@ var agentPlugin = {
   name: "@faapi/agent",
   setup(ctx) {
     const agentConfig = readAgentConfig(ctx);
-    if (!agentConfig?.llm) {
+    if (!agentConfig?.llms) {
       console.warn(
-        "! @faapi/agent: config.agent.llm not configured, agent parameter injection disabled"
+        "! @faapi/agent: config.agent.llms not configured, agent parameter injection disabled"
       );
       return;
     }
@@ -748,36 +1007,52 @@ var agentPlugin = {
       );
       return;
     }
-    const provider = createProvider(agentConfig.llm);
+    const llms = agentConfig.llms;
+    const providers = /* @__PURE__ */ new Map();
+    for (const [name, llmConfig] of Object.entries(llms)) {
+      providers.set(name, createProvider(llmConfig));
+    }
+    const defaultLlm = agentConfig.defaultLlm ?? Object.keys(llms)[0];
+    const defaultProvider = providers.get(defaultLlm);
+    if (!defaultProvider) {
+      console.warn(
+        `! @faapi/agent: config.agent.defaultLlm "${defaultLlm}" not found in llms, agent parameter injection disabled`
+      );
+      return;
+    }
     const runtimeConfig = {
       maxTurns: agentConfig.maxTurns,
-      maxAgentDepth: agentConfig.maxAgentDepth,
-      defaultTools: agentConfig.defaultTools
+      maxAgentDepth: agentConfig.maxAgentDepth
     };
     const rootDir = ctx.rootDir;
     const defaultAgent = agentConfig.defaultAgent;
     const resolveToolSchema = (tool) => resolveToolSchemaImpl(tool, rootDir);
     registerAgentHandleFactory(() => {
       return new Agent({
-        provider,
+        providers,
+        defaultProvider,
+        llms,
+        defaultLlm,
         agentName: defaultAgent,
         rootDir,
         config: runtimeConfig,
         // 注册表/加载器访问器——从 @faapi/faapi import 的单例模块
         // createAppBase 启动时已水合 agentRegistry / toolRegistry
+        // getAgent 返回 AgentCore(LLM-facing);getAgentEntry 返回 AgentMetadata(含 filePath/hasRun,供加载 handler.js)
         getAgent,
+        getAgentEntry,
         getTool,
         resolveAgentTools,
         resolveSubAgents,
         // 加载器包装：注入 rootDir 用于 dev 按需编译模式
         loadToolModule: (filePath, functionName) => loadToolModule(filePath, functionName, rootDir),
-        loadAgentModule: (filePath, hasConfig, hasRun) => loadAgentModule(filePath, hasConfig, hasRun, rootDir),
+        loadAgentModule: (filePath, hasRun) => loadAgentModule(filePath, hasRun, rootDir),
         // tool schema 解析（zod.js → JSON Schema + safeParse 校验）
         resolveToolSchema
       });
     });
     console.log(
-      `- @faapi/agent: default agent "${defaultAgent}" available via agent parameter injection`
+      `- @faapi/agent: default agent "${defaultAgent}" (provider: ${defaultLlm}) available via agent parameter injection`
     );
   }
 };
@@ -791,6 +1066,7 @@ export {
   createOpenAIProvider,
   createProvider,
   plugin_default as default,
+  isTracingToolResult,
   reactLoop,
   reactLoopStream
 };