Skip to content

Agent traces

Set up your agent

Give your coding agent a Steel browser and the Steel skills, so that it browses and writes Steel code the right way. Learn more

Install the Steel CLI. It signs you in and installs the skills for your coding agents.

curl -fsS https://setup.steel.dev | sh

Or send this prompt to your coding agent, and it does the same:

Read https://setup.steel.dev/install.md and follow it to set up Steel for this coding client.
Then continue my requested task using the installed Steel skill.

Set up your agent →

An agent trace is the timeline of the actions in a session: each click, input, scroll, drag, page load and error, with the page and element where it happened. Use it to find the step where an agent went wrong without watching the whole recording, to review what an agent did, or to turn a run into a script.

Steel builds the trace from what happened in the browser, not from what the agent says that it did. It holds the actions of every client connected to the session: your agent, your own scripts and a person in the live view.

Open the timeline

  1. Open the session viewer, the session's page in the Steel dashboard. Its URL is in sessionViewerUrl.
  2. Select the Agent Traces tab, next to Logs. If the panel is hidden, click Show traces and logs in the bar at the top of the page.

Each row is one action. It says what happened in a few words, such as Navigated to example.com, with the time since the session started. Steel groups small events into the actions that a person would describe. For example, a burst of typing is one input.

The timeline and the recording move together. Select a row to move the video to that moment. Expand a row to see its details: the element's role, name, text and selectors, the pointer or keys, and a picture from the recording near that moment.

Fetch traces from the API

Call sessions.agentTraces (sessions.agent_traces in Python, Sessions.AgentTraces in Go and sessions().agent_traces in Rust) to get the same timeline as JSON. It works while the session runs and after it ends. The method needs steel-sdk 0.21.0 or later, and the program below also needs Playwright:

npm install steel-sdk playwright

This program opens a page in a session, then prints the time and type of each action in the trace. Steel stores an event a moment after it happens, so the program reads the trace every 2 seconds until the load of example.com is there. It stops with an error after 30 seconds.

traces.mts
import Steel from "steel-sdk";
import { chromium } from "playwright";

type TraceEvent = { timestamp: string; type: string; navigation?: { url: string } };

const client = new Steel();
const session = await client.sessions.create();

async function readTrace(sessionId: string) {
  const trace = await client.sessions.agentTraces(sessionId);
  return trace.events as TraceEvent[];
}

try {
  const browser = await chromium.connectOverCDP(session.websocketUrl);
  const context = browser.contexts()[0];
  const page = context.pages()[0] ?? (await context.newPage());
  await page.goto("https://example.com");
  await browser.close();

  const deadline = Date.now() + 30_000;
  let events = await readTrace(session.id);
  while (!events.some((event) => event.navigation?.url.startsWith("https://example.com"))) {
    if (Date.now() > deadline) throw new Error("The trace has no load of example.com after 30 seconds.");
    await new Promise((resolve) => setTimeout(resolve, 2000));
    events = await readTrace(session.id);
  }
  for (const event of events) {
    console.log(event.timestamp, event.type);
  }
} finally {
  await client.sessions.release(session.id);
}

Run the program with your API key in STEEL_API_KEY:

npx tsx traces.mts

The trace has two events: the blank page that the session starts with, and the load of example.com.

2026-11-16T03:58:46.904Z navigate
2026-11-16T03:58:48.656Z navigate

The response has events (oldest first), total and hasMore. A click event looks like this:

{
  "type": "click",
  "timestamp": "2026-11-10T09:14:21.345Z",
  "page": { "url": "https://steel.dev/practice/login" },
  "target": {
    "role": "button",
    "accessibleName": "Login",
    "selector": { "css": "form#login > button" }
  },
  "pointer": { "x": 520, "y": 410 }
}

Every event has type and timestamp, and most events have page. An action that lasts some time has endTimestamp. When Steel can name the element, the event has target. Other fields depend on the type: pointer for a click, value for an input, keyboard for a key, navigation for a page load, and error for an error. Check that an event has target before you use it, because navigations and errors often have none.

Without limit, the call returns the whole trace. To read it in pages, pass limit, up to 1000, and offset. Both count actions, not raw events. Steel builds the trace from the session's first 10,000 raw events. To read part of a session, pass startTime and endTime as UTC times in ISO 8601. When Steel captured no browser actions in a session, as in older sessions, it builds a simpler trace from the session's CDP commands. If there are none, the list is empty.

Over HTTP, send GET /v1/sessions/{id}/agent-traces:

curl https://api.steel.dev/v1/sessions/$SESSION_ID/agent-traces \
  -H "steel-api-key: $STEEL_API_KEY"

GET /v1/sessions/{id}/agent-logs returns the raw CDP events behind the trace, such as Input.dispatchMouseEvent. The SDKs have no method for it. Use the trace unless you need those events.

With the CLI

The Steel CLI prints the trace, and follows new actions while the session runs:

steel sessions traces SESSION_ID --follow

Over the MCP server

The MCP server has a session_traces tool. It returns a session's newest clicks, key presses, form fills and page loads, one line each, with a CSS selector for each element, so that an agent can write a script that repeats them. It shows the length of typed text, never the text. MCP tools lists its inputs.

Export a trace

The Agent Traces tab has two exports, as buttons beside the tab names. On a phone, they are in the More actions menu.

ExportWhat you getUse it when
Copy tracesOne Markdown document on your clipboard, with a heading for each page and a numbered step for each action.Another agent or a teammate must read the run, or reproduce it.
Download tracesA ZIP file with the same Markdown document, as prompt.md, and a picture of each page from the recording. While the recording is not ready, you get the Markdown file alone.You attach the run to a bug report, a support ticket or an audit.

For the actions as JSON, use the API.

The Markdown export reads like a recipe. Paste it into Claude Code, Codex or Cursor with a request such as write me a Steel script that reproduces this run. A shortened example:

# Browser session

Recording of a real user's interaction with a web app, structured for replay by an automation agent. Read top to bottom.

## https://steel.dev/practice/login

1. `0:02.345` **Click** textbox "Username"
   - name: `username`
   - CSS: `input#username`
2. `0:04.802` **Type** <redacted, 20 chars> into textbox "Password"
   - name: `password`
   - CSS: `input#password`

*(idle 12s)*

3. `0:17.430` **Click** button "Login"
   - type: `submit`
   - CSS: `form#login > button`

Check that it worked

Print the session's sessionViewerUrl (session_viewer_url in Python) in the program in Fetch traces from the API, and open it after the run. In the Agent Traces tab, the timeline has the load of example.com that the program printed as its last navigate event. Select that row, and the recording moves to the moment that example.com loads.

Next steps