---
title: Agent processes
description: 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.
section: server-api
order: 50
audience: [builder, agent]
sources: [packages/harness-server/openapi.yaml, packages/harness-server/src/server.ts, docs/adr/0009-agent-runtime.md]
features: [server-api.sessions-agents]
---

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 {#list}

`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.

```bash
curl -s "$S/v1/sessions/$SID/agents?top=5" -H "Authorization: Bearer $TOKEN"
```

```python
for a in client.agents(sid, top=5):
    print(a["info"]["pid"], a["tokensPerSec"])
```

```ts
const { agents } = await client.listAgents(sid, { top: 5 });
```

## Signal a process {#signal}

`POST /v1/sessions/{sessionId}/agents/{pid}/signal` (`signalAgent`) sends a signal to one process:

```bash
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"}'
```

```python
client.signal_agent(sid, 3, "SIGINT", tree=True)
```

```ts
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 {#model}

`POST /v1/sessions/{sessionId}/agents/{pid}/model` (`switchAgentModel`) with `{"model": "qwen-fast"}` switches that agent's model:

```python
client.switch_model(sid, 1, "qwen-fast")
```

```ts
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](/docs/server-api/operations.md#gears), 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`.

## Related pages

- [Events](/docs/server-api/events.md#harness): `agent`, `span` and `call`
- [Sessions](/docs/server-api/sessions.md)
