OpenAI Agents SDK #15：一个 Agent 搞不定——加一个真的够吗？

两种编排范式，两种世界观

as_tool()：把 Agent 变成工具

Handoff vs as_tool()，到底什么区别？

• Handoff = 把方向盘交给别人
• as_tool() = 让别人帮你做一个子任务，结果交回来你继续开

完整代码示例：Manager 模式（三语翻译）

import asyncio
from agents import Agent, Runner, trace
from agents.extensions.handoff_prompt import RECOMMENDED_PROMPT_PREFIX

# ── Step 1：定义三个专业翻译 Agent ──────────────────────────────
spanish_agent = Agent(
    name="西班牙语翻译",
    instructions="你是一名专业的英译西翻译，只输出翻译结果，不加任何解释。",
    handoff_description="将英文文本翻译为西班牙语",
)

french_agent = Agent(
    name="法语翻译",
    instructions="你是一名专业的英译法翻译，只输出翻译结果，不加任何解释。",
    handoff_description="将英文文本翻译为法语",
)

italian_agent = Agent(
    name="意大利语翻译",
    instructions="你是一名专业的英译意翻译，只输出翻译结果，不加任何解释。",
    handoff_description="将英文文本翻译为意大利语",
)

# ── Step 2：构建 Orchestrator，将三个 Agent 转换为工具 ──────────
orchestrator_agent = Agent(
    name="翻译编排器",
    instructions=(
        f"{RECOMMENDED_PROMPT_PREFIX}\n"
        "你是一个多语言翻译编排器。收到翻译请求后，"
        "调用西班牙语、法语、意大利语三个翻译工具，"
        "按顺序逐一调用，收集全部翻译结果。"
    ),
    tools=[
        # as_tool() 将 Agent 包装成普通工具
        # 子 Agent 只拿到 tool 调用时生成的输入，不接收主 Agent 的完整历史
        spanish_agent.as_tool(
            tool_name="translate_to_spanish",
            tool_description="将英文翻译为西班牙语",
        ),
        french_agent.as_tool(
            tool_name="translate_to_french",
            tool_description="将英文翻译为法语",
        ),
        italian_agent.as_tool(
            tool_name="translate_to_italian",
            tool_description="将英文翻译为意大利语",
        ),
    ],
)

# ── Step 3：Synthesizer 合并校验结果 ───────────────────────────
synthesizer_agent = Agent(
    name="结果合成器",
    instructions=(
        "你收到了三种语言的翻译结果，请按以下格式输出最终版本：\n"
        "🇪🇸 西班牙语：...\n🇫🇷 法语：...\n🇮🇹 意大利语：..."
    ),
)

# ── Step 4：完整流程 ────────────────────────────────────────────
async def translate_all(text: str) -> str:
    with trace("多语言翻译工作流"):  # trace 包装，方便 Tracing 面板观察
        # 第一步：orchestrator 编排三个翻译工具
        orchestrator_result = await Runner.run(
            orchestrator_agent,
            f"请将以下文本翻译成三种语言：{text}",
        )
        # 第二步：synthesizer 合并输出
        # to_input_list() 把上一步的结果链接到下一步的输入
        final_result = await Runner.run(
            synthesizer_agent,
            orchestrator_result.to_input_list(),
        )
        return final_result.final_output

if __name__ == "__main__":
    result = asyncio.run(translate_all("The quick brown fox jumps over the lazy dog."))
    print(result)

并发编排：asyncio.gather 真正提速的姿势

这段代码解决什么问题：同一批任务独立运行，互不等待

import asyncio
from agents import Agent, Runner

# 定义三个独立任务的 Agent
summarize_agent = Agent(
    name="摘要 Agent",
    instructions="用三句话总结以下内容。",
)

sentiment_agent = Agent(
    name="情感分析 Agent",
    instructions="分析以下文本的情感倾向，输出：正面/负面/中性，附一句理由。",
)

