Agent processes
List a session's agent and subagent processes with their rates, signal one to pause, interrupt or stop it, and switch an agent's model mid-session.
Inside a session, the main agent and every subagent it starts with the task tool run as processes with a pid, much like an operating system's. The main agent is pid 1. These routes are ps, top and kill for them.
List processes
GET /v1/sessions/{sessionId}/agents (listAgents) returns {agents: [...]}, one entry per process:
| Field | What |
|---|---|
info |
The process: pid, parent, agent type, state (running, blocked, …), model and more (ProcInfo in the API reference) |
ageMs |
Milliseconds since it started (to its exit, for an exited process) |
waitMs |
How long a blocked process has waited |
tokensPerSec, toolCallsPerMin |
Rates over the interval since your previous call for this session (a lifetime average the first time) |
?top=N (1 to 100) keeps the N processes with the highest tokensPerSec, highest first. GET /v1/sessions/{sessionId}/agents/{pid} (getAgent) returns one process with lifetime rates; 404 agent_not_found once it is reaped.
curl -s "$S/v1/sessions/$SID/agents?top=5" -H "Authorization: Bearer $TOKEN"for a in client.agents(sid, top=5):
print(a["info"]["pid"], a["tokensPerSec"])const { agents } = await client.listAgents(sid, { top: 5 });Signal a process
POST /v1/sessions/{sessionId}/agents/{pid}/signal (signalAgent) sends a signal to one process:
curl -s -X POST $S/v1/sessions/$SID/agents/3/signal -H "Authorization: Bearer $TOKEN" \
-H 'content-type: application/json' -d '{"signal": "SIGSTOP", "reason": "waiting for review"}'client.signal_agent(sid, 3, "SIGINT", tree=True)await client.signalAgent(sid, 3, "SIGCONT");| Field | Type | What |
|---|---|---|
signal |
SIGINT, SIGTERM, SIGKILL, SIGSTOP, SIGCONT, SIGUSR1, SIGUSR2, SIGCHLD |
required |
tree |
boolean | Also its live descendants, deepest first |
reason |
string, up to 200 characters | Recorded on the signal's span and event (default POST /signal) |
| Signal | Effect |
|---|---|
SIGINT |
Aborts its current model request or tool at once; a subagent returns a partial report and its parent goes on. A second SIGINT to a tree root within a second becomes SIGTERM. |
SIGTERM |
Stops it at its next turn boundary, with a partial report |
SIGKILL |
Stops it at once |
SIGSTOP |
Parks it as blocked(paused) at its next turn boundary, with no request in flight, until SIGCONT |
SIGCONT |
Wakes a stopped process at once |
SIGUSR1, SIGUSR2, SIGCHLD |
Delivered at its next turn boundary, for the agent's own handling |
The answer is {pid, signal, tree, delivery}. delivery is now, safe-point (its next turn boundary) or deferred (inside a critical section, the stopping signals wait for it to end). What happened shows on the event stream as agent state changes and span events with kind: signal. 404 agent_not_found for a pid that is not live in the session.
Switch a model
POST /v1/sessions/{sessionId}/agents/{pid}/model (switchAgentModel) with {"model": "qwen-fast"} switches that agent's model:
client.switch_model(sid, 1, "qwen-fast")await client.switchModel(sid, 1, "qwen-fast");The answer is {pid, model, applied, cacheLost: true}. The main agent with no run active switches now; otherwise, and for a subagent, at its next turn-boundary, before its next request. The new model has no cached copy of the prompt; a context over its compaction threshold is compacted first, and a notice event says so. To move a session to a gear, post the gear's model for pid 1.
Errors: 400 unknown_model (the session's provider doesn't list it; the message names the ones it does; provider/id is accepted) or bad_request, 403 policy_forbidden (another provider's model while the organisation policy pins the orchestrator), 404 agent_not_found.