11_07_Sub_Agent

(七) Sub-Agent 委派编排

// 考虑是否采用multi agent机制 探讨

Sub-agent（子智能体）基础设施在 cli/sub_agents.py，当前只有 CLI（命令行）/ TUI（终端图形界面）可用。

当前采用的是 Supervisor / tool-calling subagents 模式：主 Agent 保持会话控制权，把子 Agent 当作高阶工具调用；子 Agent 只负责局部任务，执行完成后把结构化结果交还给主 Agent。

flowchart TD
    U["用户"] <--> M["主 Agent / Supervisor"]

    M --> T["普通工具"]
    M --> R["delegate_to_research"]
    M --> A["delegate_to_analysis"]
    M --> D["delegate_to_trading"]

    R --> RR["research mini runtime"]
    RR --> M

    A --> AR["analysis mini runtime"]
    AR --> M

    D --> DR["trading mini runtime"]
    DR --> M

Loading

这不是 handoff（交接控制权）：子 Agent 不接管后续对话。也不是 parallel workers（并发子 Agent 汇总）：当前没有同时启动多个子 Agent 再统一投票/汇总的编排器。

三个内置角色的治理参数：

Sub-agent（子智能体）	职责	总超时	单工具超时	最大工具轮次	输入预算	输出预算
research	数据收集、全市场扫描、信号、复盘、回测	240s	90s	8	24K token	3000 chars
analysis	个股诊断、持仓体检、AI 研报	180s	75s	8	20K token	2500 chars
trading	去留决策、攻防指令、调仓计划	120s	45s	6	12K token	1600 chars

工具白名单：

• research：search_stock_by_name、analyze_stock、get_market_overview、get_market_history、query_history、screen_stocks、run_backtest、check_background_tasks
• analysis：analyze_stock、portfolio、get_market_overview、get_market_history、generate_ai_report
• trading：portfolio、generate_strategy_decision、analyze_stock、get_market_overview、get_market_history

主 Agent 通过 delegate_to_research、delegate_to_analysis、delegate_to_trading 调用子 Agent。

实现要点：

• SubAgentToolProxy（子智能体工具代理）只暴露允许的 schemas（工具定义），并在执行时拒绝越权工具。
• SubAgentToolProxy 会为每次工具调用施加单工具超时；超时结果以工具错误返回给子 Agent，不继续阻塞主 Agent。
• 每个 sub-agent（子智能体）启动自己的 AgentRuntime mini loop（小型循环），使用独立 system prompt（系统提示词）和上下文。
• 子 Agent 使用同一个 provider（模型适配层）和 ToolRegistry（工具注册表），所以能共享登录态、数据源和确认机制。
• 子 Agent 有独立 deadline（总耗时上限）和 max_tool_rounds（最大工具轮次），防止一个委派任务长期占用主 Agent。
• 子 Agent 有 context_budget_tokens（输入上下文预算）和 result_budget_chars（输出结果预算）：主 Agent 可以把较大的局部材料交给子 Agent 处理，但子 Agent 只向主 Agent 回传预算内的结论摘要。
• 当传入 context 超过预算时，系统会确定性裁剪，只保留最近部分，并在上下文中加入“已按预算裁剪”的标记。这样子 Agent 能分担上下文压力，但不会变成无限上下文容器。
• TUI 的取消信号会通过 tool_context.cancel_check 传给子 Agent；用户中断主任务时，子 Agent 也会返回 cancelled。
• TUI（终端图形界面）通过 tool_context.on_progress 转发子 Agent（子智能体）的 text_delta、tool_start、tool_result、done 事件，以灰色斜体展示执行进度。

子 Agent 的返回结果是结构化对象，而不是只有一段自然语言：

{
    "agent": "research",
    "status": "completed | timeout | cancelled | error | empty",
    "result": "...",
    "usage": {"input_tokens": 0, "output_tokens": 0},
    "elapsed": 12.3,
    "rounds": 3,
    "tool_calls": ["get_market_overview", "analyze_stock"],
    "context_truncated": false,
    "result_truncated": false,
    "error": "",
    "policy": {
        "next_action": "use_result | fallback_to_direct_tools | stop_and_report_cancelled",
        "retryable": false,
        "fallback_tools": [],
        "instruction": "..."
    }
}

这里的 timeout 是子 Agent 自己的总 deadline、模型流式空闲超时或单工具超时；cancelled 是用户主动中断；error 是执行异常。主 Agent 可以基于 status 决定继续追问、降级回答，还是提示用户重试。

委派结果会附带 policy（结果策略），把失败后的处理收敛成结构化动作：

status	next_action	retryable	fallback_tools
completed	use_result	false	空
timeout	fallback_to_direct_tools	true	对应角色的普通工具降级集
error	fallback_to_direct_tools	true	对应角色的普通工具降级集
empty	fallback_to_direct_tools	false	对应角色的普通工具降级集
cancelled	stop_and_report_cancelled	false	空

降级工具集按角色固定：research 使用 get_market_overview、query_history、check_background_tasks；analysis 使用 analyze_stock、portfolio、get_market_overview；trading 使用 portfolio、generate_strategy_decision、get_market_overview。主 Agent 收到失败结果后，不再自由猜测处理方式，而是按 policy 选择降级工具、停止任务或使用已有结论。

上下文分担的边界：

• 主 Agent 保留用户最终目标、全局任务状态和高风险决策权。
• 真实调仓执行只由主 Agent 在用户确认后调用 update_portfolio；trading 子 Agent 只输出交易计划和风险条件。
• 子 Agent 处理局部大上下文，例如多标的诊断、行情材料归纳、工具返回对比和阶段性证据整理。
• 子 Agent 返回的是压缩后的局部结论，不把完整工具过程和大段原始材料重新塞回主 Agent。
• 如果 context_truncated=true 或 result_truncated=true，主 Agent 应该把结论视为预算内摘要；需要精确字段时应重新调用工具或查看 scratchpad。

需要区分的是：子 Agent 不是后台 worker（后台工作进程）。delegate_to_* 本身是同步工具调用；如果子 Agent 内部调用 screen_stocks、generate_ai_report、generate_strategy_decision、run_backtest 这类 background=True 工具，这些长任务会被提交给 BackgroundTaskManager 并立即返回 task_id。子 Agent 不负责等待后台任务跑完，后续由主 Agent 通过 check_background_tasks 或系统通知继续衔接。

这个设计把“主 Agent 负责路由、规划、预算和最终回答”和“子 Agent 专注单类任务”拆开，减少复杂投研任务把主会话上下文搅乱。

---

---

返回 系列索引