关键构件

• 终止原因枚举 SubagentTerminateMode：ERROR | TIMEOUT | GOAL | MAX_TURNS，准确表达为什么停止。
• 输出对象 OutputObject：emitted_vars 存储通过 self.emitvalue 发射的变量；terminate_reason 标示终止原因。
• 提示与模型配置：
  • PromptConfig：二选一提供 systemPrompt 或 initialMessages（few-shot 历史）。
  • ModelConfig：model、temp、top_p 控制生成行为。
  • RunConfig：max_time_minutes 与可选 max_turns 控制预算。
  • ToolConfig：允许以”注册名”或直接给出 FunctionDeclaration 暴露工具。
  • OutputConfig：声明期望输出变量的键与语义描述。
• 运行态上下文 ContextState：一个简单的键值容器，用来为系统提示模板 ${key} 替换提供值；在替换前会强校验缺失键。
• 模板函数 templateString：校验并替换 systemPrompt 内 ${...} 占位符，缺失即抛错，保障提示完整性与确定性。
• 作用域类 SubAgentScope：SubAgent 的核心执行体，负责：
  • 工具预检查与实例化（create）
  • 构建聊天对象（createChatObject）
  • 主事件循环（runNonInteractive）
  • 工具调用执行与结果回灌（processFunctionCalls）
  • 构建系统提示与本地工具注入（buildChatSystemPrompt / getScopeLocalFuncDefs）

数据流（简化）

1. 创建 Scope →
2. 构建 Chat（环境上下文 + systemPrompt/initialMessages）→
3. 进入循环（发送消息 → 接收函数调用 → 执行工具 → 结果作为”用户消息”回灌）→
4. 若未满足输出约束则”提醒”继续 →
5. 满足目标或达到预算而终止，回填 OutputObject。

1) 创建与工具预检：SubAgentScope.create

加载 ToolRegistry，对配置里以”名称”声明的工具做”非交互可用性”预检：

• 若工具无必填参数，则尝试 shouldConfirmExecute；若需要用户确认，直接抛错禁止在非交互子代理中使用。
• 若工具存在必填参数，无法构造通用的空入参校验，默认”假定安全”（保守权衡：避免创建时崩溃优先于运行时潜在挂起）。

2) 构建对话体：createChatObject

• 注入环境上下文（getEnvironmentContext）形成 start_history，帮助模型”落地”当前会话的系统状态。
• 若使用 systemPrompt：将 ContextState 注入做模板替换；否则使用 initialMessages 做 few-shot 引导。
• 组装 GenerateContentConfig（温度、topP、可选 systemInstruction），并通过 createContentGenerator 与 GeminiChat 封装出聊天对象。
• 将选定模型名写入 runtimeContext（便于统一上报/可观测）。

3) 非交互主循环：runNonInteractive

初始消息为一个轻量”点火”指令（Get Started!）。每轮：

1. 检查预算：max_turns / max_time_minutes，命中则以 MAX_TURNS/TIMEOUT 终止。
2. 发送消息（附 tools 与 abortSignal），流式接收模型产生的 functionCalls。
3. 若存在函数调用 → 进入”工具执行阶段”。
4. 若没有函数调用：
   • 如未声明输出要求，直接以 GOAL 终止。
   • 如声明了输出要求：
     • 若已全部 emit，以 GOAL 终止；
     • 否则给出”nudge”提示，要求调用 self.emitvalue 发射缺失变量，继续下一轮。

4) 工具执行与结果回灌：processFunctionCalls

对每个 FunctionCall：

• 若为作用域内工具 self.emitvalue：将 emit_variable_name/value 记录进 output.emitted_vars，并构造成功响应。
• 否则通过 executeToolCall 调用注册工具，携带 AbortSignal；收集工具返回的 responseParts。

若所有工具调用均失败，会向模型回灌一条”全部失败，请分析错误并换一种方法”的文本，促使其调整策略。

将工具响应作为”用户消息”放回对话，以闭环”观察-行动-反馈”。

buildChatSystemPrompt 会在 systemPrompt 基础上追加两类关键指令：

• 输出约束：逐条告知如何用 self.emitvalue 发射每个期望变量。
• 非交互规则：明确”不得向用户提问””完成目标后停止调用工具”。

promptId 由 sessionId#subagentId#turn 组成，贯穿工具调用链路，便于追踪与诊断。

SubAgent 自身不直接与模型交互，而是经由 GeminiChat 与 ContentGenerator 层对接 @google/genai：

• 从工程上看，这一分层让 SubAgent 聚焦”编排（prompt/工具/预算/收尾）”，而将”对话与生成”的复杂度下沉到更通用的封装中。
• 这也为未来的”模型路由/回退/观测”提供了稳定扩展点，例如引入”自动模型选择”或”token 预算”只需扩展 ModelConfig 与 ContentGenerator。

import { SubAgentScope, ContextState } from 'packages/core/src/core/subagent';
import { Config } from 'packages/core/src/config/config';

// 1) 准备运行时上下文（含工具注册、会话信息等）
const runtimeContext: Config = /* 你的实现 */;

// 2) 声明各类配置
const promptConfig = {
  systemPrompt: `你是一个文档提取子代理。目标是从 ${'${doc_path}'} 中提取标题和作者。`,
};
const modelConfig = { model: 'gemini-2.5-pro', temp: 0.2, top_p: 0.9 };
const runConfig = { max_time_minutes: 2, max_turns: 8 };
const toolConfig = { tools: ['read_file', 'grep'] }; // 假设已在 ToolRegistry 中注册
const outputConfig = { outputs: { title: '文档标题', author: '作者姓名' } };

// 3) 构建上下文（用于 systemPrompt 模板化）
const ctx = new ContextState();
ctx.set('doc_path', '/abs/path/to/paper.md');

// 4) 创建并运行子代理
const scope = await SubAgentScope.create(
  'doc-extractor',
  runtimeContext,
  promptConfig,
  modelConfig,
  runConfig,
  toolConfig,
  outputConfig,
);

await scope.runNonInteractive(ctx);

// 5) 收集结构化出参
console.log(scope.output.emitted_vars, scope.output.terminate_reason);

要点：

• systemPrompt 与 initialMessages 不能同时提供；
• 所有 ${...} 占位都必须在 ContextState 中有值；
• 若未满足 outputs 的发射要求，SubAgent 会通过 nudge 提醒模型调用 self.emitvalue；
• 若某工具需要用户确认，将在 create 阶段直接阻止使用。