Skip to content

Signals

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 →

Signals are labels that Steel adds to a session after the session ends. They mark events from the run, such as a CAPTCHA, a bot block or a proxy failure. Use them to find the sessions to check, without opening each recording. You do not set signals. To add your own labels, use metadata.

Before you begin

Put your Steel API key in the STEEL_API_KEY environment variable, and install the Steel SDK for your language: TypeScript, Python, Go or Rust.

Read a session's signals

A session's signals field is an array of signal names. It stays empty while the session runs, and Steel fills it in after the session ends.

This program creates a session with an inactivityTimeout of 5 seconds, so Steel releases it after 5 seconds without activity. The program does nothing in the session. It waits 20 seconds, then prints the session's signals as JSON.

signals.mts
import Steel from "steel-sdk";

const client = new Steel();
const session = await client.sessions.create({ inactivityTimeout: 5000 });

try {
  console.log(`Created session ${session.id}`);
  await new Promise((resolve) => setTimeout(resolve, 20_000));
  const { signals } = await client.sessions.retrieve(session.id);
  console.log(JSON.stringify(signals));
} finally {
  await client.sessions.release(session.id);
}

In Rust, the program also needs cargo add serde_json. Run the program:

npx tsx signals.mts

The session ended on its inactivityTimeout, so it has the signal session_timeout_exceeded:

Created session d14e97be-2e61-4f5f-880e-189558bd4bc3
["session_timeout_exceeded"]

A session that hit a CAPTCHA and a bot block has this list:

["captcha_encountered", "bot_detection_triggered"]

Signals reference lists every signal and what it means. It also explains why an empty list does not prove that nothing happened. To learn why a session ended, read its releaseReason. See Session lifecycle.

The sessions that sessions.list returns carry the same field. The dashboard shows signals in the session list and in the session viewer.

Show signals in your app

Steel can add new signal names over time, so handle names that you do not know. To show signals in your own app without a fixed list, call sessions.signalCatalog (sessions.signal_catalog in Python, Sessions.SignalCatalog in Go and sessions().signal_catalog in Rust). It returns each current signal with a label, a description and a severity of info, warning, danger or success.

const catalog = await client.sessions.signalCatalog();
for (const signal of catalog.signals) {
  console.log(signal.value, signal.label, signal.severity);
}

Find sessions by signal

Pass signal to sessions.list to find the sessions that carry a signal. If you pass several signals, a session must carry all of them. Add metadata to narrow the search to one job or one customer.

for await (const session of client.sessions.list({
  metadata: { job_id: "job-1042" },
  signal: ["bot_detection_triggered"],
})) {
  console.log(session.id, session.signals);
}

In Rust, this code needs cargo add futures-util.

Over HTTP, repeat the signal parameter for each signal:

curl -G https://api.steel.dev/v1/sessions \
  -H "steel-api-key: $STEEL_API_KEY" \
  --data-urlencode "signal=captcha_encountered" \
  --data-urlencode "signal=bot_detection_triggered"

The list leaves out failed sessions unless you pass status or releaseReason.

Check that it worked

List the sessions that carry session_timeout_exceeded, as Find sessions by signal shows. The session that the program in Read a session's signals created is in the list, with the signal that the program printed. The dashboard's session list shows the same signal for it.

Next steps