[!info] related notes

• 所属 MOC: Agent Runtime MOC
• 上游: Run
• 并列: Run State, Trace

Step

一句话定义

Step 是 Agent Run 内的单次推理-动作循环。一次 Step 通常包含：调用 LLM → LLM 返回响应 → 如果有 tool_call 则执行工具 → 结果回传。一个 Run 由 1 到 N 个 Step 组成。

核心原理

Step 数据结构

@dataclass
class Step:
    id: str
    run_id: str
    step_index: int
    type: str  # "llm_call", "tool_execution", "human_input"

    # LLM 调用信息
    llm_input: dict = None   # 发给 LLM 的 messages
    llm_output: dict = None  # LLM 的响应

    # 工具调用信息
    tool_calls: list = None
    tool_results: list = None

    # 资源消耗
    input_tokens: int = 0
    output_tokens: int = 0
    duration_ms: int = 0

    # 状态
    status: str = "pending"  # pending, running, completed, failed
    error: str = None

Step 与 Run 的关系

Run (run_001)
├── Step 0: LLM Call → 决定调用 search_knowledge
│   input_tokens: 1200, output_tokens: 50, duration: 2300ms
├── Step 1: Tool Execution → search_knowledge 执行
│   duration: 450ms
├── Step 2: LLM Call → 决定调用 create_chart
│   input_tokens: 1800, output_tokens: 80, duration: 3100ms
├── Step 3: Tool Execution → create_chart 执行
│   duration: 1200ms
└── Step 4: LLM Call → 生成最终回复
    input_tokens: 2000, output_tokens: 500, duration: 4500ms

Step 记录

class StepRecorder:
    def __init__(self, run_id: str):
        self.run_id = run_id
        self.steps = []
        self.current_step = 0

    def begin_step(self, step_type: str) -> Step:
        step = Step(
            id=generate_id(),
            run_id=self.run_id,
            step_index=self.current_step,
            type=step_type,
            status="running",
        )
        self.steps.append(step)
        return step

    def end_step(self, step: Step, status: str = "completed"):
        step.status = status
        self.current_step += 1

常见坑

1. Step 和 Tool Call 混淆: 一个 Step 可能包含多个 tool_call
2. 不记录 Step: 无法知道 Agent 执行了几步
3. Step 粒度太细: 每个 token 都算一个 Step

参考资料

• Run
• Agent Loop