规划设计模式：任务分解 + 结构化输出 + 多 Agent 执行

flowchart TD
    User["用户: 帮我规划 7 天巴黎旅行，预算 $5000"] --> Planner["Planning Agent<br/>（负责'想'）"]
    Planner --> Plan["结构化 TravelPlan<br/>├─ #1 订航班 (flight_agent, high)<br/>├─ #2 订酒店 (hotel_agent, high, deps: [#1])<br/>├─ #3 订卢浮宫门票 (activity_agent, medium)<br/>├─ #4 订美食 tour (activity_agent, medium)<br/>└─ #5 订凡尔赛宫 (activity_agent, low)"]
    Plan --> Concierge["Concierge Agent<br/>（负责'做'）"]
    Concierge --> T1["book_flight → #FLT-4821"]
    Concierge --> T2["reserve_hotel → #HTL-2938"]
    Concierge --> T3["book_activity → #ACT-7742"]
    Concierge --> T4["book_activity → #ACT-1835"]
    Concierge --> Result["✅ 执行完毕，汇总结果"]

from pydantic import BaseModel
 
class TravelSubTask(BaseModel):
    task_id: int              # 子任务序号
    description: str          # 任务描述
    assigned_agent: str       # 指派给哪个专业 Agent
    priority: str             # high / medium / low
    dependencies: list[int] = []  # 依赖的子任务 ID（必须先完成的）
 
class TravelPlan(BaseModel):
    destination: str
    trip_duration_days: int
    subtasks: list[TravelSubTask]
    total_estimated_budget_usd: int
    notes: str

def create_travel_plan(user_request: str) -> TravelPlan:
    response = client.chat.completions.create(
        model=MODEL,
        messages=[
            {"role": "system", "content": (
                "You are a travel planning agent. When given a travel request:\n"
                "1. Break it into specific subtasks (flights, hotels, activities, logistics)\n"
                "2. Assign each subtask to the appropriate specialist agent\n"
                "3. Set priorities and identify dependencies between tasks\n"
                "4. Estimate the total budget\n\n"
                f"Output MUST be valid JSON matching this schema:\n{PLAN_SCHEMA_DESC}\n"
                "Reply with ONLY the JSON object, no other text."
            )},
            {"role": "user", "content": user_request},
        ],
        response_format={"type": "json_object"},
    )
    return TravelPlan.model_validate_json(response.choices[0].message.content)

# 三个执行工具
TOOLS_SCHEMA = [
    {"function": {"name": "book_flight", ...}},     # 预订航班
    {"function": {"name": "reserve_hotel", ...}},   # 预订酒店
    {"function": {"name": "book_activity", ...}},   # 预订活动
]
 
TOOL_MAP = {
    "book_flight": book_flight,
    "reserve_hotel": reserve_hotel,
    "book_activity": book_activity,
}

sequenceDiagram
    participant Concierge as Concierge Agent
    participant Flight as book_flight
    participant Hotel as reserve_hotel
    participant Activity as book_activity
 
    Concierge->>Flight: #1 订巴黎航班
    Flight-->>Concierge: #FLT-4821
    Concierge->>Hotel: #2 订巴黎酒店 (依赖 #1)
    Hotel-->>Concierge: #HTL-2938
    Concierge->>Activity: #3 卢浮宫门票 (依赖 #2)
    Activity-->>Concierge: #ACT-7742
    Concierge->>Activity: #4 美食 tour (依赖 #2)
    Activity-->>Concierge: #ACT-1835
    Concierge->>Activity: #5 凡尔赛宫 (依赖 #2, low priority)
    Activity-->>Concierge: #ACT-5591
    Concierge-->>User: 全部预订完成，汇总确认号

flowchart TD
    subgraph "第一层：数据模型"
        M1["TravelSubTask<br/>（Pydantic BaseModel）"]
        M2["TravelPlan<br/>（Pydantic BaseModel）"]
    end
 
    subgraph "第二层：规划"
        P1["Planning Agent<br/>（无工具，纯推理）"]
        P2["response_format={'type': 'json_object'}"]
        P3["model_validate_json()"]
    end
 
    subgraph "第三层：执行"
        E1["Concierge Agent<br/>（持有 3 个工具）"]
        E2["tool calling 循环"]
        E3["按依赖顺序执行"]
    end
 
    M1 --> M2
    M2 --> P1
    P1 --> P2 --> P3
    P3 --> E1
    E1 --> E2 --> E3

cd 07-planning-design/code_samples
 
# 原生版（步骤 1: 规划 → 步骤 2: 执行）
python 07-python-agent-framework.py
 
# 框架版
python 07-qwen-agent-framework.py