# resume\_agent

Resume an agent on its existing conversation, such as when its pane died.

writes · idempotent · MCP tool · [Agent](https://komrad.dev/latest/api/agent.md)

An archived agent must be restored first. A reviewer may resume only its task's writer, a writer only its task's reviewers, and either may resume its workflow's orchestrator.

## Calling it

```bash
curl -X POST http://127.0.0.1:8787/komrad.agent.v1.AgentService/ResumeAgent \
  -H 'Content-Type: application/json' \
  -d '{
  "id": "<id>"
}'
```

```bash
komrad rpc resume-agent \
  --id '<uuid>'
```

```json
{
  "name": "resume_agent",
  "arguments": {
    "id": "<id>"
  }
}
```

Offered by the komrad MCP server to writer, reviewer, orchestrator agents.

## Request

### ResumeAgentRequest

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-ResumeAgentRequest-id) | uuid\* | The dormant agent to resume, by id. |

## Response

### ResumeAgentResponse

| Field | Type | Description |
| --- | --- | --- |
| [`agent`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-ResumeAgentResponse-agent) | [Agent](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent) | The agent as resumed, running. |

## Types

### Agent

Agent is one CLI conversation that komrad runs in a pane and tracks.

| Field | Type | Description |
| --- | --- | --- |
| [`id`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-id) | uuid\* | The agent's id. Mail is addressed to it. |
| [`name`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-name) | string | The agent's name. It is also the agent's tmux window name at launch. |
| [`cwd`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-cwd) | string | The directory of the agent's checkout. |
| [`flags`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-flags) | string | The command-line flags the agent's CLI started with. |
| [`prompt`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-prompt) | string | The agent's prompt. |
| [`pane_id`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-pane_id) | string | The tmux pane the agent's CLI runs in. |
| [`state`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-state) | [AgentState](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-AgentState) | What komrad last read the agent to be doing. |
| [`session_id`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-session_id) | string | The CLI's own id for the agent's conversation. A resume needs it. |
| [`harness`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-harness) | string | The harness the agent runs, such as `claude` or `codex`. |
| [`workflow_id`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-workflow_id) | uuid\* | The id of the workflow the agent belongs to. |
| [`created_at`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-created_at) | timestamp | When the agent was created. |
| [`archived_at`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-archived_at) | timestamp | When the agent was archived. Unset while the agent is live. |
| [`schedule_id`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-schedule_id) | uuid | The id of the schedule that created the agent. Unset when a person or an agent created it. |
| [`alive`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-alive) | bool | Whether the agent's pane exists. A dormant agent has none. |
| [`idempotency_key`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-idempotency_key) | string | The idempotency key the agent's create carried. |
| [`spawned_by_agent_id`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-spawned_by_agent_id) | uuid | The id of the agent that created this agent. Unset when the person created it. |
| [`failed_run`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-failed_run) | bool | Whether a hook run for the agent failed and the person has not opened its log since. |
| [`failed_run_log`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-failed_run_log) | int32 | The id of the log of the agent's failed hook run. Unset when no run failed. |
| [`state_changed_at`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-state_changed_at) | timestamp | When the agent's state last changed. |
| [`reported_reason`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-reported_reason) | string | What the agent's CLI hooks last reported the agent doing. |
| [`failure_reason`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-failure_reason) | string | Why the agent's create or cleanup last failed. Empty when neither has failed. |
| [`turn_error`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-turn_error) | string | What the CLI printed when an API error ended the agent's last turn. Empty when that turn did not fail. |
| [`role`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-role) | [AgentRole](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-AgentRole) | What the agent was launched to do. |
| [`task_id`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-task_id) | uuid | The id of the agent's task. Unset for an orchestrator, or once the task is deleted. |
| [`task_slug`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-task_slug) | string | The slug of the agent's task. Unset whenever [`task_id`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-task_id) is. |
| [`provision_disabled`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-provision_disabled) | bool | Whether the agent was told to work in the workflow's directory instead of a worktree. |
| [`hooks`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-hooks) | string\[\] | The CLI hooks the agent's latest launch installed, as the CLI names its events. Empty when that launch failed or never ran. |
| [`turn_ended_at`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-turn_ended_at) | timestamp | When the agent's last turn ended. Unset until its first turn ends. |
| [`turn_failure_kind`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-turn_failure_kind) | [TurnFailureKind](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-TurnFailureKind) | Why an error ended the agent's last turn. Unspecified when that turn did not fail. |
| [`turn_retries`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-turn_retries) | int32 | How many times komrad has retried the agent's failed turns since a turn last ended without an error. |
| [`turn_retry_at`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-Agent-turn_retry_at) | timestamp | When komrad next retries the agent's failed turn. Unset when no retry is waiting. |

### AgentState

AgentState is what komrad last read an agent to be doing, from the end of its pane.

| Value | Description |
| --- | --- |
| [`idle`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-AgentState-idle) | The CLI is at rest with nothing typed. |
| [`thinking`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-AgentState-thinking) | The CLI is working on a turn. |
| [`waiting`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-AgentState-waiting) | The CLI is waiting for the person to answer a selection. |
| [`setting_up`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-AgentState-setting_up) | The agent is launching and doesn't have a pane to read yet. |
| [`failed_to_create`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-AgentState-failed_to_create) | The launch failed. [`retry_agent`](https://komrad.dev/latest/api/agent/retry-agent.md) launches the agent again. |
| [`failed_to_cleanup`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-AgentState-failed_to_cleanup) | A delete failed to clean up after the agent. `failure_reason` says why. |
| [`uncertain`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-AgentState-uncertain) | The pane could be read, but its end showed no known state. |
| [`errored`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-AgentState-errored) | The CLI is at rest after an API error ended the last turn. `turn_error` names the error. |

### AgentRole

AgentRole is what an agent was launched to do.

| Value | Description |
| --- | --- |
| [`reviewer`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-AgentRole-reviewer) | An agent on a task that reads the writer's change and gives a review. |
| [`orchestrator`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-AgentRole-orchestrator) | The one agent per workflow that hands work out across its tasks. |
| [`writer`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-AgentRole-writer) | The one agent on a task that changes its checkout. |

### TurnFailureKind

TurnFailureKind is why an error ended an agent's turn, whichever CLI ran it.

| Value | Description |
| --- | --- |
| [`cut_off`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-TurnFailureKind-cut_off) | The machine slept or the connection dropped mid-response. Komrad retries the turn. |
| [`unreachable`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-TurnFailureKind-unreachable) | The API did not answer after the CLI's own retries. Komrad retries the turn. |
| [`rate_limited`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-TurnFailureKind-rate_limited) | The account hit its usage limit. Komrad retries the turn once the limit resets. |
| [`other`](https://komrad.dev/latest/api/agent/resume-agent.md#komrad-agent-v1-TurnFailureKind-other) | Any other error, such as a billing or auth error. Komrad does not retry the turn. |
