Watch an agent run
watch_agent_runRead-onlyIdempotent
Wait on one agent run and follow what its agent does, instead of polling get_agent_run. The call returns when the run ends, when its mission moves to another stage, or after maxSeconds. While it waits, each agent event (a thought, a tool call, a plan update, an error) is sent as a progress notification when the request has a progress token. The result has the status of the run, the stage of its mission, ended, the reason it returned, the last 20 events and a cursor. When the run is still running, call it again with since set to the cursor. A run that already ended returns at once. If your client ends a call after 60 seconds, set maxSeconds below that.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| since | No | The cursor from an earlier result. Only the events after it are sent | |
| sandboxId | Yes | Agent run id: the run's sandbox id, from list_agent_runs or get_mission | |
| maxSeconds | No | The longest time to wait, in seconds (default 300, at most 600) |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| hint | No | What to do next, when the run is still running | |
| ended | Yes | True when the run is no longer running | |
| stage | Yes | The stage of the run's mission when the call returned | |
| cursor | Yes | The id of the last event. Give it as since to continue | |
| events | Yes | The last 20 events at most, oldest first | |
| reason | Yes | Why the call returned: the run ended, its mission moved to another stage, or maxSeconds passed | |
| status | Yes | The status of the run when the call returned | |
| sandboxId | Yes |