多Agent编排：从单兵到团队

用户任务 → Supervisor（路由决策）
                ├── CodingAgent（写代码）
                ├── ReviewAgent（审代码）
                └── ...更多专家

# Swarm 模式的核心思路（伪代码）
class SwarmAgent:
    def run(self, messages: list[Message]) -> Message | Handoff:
        result = self.think(messages)
        if result.needs_handoff:
            return Handoff(target="reviewer", context=result.summary)
        return Message(role="assistant", content=result.content)

# review_agent.py
import json
from openai import OpenAI
from shared.types import Message, ToolResult, Tool
from shared.prepare_tools import prepare_tools_for_openai

REVIEWER_SYSTEM_PROMPT = """You are a code reviewer. Your job is to review code changes
for correctness, style consistency, and potential issues.

You can read files and search code, but you cannot modify files or run commands.
This separation exists by design — your role is to evaluate, not to fix.

When reviewing, check for:
- Logic errors and edge cases
- Style inconsistencies with the existing codebase
- Missing error handling
- Test coverage gaps

After review, provide a clear verdict:
- APPROVE: Code is ready to merge
- REQUEST_CHANGES: List specific issues that need fixing"""


class ReviewAgent:

    def __init__(self, tools: list[Tool], model: str = "gpt-4o"):
        self.client = OpenAI()
        self.model = model
        self.tools = {t.name: t for t in tools}
        self.tool_schemas = prepare_tools_for_openai(tools)

    def run(self, messages: list[Message]) -> Message:
        conversation = [
            {"role": "system", "content": REVIEWER_SYSTEM_PROMPT},
            *[{"role": m.role, "content": m.content} for m in messages],
        ]

        while True:
            response = self.client.chat.completions.create(
                model=self.model,
                messages=conversation,
                tools=self.tool_schemas if self.tool_schemas else None,
            )
            msg = response.choices[0].message

            if not msg.tool_calls:
                return Message(role="assistant", content=msg.content)

            conversation.append({
                "role": "assistant",
                "content": msg.content,
                "tool_calls": [
                    {"id": tc.id, "type": "function",
                     "function": {"name": tc.function.name,
                                  "arguments": tc.function.arguments}}
                    for tc in msg.tool_calls
                ],
            })

            for tool_call in msg.tool_calls:
                name = tool_call.function.name
                kwargs = json.loads(tool_call.function.arguments)
                result_str = self.tools[name].execute(**kwargs)
                tool_result = ToolResult(
                    content=result_str,
                    is_error=any(
                        k in result_str
                        for k in ["ERROR", "BLOCKED", "TIMEOUT"]
                    ),
                )
                conversation.append({
                    "role": "tool",
                    "tool_call_id": tool_call.id,
                    "content": tool_result.to_str(),
                })

# supervisor.py
import json
from openai import OpenAI
from shared.types import Message, Agent

ROUTER_PROMPT = """You are a task router that coordinates a coding team.
You have two team members:
- coder: writes and modifies code, runs tests
- reviewer: reads code and checks for issues, cannot modify files

Route the task to the appropriate team member based on the current state:
- If code needs to be written or modified → coder
- If code has been written and needs review → reviewer
- If the reviewer approved the changes → FINISH
- If the reviewer requested changes → coder (to address feedback)

Always route to reviewer before finishing. Never finish without a review."""


