@faapi/agent 4.3.0 → 4.5.0

package/dist/index.js

@@ -849,6 +849,21 @@ async function* reactLoopStream(input, config) {
 // src/agent.ts
 var DEFAULT_MAX_AGENT_DEPTH = 3;
 var VALID_MESSAGE_ROLES = /* @__PURE__ */ new Set(["system", "user", "assistant", "tool"]);
+function isProviderInstance(value) {
+  return typeof value === "object" && value !== null && typeof value.complete === "function" && typeof value.stream === "function";
+}
+function isProviderConfig(value) {
+  return typeof value === "object" && value !== null && typeof value.provider === "string";
+}
+function materializeProvider(external) {
+  if (isProviderInstance(external)) return external;
+  if (isProviderConfig(external)) {
+    return createProvider({ ...external, models: external.models ?? {} });
+  }
+  throw new AgentError(
+    'options.provider must be an LlmConfig object (with a string "provider" field) or an LLMProvider instance (with complete/stream methods)'
+  );
+}
 function validateResumeHistory(messages) {
   messages.forEach((message, index) => {
     if (!VALID_MESSAGE_ROLES.has(message.role)) {
@@ -904,7 +919,7 @@ var Agent = class _Agent {
    */
   schemaCache = /* @__PURE__ */ new Map();
   /**
-   * @param deps 运行时依赖（访问器 + providers Map + defaultProvider + llms + config）
+   * @param deps 运行时依赖（访问器 + providers Map + llms + config）
    * @param depth 递归深度（默认 1 = 根 agent；sub-agent 递归时传入 depth+1）
    */
   constructor(deps, depth = 1) {
@@ -915,15 +930,17 @@ var Agent = class _Agent {
    * 非流式执行——组装 config 调 [reactLoop](./reactLoop.md)
    *
    * reactLoop 不知 agent 名（只关心循环逻辑）,返回的 `result.trace.agentName` 为空字符串。
-   * 本方法在 reactLoop 返回后填充 `this.deps.agentName`,让顶层 trace 标识"是哪个 agent 跑的"。
+   * 本方法在 reactLoop 返回后填充 `options.agent`,让顶层 trace 标识"是哪个 agent 跑的"。
    *
    * @param input 用户输入（可选——续跑场景不传新输入；input 与 `options.messages`
    *              都为空时抛 `AgentError`）
-   * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens /
-   *                messages / enableTracing
+   * @param options 本次调用配置——`agent`（agent 名,必须显式传,无默认 agent）/
+   *                provider（外部 provider）/ model（字符串 key）/ temperature /
+   *                maxTokens / messages / enableTracing
    *                （不修改 agent 自身状态,详见 [agentHandle](./agentHandle.md)）
    * @returns 最终结果（content + messages + turns + stopReason + usage + trace?）
-   * @throws {AgentError} agent 未注册；input 与 messages 都为空；续跑历史结构非法
+   * @throws {AgentError} 未传 options.agent；agent 未注册；input 与 messages 都为空；
+   *                      续跑历史结构非法；provider/model 无法解析
    * @throws {ReactLoopError} 超出 maxTurns（`error.messages` 携带完整历史，可续跑）
    * @throws {AgentAbortError} 中断（`error.messages` 携带断点历史，可续跑）
    * @throws {Error} provider.complete 抛错时立即传播
@@ -932,7 +949,7 @@ var Agent = class _Agent {
     const config = await this.buildLoopConfig(input, options);
     const result = await reactLoop(input, config);
     if (result.trace) {
-      result.trace.agentName = options?.agent ?? this.deps.agentName;
+      result.trace.agentName = options?.agent ?? "";
     }
     return result;
   }
@@ -941,10 +958,12 @@ var Agent = class _Agent {
    *
    * @param input 用户输入（可选——续跑场景不传新输入；input 与 `options.messages`
    *              都为空时抛 `AgentError`）
-   * @param options 临时覆盖本次调用的 model（字符串 key）/ temperature / maxTokens /
-   *                messages（不修改 agent 自身状态,详见 [agentHandle](./agentHandle.md)）
+   * @param options 本次调用配置——`agent`（必须显式传）/ provider / model /
+   *                temperature / maxTokens / messages
+   *                （不修改 agent 自身状态,详见 [agentHandle](./agentHandle.md)）
    * @yields 流式 chunk（deltaContent / toolCall / toolResult / done）
-   * @throws {AgentError} agent 未注册；input 与 messages 都为空；续跑历史结构非法
+   * @throws {AgentError} 未传 options.agent；agent 未注册；input 与 messages 都为空；
+   *                      续跑历史结构非法；provider/model 无法解析
    * @throws {ReactLoopError} 超出 maxTurns（`error.messages` 携带完整历史，可续跑）
    * @throws {AgentAbortError} 中断（`error.messages` 携带断点历史，可续跑）
    * @throws {Error} provider.stream 抛错时立即传播
@@ -954,15 +973,16 @@ var Agent = class _Agent {
     yield* reactLoopStream(input, config);
   }
   /**
-   * 把自身包装为 `AgentToolDescriptor` 供 LLM 当 tool 调用
+   * 把指定 agent 包装为 `AgentToolDescriptor` 供 LLM 当 tool 调用
    *
    * 与 [agentRegistry.asTool](../../faapi/src/injection/agentRegistry.md) 同构——
    * Agent 类自带此方法便于在注入器场景直接调用（不必再过注册表）。
    *
+   * @param name agent 名（显式指定——无默认 agent）
    * @returns `AgentToolDescriptor` 或 `undefined`（agent 未注册）
    */
-  asTool() {
-    const meta = this.deps.getAgent(this.deps.agentName);
+  asTool(name) {
+    const meta = this.deps.getAgent(name);
     if (!meta) return void 0;
     return {
       kind: "agent",
@@ -994,21 +1014,19 @@ var Agent = class _Agent {
   /**
    * 组装 ReactLoopConfig
    *
-   * 1. 解析有效 agent 名：`options.agent` > `deps.agentName`（`config.agent.defaultAgent`）
+   * 1. 解析有效 agent 名：`options.agent`（必须显式传——无默认 agent,不传抛 AgentError）
    * 2. 查 agent 元数据（未注册抛 AgentError）——用 `getAgent` 拿 AgentCore
    *    (LLM-facing 字段:systemPrompt / model / maxTurns)
    * 3. buildToolDefinitions 组装 tool 列表（用有效 agent 名查 tools / sub-agents）
-   * 4. config 字段优先级（高 → 低）：`options` > agent 元数据 > 全局 AgentRuntimeConfig / deps.defaultProvider
+   * 4. config 字段优先级（高 → 低）：`options` > agent 元数据 > 全局 AgentRuntimeConfig
    *
-   * `options.model` 是字符串 key,由 {@link resolveModelKey} 解析为 provider + model
-   * （支持 llms key 精确匹配 / `provider/model` 一体化 / 纯 model 名模糊匹配）。
-   * 不传 `options.model` 时用 `deps.defaultProvider` + agent 元数据 `config.model`。
+   * `options.provider`（外部 provider）存在时由 {@link resolveExternalProvider} 物化,
+   * 优先级最高——`options.model` 变为原始 model 名原样透传（不解析 llms key）。
+   * 否则 `options.model` 是字符串 key,由 {@link resolveModelKey} 解析为 provider + model
+   * （支持 llms key 精确匹配 / `provider/model` 一体化 / 纯 model 名模糊匹配；
+   * 未传 `options.model` 时用 agent 元数据 `config.model` 作为缺省 key）。
    * 详见 [agentHandle.md](./agentHandle.md) 的「`options.model` 字符串 key 解析规则」。
    *
-   * `options.agent` 覆盖本次调用的 agent 名——不传时用 `deps.agentName`（来自
-   * `config.agent.defaultAgent`）。`defaultAgent` 未设且 `options.agent` 未传时抛
-   * `AgentError`。
-   *
    * **输入守卫**（续跑入口,见 [reactLoop.md](./reactLoop.md) 中断恢复章节）：
    * `input` 与 `options.messages` 都为空时抛 `AgentError`（不发送空请求）；
    * `options.messages` 提供时先经 `validateResumeHistory` 结构校验,非法抛
@@ -1023,14 +1041,20 @@ var Agent = class _Agent {
     if (options?.messages?.length) {
       validateResumeHistory(options.messages);
     }
-    const agentName = options?.agent ?? this.deps.agentName;
+    const agentName = options?.agent;
+    if (!agentName) {
+      throw new AgentError(
+        'agent.run/stream requires options.agent (no default agent) \u2014 pass { agent: "name" } to specify which agent to run'
+      );
+    }
     const meta = this.deps.getAgent(agentName);
     if (!meta) {
       throw new AgentError(`Agent "${agentName}" is not registered`);
     }
     const tools = await this.buildToolDefinitions(agentName);
-    const { provider, model } = this.resolveModelKey(options?.model, meta);
+    const { provider, model } = options?.provider !== void 0 ? this.resolveExternalProvider(options.provider, options?.model) : this.resolveModelKey(options?.model, meta);
     const enableTracing = options?.enableTracing ?? this.deps.config?.enableTracing ?? false;
+    const callCtx = { agentName, enableTracing, provider, model };
     return {
       provider,
       systemPrompt: meta.systemPrompt,
@@ -1042,41 +1066,77 @@ var Agent = class _Agent {
       signal: options?.signal,
       messages: options?.messages,
       enableTracing,
-      executeTool: async (name, args) => this.executeTool(name, args, enableTracing)
+      executeTool: async (name, args) => this.executeTool(name, args, callCtx)
     };
   }
+  /**
+   * 解析外部 provider（`options.provider`）→ provider + model
+   *
+   * 规则见 [agentHandle.md](./agentHandle.md) 的「`options.provider` 外部 provider」章节：
+   * - `LLMProvider` 实例 → 直接使用,`modelKey` 原样透传（可为 `undefined`,自定义 provider 自决）
+   * - `LlmConfig` 配置对象 → `createProvider` 现场创建,`modelKey` 原样透传；
+   *   缺省回落该 config `models` 第一个 key,两者皆无抛 `AgentError`（早失败,不发请求）
+   * - `modelKey` 不做 llms key 解析、不拆 `/`（支持 OpenRouter 等带斜杠的 model id）
+   *
+   * 仅本次调用生效：不进 providers Map、sub-agent 递归不继承（executeSubAgent 构造
+   * subDeps 时不携带 options,sub-agent 走默认解析链路）。
+   *
+   * @throws {AgentError} provider 形式非法；LlmConfig 形式下 model 缺失
+   */
+  resolveExternalProvider(external, modelKey) {
+    const provider = materializeProvider(external);
+    if (isProviderInstance(external)) {
+      return { provider, model: modelKey };
+    }
+    const firstModel = Object.keys(external.models ?? {})[0];
+    const model = modelKey ?? firstModel;
+    if (model === void 0) {
+      throw new AgentError(
+        "External provider requires a model: pass options.model or declare models in the provider config"
+      );
+    }
+    return { provider, model };
+  }
   /**
    * 解析 `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
+   * 规则见 [agentHandle.md](./agentHandle.md) 的「`options.model` 字符串 key 解析规则」。
+   * 无默认 provider——`key` 未传时用 agent 元数据 `config.model` 作为缺省 key；
+   * 两者皆无抛 `AgentError`（要求调用方传 `options.model` 或 `options.provider`）。
+   * 1. 精确匹配 `deps.providers` 的 key → 该 provider + 其 `models` 第一个 key
+   *    （该 provider 未声明 `models` 时回落 `meta.model`）
+   * 2. 含 `/` → `provider/model` 形式,`deps.providers.get(provider)` + 该 model
    *    （要求该 model 在 `deps.llms[provider].models` 里）
-   * 4. 不含 `/` 且非 provider key → 在所有 provider 的 `models` 里按 model 名查找
+   * 3. 不含 `/` 且非 provider key → 在所有 provider 的 `models` 里按 model 名查找
    *    - 唯一 → 该 provider + 该 model
    *    - 多个 → 抛 `AgentError`（要求用 `provider/model` 消歧）
    *    - 无 → 抛 `AgentError`
    *
-   * @throws {AgentError} key 解析失败（provider/model 不存在或歧义）
+   * @throws {AgentError} key 与 `meta.model` 均缺省；key 解析失败（provider/model
+   *   不存在或歧义）
    */
   resolveModelKey(key, meta) {
-    if (key === void 0) {
-      return { provider: this.deps.defaultProvider, model: meta.model };
+    const effectiveKey = key ?? meta.model;
+    if (effectiveKey === void 0) {
+      throw new AgentError(
+        'No LLM provider resolved: pass options.model (a provider key / "provider/model" / model name from config.agent.llms), options.provider (external provider), or declare model in the agent config'
+      );
     }
-    const byProviderKey = this.deps.providers.get(key);
+    const byProviderKey = this.deps.providers.get(effectiveKey);
     if (byProviderKey) {
-      const llmConfig = this.deps.llms[key];
+      const llmConfig = this.deps.llms[effectiveKey];
       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);
+    if (effectiveKey.includes("/")) {
+      const slashIdx = effectiveKey.indexOf("/");
+      const providerName = effectiveKey.slice(0, slashIdx);
+      const modelName = effectiveKey.slice(slashIdx + 1);
       const provider = this.deps.providers.get(providerName);
       if (!provider) {
-        throw new AgentError(`Unknown provider "${providerName}" in model key "${key}"`);
+        throw new AgentError(
+          `Unknown provider "${providerName}" in model key "${effectiveKey}". Declare it in config.agent.llms, or pass options.provider to use an external provider.`
+        );
       }
       const llmConfig = this.deps.llms[providerName];
       if (!llmConfig || !llmConfig.models[modelName]) {
@@ -1089,20 +1149,20 @@ var Agent = class _Agent {
     const matches = [];
     for (const [providerName, provider] of this.deps.providers) {
       const llmConfig = this.deps.llms[providerName];
-      if (llmConfig && llmConfig.models[key]) {
+      if (llmConfig && llmConfig.models[effectiveKey]) {
         matches.push({ provider, providerName });
       }
     }
     if (matches.length === 1) {
-      return { provider: matches[0].provider, model: key };
+      return { provider: matches[0].provider, model: effectiveKey };
     }
     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.`
+        `Model "${effectiveKey}" 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.`
+      `Model "${effectiveKey}" not found in any provider. Declare it in config.agent.llms.*.models, or pass options.provider to use an external provider.`
     );
   }
   /**
@@ -1148,15 +1208,16 @@ var Agent = class _Agent {
    * - `agent.` 前缀 → {@link executeSubAgent} 递归（含 enableTracing + TracingToolResult 包装）
    * - 常规 tool → `loadToolModule` 加载 handler + 可选 input 校验 → 调用
    *
-   * `enableTracing` 由 [buildLoopConfig](#buildLoopConfig) 闭包捕获传入,用于 sub-agent
-   * 调用时决定是否包装 [TracingToolResult](./trace.md) 携带 sub-trace。
+   * `callCtx` 由 [buildLoopConfig](#buildLoopConfig) 闭包捕获传入——本次调用的有效
+   * agent 名（白名单校验）、enableTracing（sub-agent tracing 包装）与解析出的
+   * provider/model（sub-agent 递归继承）。常规 tool 不需要 tracing 包装,直接返回结果。
    *
    * **常规 tool 校验失败**：不抛错，返回 `{ error }` 对象——reactLoop stringify 后
    * 作为 tool 结果回传 LLM，LLM 可据此修正参数重试。
    *
    * **tool 未找到 / 加载失败**：抛错，被 reactLoop catch 后同样回传 LLM。
    */
-  async executeTool(rawName, rawArgs, enableTracing) {
+  async executeTool(rawName, rawArgs, callCtx) {
     const name = rawName;
     let args = rawArgs;
     const guard = this.deps.config?.beforeToolCall?.(name, args, this.deps.ctx);
@@ -1165,19 +1226,19 @@ var Agent = class _Agent {
       if ("args" in guard) args = guard.args;
     }
     const declared = /* @__PURE__ */ new Set();
-    for (const tool2 of this.deps.resolveAgentTools(this.deps.agentName)) {
+    for (const tool2 of this.deps.resolveAgentTools(callCtx.agentName)) {
       declared.add(tool2.name);
     }
-    for (const sub of this.deps.resolveSubAgents(this.deps.agentName)) {
+    for (const sub of this.deps.resolveSubAgents(callCtx.agentName)) {
       declared.add(`agent.${sub.name}`);
     }
     if (!declared.has(name)) {
       return {
-        error: `Tool "${name}" is not declared by agent "${this.deps.agentName}" (add it to the agent's tools/agents declaration)`
+        error: `Tool "${name}" is not declared by agent "${callCtx.agentName}" (add it to the agent's tools/agents declaration)`
       };
     }
     if (name.startsWith("agent.")) {
-      return await this.executeSubAgent(name.slice(6), args, enableTracing);
+      return await this.executeSubAgent(name.slice(6), args, callCtx);
     }
     const tool = this.deps.getTool(name);
     if (!tool) {
@@ -1202,7 +1263,9 @@ var Agent = class _Agent {
    *
    * 1. `maxAgentDepth` 防护——超限抛 {@link AgentRecursionError}
    * 2. sub-agent handler 导出 `run` 时调自定义 `mod.run(args)`（无 trace,与常规 tool 一致）
-   * 3. 无 `run` 时调 `subAgent.run(stringify(args), { enableTracing })` 走默认 reactLoop
+   * 3. 无 `run` 时调 `subAgent.run(stringify(args), { agent, provider, model, enableTracing })`
+   *    走默认 reactLoop——继承父调用的 provider,sub 元数据声明 `model` 时优先用自身的,
+   *    未声明时沿用父 model
    *
    * **tracing 路径**：`enableTracing=true` 时,subAgent.run 返回的 `result.trace`（agentName
    * 已被 `Agent.run` 填为 subName）被包装为 [TracingToolResult](./trace.md) 返回给 reactLoop。
@@ -1220,14 +1283,13 @@ var Agent = class _Agent {
    * 而非 `getAgent`(返回 AgentCore,无代码加载细节)。DB skill 无文件,
    * `getAgentEntry` 返回 `undefined`,走默认 reactLoop。
    */
-  async executeSubAgent(subName, args, enableTracing) {
+  async executeSubAgent(subName, args, callCtx) {
     const newDepth = this.depth + 1;
     const maxDepth = this.deps.config?.maxAgentDepth ?? DEFAULT_MAX_AGENT_DEPTH;
     if (newDepth > maxDepth) {
       throw new AgentRecursionError(maxDepth, newDepth);
     }
-    const subDeps = { ...this.deps, agentName: subName };
-    const subAgent = new _Agent(subDeps, newDepth);
+    const subAgent = new _Agent(this.deps, newDepth);
     const entry = this.deps.getAgentEntry(subName);
     if (entry?.hasRun) {
       const mod = await this.deps.loadAgentModule(entry.filePath, entry.hasRun);
@@ -1237,11 +1299,15 @@ var Agent = class _Agent {
         return result2;
       }
     }
+    const subMeta = this.deps.getAgent(subName);
     const result = await subAgent.run(typeof args === "string" ? args : JSON.stringify(args), {
-      enableTracing
+      agent: subName,
+      provider: callCtx.provider,
+      model: subMeta?.model ?? callCtx.model,
+      enableTracing: callCtx.enableTracing
     });
     this.deps.config?.afterToolCall?.(`agent.${subName}`, args, result.content, this.deps.ctx);
-    if (enableTracing && result.trace) {
+    if (callCtx.enableTracing && result.trace) {
       return {
         __trace: true,
         result: result.content,
@@ -1286,14 +1352,12 @@ var agentPlugin = {
   setup(ctx) {
     const registries = ctx.registries;
     const agentConfig = readAgentConfig(ctx);
-    if (!agentConfig?.llms) {
-      console.warn(
-        "! @faapi/agent: config.agent.llms not configured, agent parameter injection disabled"
+    const llms = agentConfig?.llms ?? {};
+    if (Object.keys(llms).length === 0) {
+      console.log(
+        "- @faapi/agent: no llms configured \u2014 use agent.run(input, { agent, provider }) to pass an external provider per call"
       );
-      return;
     }
-    const defaultAgent = agentConfig.defaultAgent ?? "";
-    const llms = agentConfig.llms;
     const providers = /* @__PURE__ */ new Map();
     for (const [name, llmConfig] of Object.entries(llms)) {
       if (!llmConfig.apiKey || llmConfig.apiKey.trim() === "") {
@@ -1303,22 +1367,14 @@ var agentPlugin = {
       }
       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,
-      maxHistoryTokens: agentConfig.maxHistoryTokens,
+      maxTurns: agentConfig?.maxTurns,
+      maxAgentDepth: agentConfig?.maxAgentDepth,
+      maxHistoryTokens: agentConfig?.maxHistoryTokens,
       // 鉴权钩子（authHooks,见 ./authHooks.md）——业务方在 config.agent 声明
-      beforeToolCall: agentConfig.beforeToolCall,
-      afterToolCall: agentConfig.afterToolCall,
-      filterTools: agentConfig.filterTools
+      beforeToolCall: agentConfig?.beforeToolCall,
+      afterToolCall: agentConfig?.afterToolCall,
+      filterTools: agentConfig?.filterTools
     };
     const rootDir = ctx.rootDir;
     const schemaCache = /* @__PURE__ */ new Map();
@@ -1341,10 +1397,7 @@ var agentPlugin = {
     ctx.registries.agentHandle.register((ctx2) => {
       return new Agent({
         providers,
-        defaultProvider,
         llms,
-        defaultLlm,
-        agentName: defaultAgent ?? "",
         rootDir,
         config: runtimeConfig,
         // ctx 传递链（authHooks）：捕获请求上下文,tool handler / sub-agent /
@@ -1365,7 +1418,7 @@ var agentPlugin = {
       });
     });
     console.log(
-      defaultAgent ? `- @faapi/agent: default agent "${defaultAgent}" (provider: ${defaultLlm}) available via agent parameter injection` : `- @faapi/agent: no defaultAgent set \u2014 use agent.run(input, { agent: 'name' }) to specify agent (provider: ${defaultLlm})`
+      Object.keys(llms).length > 0 ? `- @faapi/agent: providers [${Object.keys(llms).join(", ")}] \u2014 call agent.run(input, { agent, model }) to execute (no default agent/provider)` : "- @faapi/agent: no llms configured \u2014 use agent.run(input, { agent, provider }) to pass an external provider per call"
     );
   }
 };