Skip to content
Docs menu

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.

View .md

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.