class SupervisorAgent:

    def __init__(self, agents: dict[str, Agent], model: str = "gpt-4o-mini"):
        self.client = OpenAI()
        self.model = model
        self.agents = agents
        self.max_rounds = 5

    def _route(self, messages: list[dict]) -> str:
        response = self.client.chat.completions.create(
            model=self.model,
            messages=[
                {"role": "system", "content": ROUTER_PROMPT},
                *messages,
            ],
            tools=[{
                "type": "function",
                "function": {
                    "name": "route",
                    "description": "决定下一步的行动",
                    "strict": True,
                    "parameters": {
                        "type": "object",
                        "properties": {
                            "next": {
                                "type": "string",
                                "enum": ["coder", "reviewer", "FINISH"],
                                "description": "下一个执行的Agent，或FINISH结束"
                            },
                            "reason": {
                                "type": "string",
                                "description": "路由决策的理由"
                            }
                        },
                        "required": ["next", "reason"],
                        "additionalProperties": False
                    }
                }
            }],
        )
        tool_call = response.choices[0].message.tool_calls[0]
        decision = json.loads(tool_call.function.arguments)
        return decision["next"]

    def _filter_context(self, conversation: list[dict],
                        target: str) -> list[dict]:
        filtered = []
        for msg in conversation:
            if msg["role"] == "user":
                filtered.append(msg)
            elif msg["role"] == "assistant" and "name" in msg:
                filtered.append(msg)
        return filtered

    def run(self, messages: list[Message]) -> Message:
        conversation = [
            {"role": m.role, "content": m.content} for m in messages
        ]
        round_count = 0

        while round_count < self.max_rounds:
            next_agent = self._route(conversation)
            if next_agent == "FINISH":
                break

            agent = self.agents[next_agent]
            filtered = self._filter_context(conversation, next_agent)
            result = agent.run([
                Message(role=m["role"], content=m["content"])
                for m in filtered
            ])

            conversation.append({
                "role": "assistant",
                "content": f"[{next_agent}]: {result.content}",
                "name": next_agent,
            })
            round_count += 1

        return Message(
            role="assistant",
            content=conversation[-1]["content"],
            metadata={"rounds": round_count},
        )

def _filter_context(self, conversation: list[dict],
                    target: str) -> list[dict]:
    # target 参数为扩展预留——当前两Agent场景下双方互相可见即可
    filtered = []
    for msg in conversation:
        if msg["role"] == "user":
            filtered.append(msg)
        elif msg["role"] == "assistant" and "name" in msg:
            filtered.append(msg)
    return filtered

# main.py
from shared.types import Message
from coding_agent import CodingAgent
from review_agent import ReviewAgent
from supervisor import SupervisorAgent

# CodingAgent：沿用第6篇的完整实现
coder = CodingAgent(
    tools=[ReadFile(), WriteFile(), SearchCode(), RunCommand()]
)

# ReviewAgent：只有只读工具——L2 权限隔离
reviewer = ReviewAgent(
    tools=[ReadFile(), SearchCode()]
)

# Supervisor：编排两个专家
supervisor = SupervisorAgent(
    agents={"coder": coder, "reviewer": reviewer}
)

result = supervisor.run([
    Message(
        role="user",
        content="给 calculator.py 的除法函数添加除零保护，并更新测试"
    )
])
print(result.content)
print(f"总轮次: {result.metadata['rounds']}")

Round 1 — Supervisor → coder
  CodingAgent 读取 calculator.py，发现 divide() 没有除零检查。
  添加 if divisor == 0: raise ValueError("Cannot divide by zero")。
  写入测试 test_divide_by_zero()，运行 pytest，全部通过。

Round 2 — Supervisor → reviewer
  ReviewAgent 读取修改后的 calculator.py 和测试文件。
  发现问题：测试只检查了 ValueError 的抛出，没有验证正常除法仍然正确。
  输出 REQUEST_CHANGES。

Round 3 — Supervisor → coder
  CodingAgent 收到审查反馈，补充 test_divide_normal() 测试用例。
  运行 pytest，全部通过。

Round 4 — Supervisor → reviewer
  ReviewAgent 重新审查，确认修改和测试覆盖完整。
  输出 APPROVE。

Supervisor → FINISH（总轮次: 4）

# 成本对比
supervisor = SupervisorAgent(
    agents=agents,
    model="gpt-4o-mini",   # 路由：~$0.15/M input tokens
)
coder = CodingAgent(
    tools=tools,
    model="gpt-4o",        # 执行：~$2.50/M input tokens
)

while round_count < self.max_rounds:
    next_agent = self._route(conversation)
    if next_agent == "FINISH":
        break
    # ...
    round_count += 1

# 超过 max_rounds 自动退出，返回最后一条消息
return Message(
    role="assistant",
    content=conversation[-1]["content"],
    metadata={"rounds": round_count},
)