@faapi/agent 4.3.0 → 4.5.0

package/README.md

@@ -44,12 +44,13 @@ import type { FaapiConfig } from '@faapi/faapi';
 
 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,
+        models: { 'gpt-4o': {} },
+      },
     },
-    defaultAgent: 'researcher',
     maxTurns: 10,
     maxAgentDepth: 3,
   },
@@ -57,6 +58,18 @@ export default {
 } satisfies FaapiConfig;
 ```
 
+无默认 agent / 默认 provider——handler 调用时显式指定 agent 名与 model/provider：
+
+```ts
+// src/api/chat/handler.ts
+import type { AgentHandle } from '@faapi/agent';
+
+export async function POST(agent: AgentHandle, body: { input: string }) {
+  const result = await agent.run(body.input, { agent: 'researcher', model: 'gpt-4o' });
+  return { content: result.content, turns: result.turns };
+}
+```
+
 CLI 启动时动态加载——未安装时自动跳过，不影响核心功能。需单独安装：`pnpm add @faapi/agent`。
 
 ## 多 agent 组织

package/dist/index.d.ts

@@ -510,21 +510,23 @@ declare function reactLoopStream(input: string | undefined, config: ReactLoopCon
  *
  * // src/api/chat/handler.ts
  * export function POST(agent: AgentHandle, body: { input: string }) {
- *   const result = await agent.run(body.input);
+ *   const result = await agent.run(body.input, { agent: 'researcher', model: 'gpt-4o' });
  *   return { content: result.content, turns: result.turns };
  * }
  * ```
  *
