# 不好的描述
def search(query): """搜索"""

# 好的描述
def search(query: str, max_results: int = 5) -> list[dict]:
    """在内部知识库中搜索文档片段。

    何时使用：用户询问产品文档、政策、FAQ 等内部知识时。
    何时不用：用户问实时信息或公开事实时（用 web_search）。

    Args:
        query: 自然语言查询，不要超过 200 字符
        max_results: 返回片段数，1-20

    Returns:
        [{"text": str, "source_url": str, "score": float}, ...]
    """

用户：帮我找出最近一个月 Python 最受欢迎的 10 个开源项目

第一轮
  思考：我需要搜索 GitHub 上近期 Star 增长最快的 Python 项目
  行动：search_web("GitHub trending Python repositories last month")
  观察：返回搜索结果，包含多个项目列表

第二轮
  思考：结果不够精确，应该直接查询 GitHub Trending API
  行动：github_api("trending/repositories?language=python&since=monthly")
  观察：返回结构化的项目列表

第三轮
  思考：数据已获取，需要按 Star 增量排序并格式化
  行动：sort_and_format(data, key="stars_gained", limit=10)
  观察：格式化完成的 TOP10 列表

回答：以下是本月 GitHub 上最受欢迎的 10 个 Python 开源项目……

Planner（规划者）→ 拆解为子步骤列表
Executor（执行者）→ 逐步执行
Re-Planner（重规划者）→ 根据结果动态调整

Generator 生成初步输出
   ↓
Critic 评估质量、指出问题
   ↓
Generator 根据反馈修改
   ↓
（循环直到满足标准，或达到最大轮次）

失败案例 → 生成反思摘要 → 存入记忆数据库
新任务开始 → 检索相关历史反思 → 注入当前上下文 → 避免重蹈覆辙

Orchestrator（编排者）→ 拆解任务、分派角色、汇总结果
  ├─ Research Agent → 搜索和信息收集
  ├─ Analysis Agent → 数据分析
  ├─ Writing Agent → 内容生成
  └─ Review Agent → 质量检查

Agent A 提出方案
   ↓
Agent B 评估批判
   ↓
Agent C 整合优化

from langgraph.graph import StateGraph, START, END

# 1. 定义共享状态
class State(TypedDict):
    task: str
    search_results: list
    analysis: str
    report: str

# 2. 注册节点
graph = StateGraph(State)
graph.add_node("research", do_research)
graph.add_node("analysis", do_analysis)
graph.add_node("writing", do_writing)

# 3. 连边
graph.add_edge(START, "research")
graph.add_edge("research", "analysis")
graph.add_edge("analysis", "writing")
graph.add_edge("writing", END)

app = graph.compile()

triage = Agent(
    name="Triage",
    instructions="Route to the right specialist.",
    handoffs=[sales_agent, support_agent, tech_agent],
)
result = await Runner.run(triage, user_message)