# Agent Steps

Agent Steps is the execution visualizer on the right side of the **Chat** page. It shows exactly what the agent did to process each conversation message — in real time.

## What Users See

When a user sends a message in the webchat (left panel), the Agent Steps panel (right panel) shows the execution flow as a sequence of collapsible cards:

```
┌─ User Message: "Help me with order #123"
│
├─ 🤖 Bot Handler (onWebchatConversation)
│   ├─ Iteration 1
│   │   ├─ 🟣 Tool: lookupOrder (input: {orderId: "123"})
│   │   └─ → continued
│   ├─ Iteration 2
│   │   ├─ 🔵 Message: "I found order #123. It was shipped yesterday..."
│   │   └─ → message_sent
│   └─ 🟢 State: conversation.lastOrderId = "123"
│
└─ Total: 2 iterations, $0.0034, 1.2s
```

## Data Model

### Turns

A **Turn** is one conversation exchange — from the user's input through the agent's complete response. Each turn contains:

- **User message** or **event** that triggered processing
- **Handler span** — the conversation/event/trigger handler that processed it
- **Steps** — autonomous iterations (the agent's think-decide-act loops)
- **Direct messages** — messages sent outside iterations
- **State mutations** — state changes made during the turn
- **Total cost** — aggregated AI cost across all iterations

### Steps (Autonomous Iterations)

Each **Step** is one iteration of the autonomous agent loop. The agent:

1. Receives context (conversation history, available tools)
2. Makes an LLM call (the **cognitive request**)
3. Decides what to do: call a tool, send a message, or stop

Each step shows:

- **Iteration number** (1, 2, 3...)
- **Exit reason**: "continued" (more work to do), "tool_called", "message_sent", "errored"
- **Cognitive request** metadata: model, input/output tokens, cost, duration
- **Tools called** in this iteration
- **Messages sent** in this iteration

### Tool Calls

Displayed as **violet cards** (or green for `search_knowledge`). Each shows:

- Tool name
- Input (JSON)
- Output (JSON or markdown for knowledge search results)
- Duration
- Status (ok / error / running)

### Bot Messages

Displayed as **blue cards**. Each shows:

- Message content (markdown rendered)
- Duration
- Long messages are clamped at 300 characters — click to expand

### State Mutations

Displayed as **teal cards**. Each shows:

- State type (bot, user, conversation)
- Two-column "Before" and "After" view
- Only changed keys shown by default (toggle for full state)
- JSON tree view for complex objects

### Trigger Handlers

When a trigger fires instead of a conversation message, the turn shows an **amber card** with:

- Trigger name
- Event type that fired it
- Same iteration/tool/message structure inside

## Status Indicators

| Visual                       | Meaning                                |
| ---------------------------- | -------------------------------------- |
| ✓ Green checkmark            | Completed successfully                 |
| ✗ Red X                      | Failed (error message in detail panel) |
| ⟳ Blue spinner               | Currently executing                    |
| Shimmer text ("thinking...") | LLM is generating                      |

## AI Metrics

Each iteration's cognitive request shows:

- **Model**: e.g., "claude-3.5-sonnet"
- **Input tokens**: count + cost
- **Output tokens**: count + cost
- **Total cost**: USD with 4 decimal places
- **Duration**: milliseconds

Turn-level cost is the sum of all iteration costs.

## Interactions

- **Collapse/Expand**: Click any card to toggle children. "Collapse All" / "Expand All" buttons in header.
- **Detail Panel**: Click a step to open a resizable detail panel on the right with full span data.
- **Copy**: Copy buttons on IDs, tokens, error messages.
- **Open Traces**: "Open conversation traces" link in the header navigates to the full Traces page filtered to this conversation.

## Real-Time Updates

Agent Steps streams data via SSE (Server-Sent Events):

- Running spans show a live timer
- New spans animate in from the top
- Auto-scrolls to bottom when new content arrives
- Stale detection marks spans as errored if the CLI stops sending updates for 5+ seconds