komrad

restart_agent

Restart a task's writer or a workflow's orchestrator on a new conversation.

writesnot idempotentdestructiveMCP toolAgent

A writer's prompt is built from its task's notes and checkout. The agent keeps its harness and flags unless others are named, and its old conversation stays in its transcript. A task's reviewers keep running. An agent may not restart an orchestrator.

Calling it#

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

Request#

RestartAgentRequest#

FieldTypeDescription
iduuid*

The writer or orchestrator to restart, by id.

notestring

at most 50000 characters

Text to add to the agent's prompt. Empty to add nothing.

harnessstring

at most 40 characters

matching ^[a-z0-9-]*$

The harness to move the agent to. Empty to keep the agent's harness.

flagsstring

at most 500 characters

must not contain shell metacharacters

The flags for the agent's CLI. Empty to keep the agent's flags, or, when harness changes, to use the workflow's flags if the workflow runs that harness and the CLI's default flags if not.

Response#

RestartAgentResponse#

FieldTypeDescription
agentAgent

The agent as restarted, running.

Types#

Agent#

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

FieldTypeDescription
iduuid*

The agent's id. Mail is addressed to it.

namestring

The agent's name. It is also the agent's tmux window name at launch.

cwdstring

The directory of the agent's checkout.

flagsstring

The command-line flags the agent's CLI started with.

promptstring

The agent's prompt.

pane_idstring

The tmux pane the agent's CLI runs in.

stateAgentState

What komrad last read the agent to be doing.

session_idstring

The CLI's own id for the agent's conversation. A resume needs it.

harnessstring

The harness the agent runs, such as claude or codex.

workflow_iduuid*

The id of the workflow the agent belongs to.

created_attimestamp

When the agent was created.

archived_attimestamp

When the agent was archived. Unset while the agent is live.

schedule_iduuid

The id of the schedule that created the agent. Unset when a person or an agent created it.

alivebool

Whether the agent's pane exists. A dormant agent has none.

idempotency_keystring

The idempotency key the agent's create carried.

spawned_by_agent_iduuid

The id of the agent that created this agent. Unset when the person created it.

failed_runbool

Whether a hook run for the agent failed and the person has not opened its log since.

failed_run_logint32

The id of the log of the agent's failed hook run. Unset when no run failed.

state_changed_attimestamp

When the agent's state last changed.

reported_reasonstring

What the agent's CLI hooks last reported the agent doing.

failure_reasonstring

Why the agent's create or cleanup last failed. Empty when neither has failed.

turn_errorstring

What the CLI printed when an API error ended the agent's last turn. Empty when that turn did not fail.

roleAgentRole

What the agent was launched to do.

task_iduuid

The id of the agent's task. Unset for an orchestrator, or once the task is deleted.

task_slugstring

The slug of the agent's task. Unset whenever task_id is.

provision_disabledbool

Whether the agent was told to work in the workflow's directory instead of a worktree.

hooksstring[]

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_attimestamp

When the agent's last turn ended. Unset until its first turn ends.

turn_failure_kindTurnFailureKind

Why an error ended the agent's last turn. Unspecified when that turn did not fail.

turn_retriesint32

How many times komrad has retried the agent's failed turns since a turn last ended without an error.

turn_retry_attimestamp

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.

ValueDescription
idle

The CLI is at rest with nothing typed.

thinking

The CLI is working on a turn.

waiting

The CLI is waiting for the person to answer a selection.

setting_up

The agent is launching and doesn't have a pane to read yet.

failed_to_create

The launch failed. retry_agent launches the agent again.

failed_to_cleanup

A delete failed to clean up after the agent. failure_reason says why.

uncertain

The pane could be read, but its end showed no known state.

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.

ValueDescription
reviewer

An agent on a task that reads the writer's change and gives a review.

orchestrator

The one agent per workflow that hands work out across its tasks.

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.

ValueDescription
cut_off

The machine slept or the connection dropped mid-response. Komrad retries the turn.

unreachable

The API did not answer after the CLI's own retries. Komrad retries the turn.

rate_limited

The account hit its usage limit. Komrad retries the turn once the limit resets.

other

Any other error, such as a billing or auth error. Komrad does not retry the turn.