Agent/agent/tools/builtin/subagent.py

"""
Subagent 工具 - 统一的 Sub-Agent 创建工具

统一 evaluate、delegate、explore 三个工具的功能
"""

from typing import Optional, Dict, Any, List
from agent.tools import tool


@tool(description="创建 Sub-Agent 执行任务（评估/委托/探索）")
async def subagent(
    mode: str,  # "evaluate" | "delegate" | "explore"

    # 通用参数
    task: Optional[str] = None,

    # evaluate 专用参数
    target_goal_id: Optional[str] = None,
    evaluation_input: Optional[Dict] = None,
    requirements: Optional[str] = None,

    # explore 专用参数
    branches: Optional[List[str]] = None,
    background: Optional[str] = None,

    # 通用选项
    continue_from: Optional[str] = None,
    wait: bool = True,

    context: Optional[dict] = None
) -> Dict[str, Any]:
    """
    创建 Sub-Agent 执行任务

    Args:
        mode: 模式 - "evaluate"（评估）、"delegate"（委托）、"explore"（探索）
        task: 任务描述（delegate/explore 使用）
        target_goal_id: 被评估的 Goal ID（evaluate 使用）
        evaluation_input: 评估输入（evaluate 使用）
        requirements: 评估要求（evaluate 使用）
        branches: 探索分支列表（explore 使用）
        background: 背景信息（explore 使用）
        continue_from: 继承的 trace ID（连续记忆）
        wait: 是否等待结果（默认 True）
        context: 工具执行上下文

    Returns:
        根据 mode 返回不同格式的结果

    Examples:
        # 评估
        subagent(
            mode="evaluate",
            target_goal_id="3",
            evaluation_input={"actual_result": "已实现登录功能"}
        )

        # 委托
        subagent(mode="delegate", task="实现用户注册功能")

        # 探索
        subagent(mode="explore", branches=["JWT 方案", "Session 方案"])
    """
    from agent.services.subagent.manager import SubAgentManager

    if not context:
        return {"error": "context is required"}

    # 提取 context 参数
    store = context.get("store")
    trace_id = context.get("trace_id")
    goal_id = context.get("goal_id")
    run_agent = context.get("run_agent")

    # 验证必需参数
    missing = []
    if not store: missing.append("store")
    if not trace_id: missing.append("trace_id")
    if not run_agent: missing.append("run_agent")

    if missing:
        return {"error": f"Missing required context: {', '.join(missing)}"}

    # 验证 mode 参数
    if mode not in ["evaluate", "delegate", "explore"]:
        return {"error": f"Invalid mode: {mode}. Must be 'evaluate', 'delegate', or 'explore'"}

    # 构建 options
    options = {}

    if mode == "evaluate":
        if not target_goal_id or not evaluation_input:
            return {"error": "evaluate mode requires target_goal_id and evaluation_input"}
        options = {
            "target_goal_id": target_goal_id,
            "evaluation_input": evaluation_input,
            "requirements": requirements
        }

    elif mode == "delegate":
        if not task:
            return {"error": "delegate mode requires task"}
        options = {"task": task}

    elif mode == "explore":
        if not branches:
            return {"error": "explore mode requires branches"}
        options = {
            "branches": branches,
            "background": background
        }

    # 使用 SubAgentManager 执行
    manager = SubAgentManager(store, signal_bus=context.get("signal_bus"))

    result = await manager.execute(
        mode=mode,
        current_trace_id=trace_id,
        current_goal_id=goal_id,
        options=options,
        continue_from=continue_from,
        wait=wait,
        run_agent=run_agent
    )

    return result