生产级 AI Agent 的难点不在“让它跑起来”，而在“让它一直跑对”。

# 脆弱的方式：在 Prompt 里硬编码 JSON 格式
prompt = """
分析以下文本，返回 JSON 格式：
{
   "sentiment": "positive/negative",
   "score": 0-100
}
"""

from pydantic import BaseModel
from typing import List

# 1. 定义严格的输出契约
class SentimentResult(BaseModel):
    sentiment: str  # 'positive' or 'negative'
    score: int       # 0-100

# 2. 在调用 LLM 时直接使用这个 Schema
# （以 Google ADK 为例，它会自动将 Schema 注入请求，并校验返回）
# result = await agent.run_async(prompt, output_schema=SentimentResult)

from enum import Enum
from typing import List, Optional
from pydantic import BaseModel

# 1. 定义 Agent 的状态
class AgentState(str, Enum):
    PLANNING = "planning"   # 规划阶段
    EXECUTING = "executing" # 执行阶段
    VERIFYING = "verifying" # 验证阶段
    COMPLETED = "completed" # 完成
    ERROR = "error"         # 错误

class PlanStep(BaseModel):
    step_id: str
    description: str
    tool_name: str
    tool_args: dict

class AgentContext(BaseModel):
    session_id: str
    state: AgentState
    user_input: str
    plan: Optional[List[PlanStep]] = None # 显式的执行计划
    intermediate_results: dict = {}       # 中间结果存储
    final_answer: Optional[str] = None

# 2. 核心路由逻辑（伪代码）
def router(context: AgentContext):
    if context.state == AgentState.PLANNING:
        # 调用 LLM 生成 PlanStep 列表，而不是直接调用工具
        context.plan = planner_agent.plan(context.user_input)
        context.state = AgentState.EXECUTING
        return context
    elif context.state == AgentState.EXECUTING:
        # 按顺序或并行执行计划中的步骤
        execute_next_step(context) # 这里会调用具体工具
        context.state = AgentState.VERIFYING
        return context
    elif context.state == AgentState.VERIFYING:
        # 检查上一步执行结果是否符合预期
        if verify_step(context):
            # 继续执行或结束
            context.state = AgentState.COMPLETED if plan_is_done else AgentState.EXECUTING
        else:
            # 触发重规划（Re-planning），而不是直接报错
            context.state = AgentState.PLANNING
        return context

# 简单的追踪装饰器思想
def trace_agent_step(func):
    async def wrapper(*args, **kwargs):
        step_id = generate_step_id()
        log_step_start(step_id, func.__name__, kwargs)
        try:
            result = await func(*args, **kwargs)
            log_step_end(step_id, result)
            return result
        except Exception as e:
            log_step_error(step_id, str(e))
            raise
    return wrapper