keyword_agent = Agent(
    name="关键词提取 Agent",
    instructions="提取以下文本的 5 个核心关键词，用逗号分隔输出。",
)

async def analyze_text(text: str):
    """
    三个 Agent 并发执行，总耗时 ≈ 最慢的那个，而不是三者之和
    适用条件：各 Agent 之间没有数据依赖
    """
    summary_task = Runner.run(summarize_agent, text)
    sentiment_task = Runner.run(sentiment_agent, text)
    keyword_task = Runner.run(keyword_agent, text)

# gather 等待所有任务完成，结果顺序与输入顺序对应
    summary_result, sentiment_result, keyword_result = await asyncio.gather(
        summary_task,
        sentiment_task,
        keyword_task,
    )

return {
        "summary": summary_result.final_output,
        "sentiment": sentiment_result.final_output,
        "keywords": keyword_result.final_output,
    }

if __name__ == "__main__":
    sample_text = """
    OpenAI Agents SDK 在 2026 年持续迭代，多 Agent 编排能力进一步成熟。
    v0.15.2 修复了交接过滤器的 bug，测试覆盖率也在持续扩展。
    """
    result = asyncio.run(analyze_text(sample_text))
    for k, v in result.items():
        print(f"[{k}] {v}")

什么时候不能并发？

# 代码驱动串行示例：大纲 → 质量评估 → 按条件决定是否写故事
from pydantic import BaseModel

class OutlineCheckerOutput(BaseModel):
    good_quality: bool   # 大纲质量是否合格
    is_scifi: bool       # 是否属于科幻主题

story_outline_agent = Agent(name="大纲生成", instructions="生成一个科幻故事大纲。")
outline_checker_agent = Agent(
    name="大纲评估",
    instructions="评估大纲质量和题材，输出结构化结果。",
    output_type=OutlineCheckerOutput,  # 强制结构化输出，方便代码层判断
)
story_agent = Agent(name="故事写作", instructions="根据大纲写一个完整的科幻短故事。")

async def generate_story(prompt: str) -> str:
    # Step 1：生成大纲
    outline_result = await Runner.run(story_outline_agent, prompt)

# Step 2：评估大纲——结构化输出保证 .final_output 是 OutlineCheckerOutput 实例
    check_result = await Runner.run(
        outline_checker_agent,
        outline_result.final_output,
    )
    evaluation: OutlineCheckerOutput = check_result.final_output

# Step 3：代码层判断，不是 LLM 在猜——这就是「代码驱动」的关键
    if not evaluation.good_quality or not evaluation.is_scifi:
        print("大纲不符合要求，流程终止。")
        return ""

# Step 4：写故事
    story_result = await Runner.run(story_agent, outline_result.final_output)
    return story_result.final_output

多 Agent 间的 Context 流转

from dataclasses import dataclass
from agents import Agent, Runner, RunConfig

@dataclass
class AppContext:
    user_id: str
    db_connection: str  # 实际场景里是数据库连接对象

context = AppContext(user_id="u_12345", db_connection="postgresql://...")

# as_tool() 子 Agent 通过 run_config 传入 context
child_agent = Agent(name="子任务 Agent", instructions="完成具体的数据处理任务。")

parent_agent = Agent(
    name="主编排 Agent",
    instructions="根据任务类型调用子任务工具。",
    tools=[
        child_agent.as_tool(
            tool_name="process_data",
            tool_description="处理用户数据",
        )
    ],
)

# 在主 Agent 运行时传入 context，子 Agent 通过 run_config 继承
result = await Runner.run(
    parent_agent,
    "处理用户数据",
    context=context,  # context 在整条链路中自动流转
)

踩坑经验：中文社区的三个高频错误

把 as_tool() 当 Handoff 用——上下文全丢

把有依赖的任务丢进 asyncio.gather

LLM 驱动编排忘了设 max_turns

实践建议：3 条立即可落地的

下一篇预告：#16 Results 解析