@faapi/agent 4.4.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,7 +510,7 @@ 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 };
  * }
  * ```
@@ -518,14 +518,15 @@ declare function reactLoopStream(input: string | undefined, config: ReactLoopCon
  * 仅在 `@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 解析规则」）：
@@ -533,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 {
@@ -561,16 +559,17 @@ 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}。
      */
@@ -590,8 +589,9 @@ interface AgentRunOptions {
      * LlmConfig 形式下 `options.model` 缺省时回落该 config 的 `models` 第一个 key,
      * 两者皆无抛 `AgentError`；LLMProvider 实例形式下可为 `undefined`（自定义 provider 自决）。
      *
-     * 仅影响本次调用——不进 providers Map、不修改 agent 状态,**sub-agent 递归不继承**
-     * （sub-agent 仍走默认解析链路）,下一次调用仍用默认配置。
+     * 仅影响本次调用——不进 providers Map、不修改 agent 状态。
+     * **sub-agent 递归继承父调用解析出的 provider**（sub 的 model 用其元数据声明的
+     * `config.model`,未声明时沿用父 model）,不继承 options 对象本身。
      */
     provider?: LlmConfig | LLMProvider;
     /** 采样温度（透传给 LLM API,覆盖 provider/model 级 temperature） */
@@ -657,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;
 }
 
 /**
@@ -759,19 +760,8 @@ interface ToolSchemaResolution {
 interface AgentDeps {
     /** LLM provider 实例映射（key 是 provider 名，来自 config.agent.llms；未配置时为空 Map） */
     providers: Map<string, LLMProvider>;
-    /**
-     * 默认 provider 实例（config.agent.defaultLlm 对应，或 llms 第一个 key）
-     *
-     * 可选——config.agent.llms 未配置时为 undefined（外部 provider 模式），
-     * 此时 run/stream 必须传 options.provider，否则 resolveModelKey 抛 AgentError。
-     */
-    defaultProvider?: LLMProvider;
     /** LLM provider 配置映射（含 models，用于 options.model key 解析；llms 未配置时为空对象） */
     llms: Record<string, LlmConfig>;
-    /** 默认 provider key（config.agent.defaultLlm，或 llms 第一个 key；llms 未配置时为 undefined） */
-    defaultLlm?: string;
-    /** 当前 agent 名 */
-    agentName: string;
     /** 项目根目录（Phase 3.5 接线时用于加载器） */
     rootDir: string;
     /** 全局 agent 配置覆盖 */
@@ -842,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);
@@ -850,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 临时覆盖本次调用的 provider（外部 provider）/ 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 抛错时立即传播
@@ -869,25 +861,27 @@ declare class Agent {
      *
      * @param input 用户输入（可选——续跑场景不传新输入；input 与 `options.messages`
      *              都为空时抛 `AgentError`）
-     * @param options 临时覆盖本次调用的 provider（外部 provider）/ model（字符串 key）/
+     * @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（带缓存）
      *
@@ -901,23 +895,19 @@ 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.provider`（外部 provider）存在时由 {@link resolveExternalProvider} 物化,
      * 优先级最高——`options.model` 变为原始 model 名原样透传（不解析 llms key）。
      * 否则 `options.model` 是字符串 key,由 {@link resolveModelKey} 解析为 provider + model
-     * （支持 llms key 精确匹配 / `provider/model` 一体化 / 纯 model 名模糊匹配）。
-     * 不传 `options.model` 时用 `deps.defaultProvider` + agent 元数据 `config.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` 结构校验,非法抛
@@ -942,19 +932,20 @@ declare class Agent {
     /**
      * 解析 `options.model` 字符串 key → provider + model
      *
-     * 规则见 [agentHandle.md](./agentHandle.md) 的「`options.model` 字符串 key 解析规则」：
-     * 1. `undefined` → `deps.defaultProvider`（未配置时抛 `AgentError`——外部 provider 模式
-     *    要求调用方传 `options.provider`）+ `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 不存在或歧义）；deps.defaultProvider
-     *   未配置（外部 provider 模式下调用方未传 options.provider）
+     * @throws {AgentError} key 与 `meta.model` 均缺省；key 解析失败（provider/model
+     *   不存在或歧义）
      */
     private resolveModelKey;
     /**
@@ -977,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 可据此修正参数重试。
@@ -991,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。
@@ -1029,8 +1023,6 @@ declare class Agent {
  *         models: { 'gpt-4o': {}, 'gpt-4o-mini': { temperature: 0.5 } },
  *       },
  *     },
- *     defaultLlm: 'openai',
- *     defaultAgent: 'researcher',
  *     maxTurns: 10,
  *   },
  *   plugins: ['@faapi/agent'],
@@ -1039,20 +1031,18 @@ declare class Agent {
  *
  * 插件 setup 时：
  * 1. 遍历 `config.agent.llms`（可选）→ 每项调 `createProvider` → `Map<providerKey, LLMProvider>`
- * 2. 读 `config.agent.defaultLlm` → `defaultProvider`（未设时用 `llms` 第一个 key;
- *    `llms` 未配置/未命中时为 `undefined`——外部 provider 模式,照常注册工厂）
- * 3. 读 `config.agent.defaultAgent`（可选） / `maxTurns` / `maxAgentDepth`
- * 4. 从 `@faapi/faapi` import 注册表/加载器访问器（getAgent / getTool / resolveAgentTools /
+ * 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 / 默认 provider——`agent.run/stream` 每次调用显式传 `options.agent` +
+ * `options.model` / `options.provider`。
+ *
  * `agent.llms` 可选——未配置时工厂照常注册（外部 provider 模式）,`agent.run/stream`
  * 需调用方传 `options.provider` 才能调用 LLM。只有插件未加载时 `agent` 参数才注入 `undefined`。
  *
- * `defaultAgent` 可选——未设时 handler 需通过 `agent.run(input, { agent: 'name' })`
- * 显式指定 agent 名。
- *
  * 详见 [plugin.md](./plugin.md)。
  */