- * 工厂未注册（`@faapi/agent` 插件未加载或 `config.agent.llm` / `defaultAgent` 未配置）
- * 时注入 `undefined`,handler 需自行处理。
+ * 仅在 `@faapi/agent` 插件未加载时注入 `undefined`,handler 需自行处理。
+ * `config.agent.llms` 未配置时工厂照常注册（外部 provider 模式）——
+ * `agent.run/stream` 需调用方传 `options.provider` 才能调用 LLM。
+ * 无默认 agent——每次 `run` / `stream` 必须显式传 `options.agent`。
  *
  * 详见 [agentHandle.md](./agentHandle.md)。
  */
 /**
- * `agent.run` / `agent.stream` 的 options 参数——临时覆盖本次调用的 LLM 配置
+ * `agent.run` / `agent.stream` 的 options 参数——本次调用的 LLM 配置
  *
- * 所有字段可选,不传或 `undefined` 时回落到下一优先级（agent 元数据 → 全局配置）。
- * **不修改 agent 自身状态**——下一次调用仍用默认配置。
+ * `agent` 必须显式传（无默认 agent）；其余字段可选,不传或 `undefined` 时回落到
+ * 下一优先级（agent 元数据 → 全局配置）。**不修改 agent 自身状态**。
  *
  * `model` 是字符串 key,支持三种形式（解析规则见 [agentHandle.md](./agentHandle.md) 的
  * 「`options.model` 字符串 key 解析规则」）：
@@ -532,23 +534,20 @@ declare function reactLoopStream(input: string | undefined, config: ReactLoopCon
  * - `provider/model` 一体化（如 `'openai/gpt-4o'`）
  * - 纯 model 名（如 `'gpt-4o'`）—— 在所有 provider 的 `models` 里查找,唯一时切到对应 provider
  *
+ * 不传 `model` 时用 agent 元数据 `config.model` 作为缺省 key 参与同一套解析。
  * 优先级（高 → 低）：`options` > agent 元数据（`config.model` / `config.maxTurns`）> 全局
- * `AgentRuntimeConfig` / `defaultLlm` provider。详见 [agentHandle.md](./agentHandle.md) 的
- * Run-level 覆盖优先级表。
- *
- * `agent` 字段覆盖本次调用的 agent 名（不传时用 `config.agent.defaultAgent`，
- * 未设 defaultAgent 时必须显式传入）。
+ * `AgentRuntimeConfig`。详见 [agentHandle.md](./agentHandle.md) 的 Run-level 覆盖优先级表。
  *
  * @example
  * ```ts
+ * // 指定 agent（必须——无默认 agent）
+ * await agent.run(input, { agent: 'researcher' });
+ *
  * // 按请求切模型（纯 model 名,在 llms 里唯一时切到对应 provider）
- * await agent.run(input, { model: 'gpt-4o-mini' });
+ * await agent.run(input, { agent: 'researcher', model: 'gpt-4o-mini' });
  *
  * // provider/model 一体化形式（精确切换）
- * await agent.run(input, { model: 'anthropic/claude-3-5-sonnet' });
- *
- * // 指定 agent（不依赖 defaultAgent 配置）
- * await agent.run(input, { agent: 'researcher' });
+ * await agent.run(input, { agent: 'researcher', model: 'anthropic/claude-3-5-sonnet' });
  * ```
  */
 interface AgentRunOptions {
@@ -560,18 +559,41 @@ interface AgentRunOptions {
      */
     signal?: AbortSignal;
     /**
-     * 覆盖本次调用的 agent 名（从 agentRegistry 查找对应元数据 / tools / sub-agents）
+     * 本次调用的 agent 名（必须显式传——config.agent 无 defaultAgent 默认值）
      *
-     * 不传时用 `config.agent.defaultAgent`。`defaultAgent` 未设时必须显式传入，
-     * 否则抛 `AgentError`。
+     * 从 agentRegistry 查找对应元数据 / tools / sub-agents。
+     * 不传抛 `AgentError`。
      */
     agent?: string;
     /**
      * 切换 provider + model 的字符串 key（支持 llms key / `provider/model` / 纯 model 名）
      *
-     * 不传时用 `defaultLlm` provider + agent 元数据 `config.model`。
+     * 不传时用 agent 元数据 `config.model` 作为缺省 key 参与解析；
+     * 两者皆无且未传 `provider` 时抛 `AgentError`（无默认 provider）。
+     * `provider` 字段存在时本字段变为「原始 model 名」原样透传给外部 provider
+     * （不做 llms key 解析,支持带 / 的 model id），详见 {@link AgentRunOptions.provider}。
      */
     model?: string;
+    /**
+     * 外部 provider（本次调用临时使用,优先级最高——完全不查 `config.agent.llms`）
+     *
+     * 两种形式（运行时按形状判别,两者皆非抛 `AgentError`）：
+     * - `LlmConfig` 对象（含字符串 `provider` 字段）→ 现场调 `createProvider` 创建适配器
+     *   （浅拷贝 + `models` 兜底 `{}`,不改调用方对象）,适用于 BYOK（用户自带 apiKey）/
+     *   按请求指定 baseURL 网关
+     * - `LLMProvider` 实例（有 `complete` / `stream` 方法）→ 直接使用,适用于框架未内置
+     *   适配器的 LLM 服务（内部自研模型网关等）
+     *
+     * 传入时 `options.model` 语义变为「原始 model 名」——不做 llms key 解析、不拆 `/`,
+     * 原样透传给该 provider（支持 OpenRouter 等带 `/` 的 model id）。
+     * LlmConfig 形式下 `options.model` 缺省时回落该 config 的 `models` 第一个 key,
+     * 两者皆无抛 `AgentError`；LLMProvider 实例形式下可为 `undefined`（自定义 provider 自决）。
+     *
+     * 仅影响本次调用——不进 providers Map、不修改 agent 状态。
+     * **sub-agent 递归继承父调用解析出的 provider**（sub 的 model 用其元数据声明的
+     * `config.model`,未声明时沿用父 model）,不继承 options 对象本身。
+     */
+    provider?: LlmConfig | LLMProvider;
     /** 采样温度（透传给 LLM API,覆盖 provider/model 级 temperature） */
     temperature?: number;
     /** 最大生成 token 数（透传给 LLM API） */
@@ -635,14 +657,15 @@ interface AgentHandle {
      */
     stream(input?: string, options?: AgentRunOptions): AsyncIterable<ReactLoopStreamChunk>;
     /**
-     * 把自身包装为 `AgentToolDescriptor` 供 LLM 当 tool 调用
+     * 把指定 agent 包装为 `AgentToolDescriptor` 供 LLM 当 tool 调用
      *
-     * 用于 agent-as-tool 场景：父 agent 把子 agent 包装为 tool,
+     * 用于 agent-as-tool 场景：把 agent 包装为 tool,
      * 加入 LLM 可见 tool 列表,LLM 调用时触发 sub-agent 递归执行。
      *
+     * @param name agent 名（显式指定——无默认 agent）
      * @returns `AgentToolDescriptor` 或 `undefined`（agent 未注册）
      */
-    asTool(): AgentToolDescriptor | undefined;
+    asTool(name: string): AgentToolDescriptor | undefined;
 }
 
 /**
@@ -735,16 +758,10 @@ interface ToolSchemaResolution {
  * 访问器签名与 faapi 核心对称（见 [agent.md](./agent.md) 依赖注入章节）。
  */
 interface AgentDeps {
-    /** LLM provider 实例映射（key 是 provider 名，来自 config.agent.llms） */
+    /** LLM provider 实例映射（key 是 provider 名，来自 config.agent.llms；未配置时为空 Map） */
     providers: Map<string, LLMProvider>;
-    /** 默认 provider 实例（config.agent.defaultLlm 对应，或 llms 第一个 key） */
-    defaultProvider: LLMProvider;
-    /** LLM provider 配置映射（含 models，用于 options.model key 解析） */
+    /** LLM provider 配置映射（含 models，用于 options.model key 解析；llms 未配置时为空对象） */
     llms: Record<string, LlmConfig>;
-    /** 默认 provider key（config.agent.defaultLlm，或 llms 第一个 key） */
-    defaultLlm: string;
-    /** 当前 agent 名 */
-    agentName: string;
     /** 项目根目录（Phase 3.5 接线时用于加载器） */
     rootDir: string;
     /** 全局 agent 配置覆盖 */
@@ -815,7 +832,7 @@ declare class Agent {
      */
     private readonly schemaCache;
     /**
-     * @param deps 运行时依赖（访问器 + providers Map + defaultProvider + llms + config）
+     * @param deps 运行时依赖（访问器 + providers Map + llms + config）
      * @param depth 递归深度（默认 1 = 根 agent；sub-agent 递归时传入 depth+1）
      */
     constructor(deps: AgentDeps, depth?: number);
@@ -823,15 +840,17 @@ declare 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 抛错时立即传播
@@ -842,24 +861,27 @@ declare 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 抛错时立即传播
      */
     stream(input?: string, options?: AgentRunOptions): AsyncIterable<ReactLoopStreamChunk>;
     /**
-     * 把自身包装为 `AgentToolDescriptor` 供 LLM 当 tool 调用
+     * 把指定 agent 包装为 `AgentToolDescriptor` 供 LLM 当 tool 调用
      *
      * 与 [agentRegistry.asTool](../../faapi/src/injection/agentRegistry.md) 同构——
      * Agent 类自带此方法便于在注入器场景直接调用（不必再过注册表）。
      *
+     * @param name agent 名（显式指定——无默认 agent）
      * @returns `AgentToolDescriptor` 或 `undefined`（agent 未注册）
      */
-    asTool(): AgentToolDescriptor | undefined;
+    asTool(name: string): AgentToolDescriptor | undefined;
     /**
      * 查询 tool schema（带缓存）
      *
@@ -873,41 +895,57 @@ declare 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` 结构校验,非法抛
      * `AgentError`,不发起 LLM 请求。
      */
     private buildLoopConfig;
+    /**
+     * 解析外部 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 缺失
+     */
+    private resolveExternalProvider;
     /**
      * 解析 `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
+     *   不存在或歧义）
      */
     private resolveModelKey;
     /**
@@ -930,8 +968,9 @@ declare 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 可据此修正参数重试。
@@ -944,7 +983,9 @@ declare 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。
@@ -982,8 +1023,6 @@ declare class Agent {
  *         models: { 'gpt-4o': {}, 'gpt-4o-mini': { temperature: 0.5 } },
  *       },
  *     },
- *     defaultLlm: 'openai',
- *     defaultAgent: 'researcher',
  *     maxTurns: 10,
  *   },
  *   plugins: ['@faapi/agent'],
@@ -991,19 +1030,18 @@ declare class Agent {
  * ```
  *
  * 插件 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 /
+ * 1. 遍历 `config.agent.llms`（可选）→ 每项调 `createProvider` → `Map<providerKey, LLMProvider>`
+ * 2. 读 `config.agent.maxTurns` / `maxAgentDepth`
+ * 3. 从 `@faapi/faapi` import 注册表/加载器访问器（getAgent / getTool / resolveAgentTools /
  *    resolveSubAgents / loadAgentModule / loadToolModule）
- * 5. `registerAgentHandleFactory` 注册工厂——每次请求时构造 [Agent](./agent.md) 实例注入到
+ * 4. `registerAgentHandleFactory` 注册工厂——每次请求时构造 [Agent](./agent.md) 实例注入到
  *    handler 的 `agent` 参数
  *
- * 配置缺失时（`agent.llms` 未设置）跳过工厂注册并打印警告,
- * handler 的 `agent` 参数注入 `undefined`。
+ * 无默认 agent / 默认 provider——`agent.run/stream` 每次调用显式传 `options.agent` +
+ * `options.model` / `options.provider`。
  *
- * `defaultAgent` 可选——未设时 handler 需通过 `agent.run(input, { agent: 'name' })`
- * 显式指定 agent 名。
+ * `agent.llms` 可选——未配置时工厂照常注册（外部 provider 模式）,`agent.run/stream`
+ * 需调用方传 `options.provider` 才能调用 LLM。只有插件未加载时 `agent` 参数才注入 `undefined`。
  *
  * 详见 [plugin.md](./plugin.md)。
  */