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>"
}'komrad rpc create-agent \
--prompt '<string>' \
--workflow-id '<uuid>'{
"name": "create_agent",
"arguments": {
"prompt": "<prompt>",
"workflow_id": "<workflow_id>"
}
}Offered by the komrad MCP server to writer, orchestrator agents.
Request#
CreateAgentRequest#
| Field | Type | Description |
|---|---|---|
prompt | string* at most 50000 characters | The agent's prompt, which is all the agent has to go on. |
title | string at most 200 characters must not contain control characters | The agent's name. Empty to have komrad name the agent. |
flags | string at most 500 characters must not contain shell metacharacters | The flags for the agent's CLI. Empty to use the workflow's flags. |
workflow_id | uuid* | The workflow to create the agent in, by id. The agent uses the workflow's directory, flags and context. |
harness | string at most 40 characters matching ^[a-z0-9-]*$ | The harness to run. Empty to use the workflow's harness. |
idempotency_key | string 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_enabled | bool | 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 | |
task_id | uuid | The task, by id. |
task_slug | string not empty | The task, by slug. |
new_task_slug | string 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_goal | string 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 | |
depends_on_id | uuid | The task, by id. |
depends_on_slug | string not empty | The task, by slug. |
Response#
CreateAgentResponse#
Types#
Agent#
Agent is one CLI conversation that komrad runs in a pane and tracks.
| Field | Type | Description |
|---|---|---|
id | uuid* | The agent's id. Mail is addressed to it. |
name | string | The agent's name. It is also the agent's tmux window name at launch. |
cwd | string | The directory of the agent's checkout. |
flags | string | The command-line flags the agent's CLI started with. |
prompt | string | The agent's prompt. |
pane_id | string | The tmux pane the agent's CLI runs in. |
state | AgentState | What komrad last read the agent to be doing. |
session_id | string | The CLI's own id for the agent's conversation. A resume needs it. |
harness | string | The harness the agent runs, such as |
workflow_id | uuid* | The id of the workflow the agent belongs to. |
created_at | timestamp | When the agent was created. |
archived_at | timestamp | When the agent was archived. Unset while the agent is live. |
schedule_id | uuid | The id of the schedule that created the agent. Unset when a person or an agent created it. |
alive | bool | Whether the agent's pane exists. A dormant agent has none. |
idempotency_key | string | The idempotency key the agent's create carried. |
spawned_by_agent_id | uuid | The id of the agent that created this agent. Unset when the person created it. |
failed_run | bool | Whether a hook run for the agent failed and the person has not opened its log since. |
failed_run_log | int32 | The id of the log of the agent's failed hook run. Unset when no run failed. |
state_changed_at | timestamp | When the agent's state last changed. |
reported_reason | string | What the agent's CLI hooks last reported the agent doing. |
failure_reason | string | Why the agent's create or cleanup last failed. Empty when neither has failed. |
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 | AgentRole | What the agent was launched to do. |
task_id | uuid | The id of the agent's task. Unset for an orchestrator, or once the task is deleted. |
task_slug | string | The slug of the agent's task. Unset whenever |
provision_disabled | bool | Whether the agent was told to work in the workflow's directory instead of a worktree. |
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 | timestamp | When the agent's last turn ended. Unset until its first turn ends. |
turn_failure_kind | TurnFailureKind | Why an error ended the agent's last turn. Unspecified when that turn did not fail. |
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 | 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 | 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. |
failed_to_cleanup | A delete failed to clean up after the agent. |
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. |
AgentRole#
AgentRole is what an agent was launched to do.
| Value | Description |
|---|---|
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.
| Value | Description |
|---|---|
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. |