OpenAI Agents SDK #26：Research Bot 拆解——一个真正会上网查资料的 Agent 是怎么造的

架构总览：三个 Agent，一个管家，没有 handoff

• PlannerAgent：拿到用户问题，输出一份搜索计划（5-20 个搜索词+理由）
• SearchAgent：拿到单个搜索词，上网搜，写 2-3 段摘要
• WriterAgent：拿到全部摘要，写成 5-10 页的 Markdown 报告

用户问题
   ↓
PlannerAgent（一次）
   ↓ 输出 WebSearchPlan（N 个搜索项）
SearchAgent × N（asyncio 并发）
   ↓ 每个输出 300 词摘要
WriterAgent（一次，流式）
   ↓
结构化报告（short_summary + markdown + follow_up_questions）

PlannerAgent：不搜索的「规划师」

from openai.types.shared.reasoning import Reasoning
from pydantic import BaseModel
from agents import Agent, ModelSettings

class WebSearchItem(BaseModel):
    reason: str    # 为什么要搜这个词
    query: str     # 搜索词本身

class WebSearchPlan(BaseModel):
    searches: list[WebSearchItem]

planner_agent = Agent(
    name="PlannerAgent",
    instructions="You are a helpful research assistant. Given a query, "
                 "come up with a set of web searches to perform to best "
                 "answer the query. Output between 5 and 20 terms to query for.",
    model="gpt-5.5",
    model_settings=ModelSettings(reasoning=Reasoning(effort="medium")),
    output_type=WebSearchPlan,
)

result = await Runner.run(planner_agent, f"Query: {query}")
plan = result.final_output_as(WebSearchPlan)

SearchAgent + WebSearchTool：真正上网的那一步

from agents import Agent, WebSearchTool

search_agent = Agent(
    name="Search agent",
    model="gpt-5.5",
    instructions=(
        "You are a research assistant. Given a search term, you search the web "
        "for that term and produce a concise summary of the results. The summary "
        "must be 2-3 paragraphs and less than 300 words. Capture the main points. "
        "Write succinctly, no need to have complete sentences or good grammar. "
        "This will be consumed by someone synthesizing a report, so its vital "
        "you capture the essence and ignore any fluff."
    ),
    tools=[WebSearchTool()],
)

WebSearchTool 的全部参数

asyncio 并发：联动 #22 Parallelization

tasks = [asyncio.create_task(self._search(item)) for item in plan.searches]
results = []
for task in asyncio.as_completed(tasks):
    result = await task
    if result is not None:
        results.append(result)

WriterAgent：把碎片摘要变成完整报告

from pydantic import BaseModel
from agents import Agent, ModelSettings

class ReportData(BaseModel):
    short_summary: str          # 2-3 句话的执行摘要
    markdown_report: str        # 5-10 页完整 Markdown 报告
    follow_up_questions: list[str]  # 后续研究方向

writer_agent = Agent(
    name="WriterAgent",
    model="gpt-5-mini",
    model_settings=ModelSettings(reasoning=Reasoning(effort="medium")),
    output_type=ReportData,
    instructions="You are a senior researcher. You will be provided with the "
                 "original query and some initial research. You should first come up "
                 "with an outline for the report that describes the structure and "
                 "flow of the report. Then, generate the report and return that as "
                 "your final output.",
)

result = Runner.run_streamed(writer_agent, input=f"Original query: {query}\nSummarized search results: {search_results}")
async for event in result.stream_events():
    # 每 5 秒更新一次 UI 状态消息
    ...

HostedTool 三兄弟：Web / File / MCP 怎么选

3 条生产级建议