komrad

create_agent

Create an agent and launch it with a prompt.

writesnot idempotentMCP toolAgent

The agent works in the workflow's directory, in a worktree of its own unless provision_enabled is false. With task_id or task_slug set, the agent becomes the task's writer when the task has none, and otherwise a reviewer in the writer's checkout. With neither set, komrad creates a task with the agent as its writer, and the agent returned carries its task_id and task_slug.

Calling it#

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

Request#

CreateAgentRequest#

FieldTypeDescription
promptstring*

at most 50000 characters

The agent's prompt, which is all the agent has to go on.

titlestring

at most 200 characters

must not contain control characters

The agent's name. Empty to have komrad name the agent.

flagsstring

at most 500 characters

must not contain shell metacharacters

The flags for the agent's CLI. Empty to use the workflow's flags.

workflow_iduuid*

The workflow to create the agent in, by id. The agent uses the workflow's directory, flags and context.

harnessstring

at most 40 characters

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

The harness to run. Empty to use the workflow's harness.

idempotency_keystring

not empty

at most 200 characters

A key that makes a retry safe. A repeat with the same key returns the agent already created.

provision_enabledbool

Whether the agent gets a worktree of its own. False keeps the agent in the workflow's directory. Unset to follow the workflow.

one of

The task in workflow_id to put the agent on. Unset to create a task with the agent as its writer. An agent that joins as a reviewer cannot set provision_enabled to true.

task_iduuid

The task, by id.

task_slugstring

not empty

The task, by slug.

new_task_slugstring

at most 80 characters

matching ^[a-z0-9]+(-[a-z0-9]+)*$

The slug of the task komrad creates when the call doesn't name one. A task can't take a slug another task has used. Unset to derive one from the agent's name.

new_task_goalstring

at most 50000 characters

The goal of the task komrad creates when no task is named, in markdown. Empty to use the first line of the prompt.

one of

The task in workflow_id the new task depends on. The new task's branch starts from that task's branch on origin, and komrad rebases it as that branch moves and re-targets it onto the base branch once that task merges. Unset to start from the workflow's base branch. Cannot be set with a task to put the agent on.

depends_on_iduuid

The task, by id.

depends_on_slugstring

not empty

The task, by slug.

Response#

CreateAgentResponse#

FieldTypeDescription
agentAgent

The agent as created.

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.