create_agent

Launch a background agent with an opening prompt.

Agentwritesnot idempotentMCP tool

Requires an absolute or ~-prefixed directory: this spawns a real agent in a real tmux window, and a relative path would point somewhere unpredictable. Each call spawns another agent, so do not retry a call that may have succeeded. There is a ceiling on how many agents may exist at once, and a call past it is refused as resource_exhausted; that means there is no room rather than something being broken, so stop and tell the user instead of trying again. Set parentAgentId to attach the new agent to an existing one as its child, passing your own id from KOMRAD_AGENT_ID, which is the shape for an agent that reads the tree you are in: reach for a child whenever that is what the new agent does, and leave it off when the new agent writes work of its own and so needs a checkout of its own, or when the person asking said they wanted an agent standing on its own. Set provisionEnabled to false to keep the directory you named rather than be given one: that is how an agent reads a checkout somebody else already has open, and it is what the reviewer case wants. Leave it unset to do whatever the workflow does. A child runs in its parent's directory and provisions nothing of its own, so dir and provisionEnabled are both refused rather than quietly overridden, and workflowId is still required but has to be the parent's own. It may only mail its parent and its parent's other children, it goes when the parent goes, and it cannot be restored on its own while the parent stays archived. A child may not have children of its own, and neither may an orchestrator: it is drawn on its workflow's own row rather than a row of its own, so a child of it would be drawn nowhere at all, and a parentAgentId naming one is refused. An orchestrator fans read-only work out as an ordinary agent in its workflow with provisionEnabled false, which gives that agent a row, a mailbox and the workflow's own directory to read.

Calling it#

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

komrad rpc create-agent \
  --prompt <string> \
  --workflow-id <string>

{
  "name": "create_agent",
  "arguments": {
    "prompt": "<prompt>",
    "workflowId": "<workflowId>"
  }
}

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

Request#

CreateAgentRequest#

Field	Type	Description
`prompt`	string	The opening briefing, which is everything the agent has to go on. required, at most 50000 characters
`title`	string	What to call it in the panel, blank to have komrad name it. at most 200 characters
`dir`	string	Where to start it, absolute or ~-prefixed, blank to take the workflow's own. at most 4096 characters
`flags`	string	Flags for its CLI, blank to take the workflow's own. at most 500 characters
`workflowId`	string	Which workflow to launch it into, whose cwd, flags and context it inherits. required
`harness`	string	Which CLI to run, blank to take the workflow's own. at most 40 characters, matching ^[a-z0-9-]*$
`idempotencyKey`	string	A key that makes a retry safe, since a repeat carrying it is answered with the agent it already launched. at most 200 characters
`provisionEnabled`	bool	False to keep the directory named above rather than be given a worktree, which is how an agent reads a checkout somebody else has open.
`parentAgentId`	string	Which agent to attach this one to as its child, which then runs in that agent's directory and goes when it goes.

Response#

CreateAgentResponse#

Field	Type	Description
`agent`	Agent	The agent as launched, whose id is what mail is addressed to.

Types#

Agent#

Field	Type	Description
`id`	string	The handle every other call names this agent by, and what mail is addressed to.
`name`	string	What the panel lists it as, which is also its tmux window name at launch.
`cwd`	string	The directory it is running in, its own worktree when the workflow provisions one.
`flags`	string	The command-line flags its CLI was started with.
`prompt`	string	The whole briefing it was launched with.
`paneId`	string	The tmux pane its CLI is running in, which is what capture-pane reads.
`state`	AgentState	What the panel last decided it was doing, read off the tail of its pane.
`sessionId`	string	The CLI's own conversation id, which is the handle a resume needs.
`harness`	string	Which CLI it runs, such as claude or codex.
`workflowId`	string	Which workflow it is filed under, whose context it took at launch.
`createdAt`	string	When it was launched, in RFC 3339.
`archivedAt`	string	When it was hidden from the panel, unset while it is live.
`scheduleId`	string	The schedule that launched it, unset for an agent a person or another agent spawned.
`alive`	bool	Whether its pane is still there, which a dormant agent's is not.
`hidden`	bool	Whether the panel draws a row for it, which changes nothing about the agent itself.
`metadata`	list of AgentMetadata	Facts it has recorded about its own work, such as the ticket it is implementing.
`idempotencyKey`	string	The key a retry of its create carried, which is what answers a repeat with this agent.
`spawnedByAgentId`	string	Which agent called create, unset for one a person spawned.
`parentAgentId`	string	The agent this one is attached to, where spawned_by_agent_id is only who called create.
`branch`	string	The git branch its worktree is on, unset for an agent that provisions none.
`repositoryUrl`	string	The canonical web address of the repository its checkout pushes to, such as https://github.com/harrisoncramer/komrad, unset when the checkout is gone or its origin is not a forge.
`headSha`	string	The commit its checkout has checked out, unset when the checkout is gone or git cannot read it.
`worktreeRemoved`	bool	Whether its checkout has been taken away, which leaves the record and the transcript.
`sequenceInProgress`	bool	Whether a merge, a rebase or a cherry-pick is part-way through its checkout, waiting on somebody to settle it.
`failedRun`	bool	Whether a script komrad fired for the agent failed and nobody has looked at it since.
`failedRunLog`	int32	The run log that failure was written to, which is the run the panel opens on.
`stateChangedAt`	string	When the state above last moved, in RFC 3339.
`reportedReason`	string	What the agent's own CLI last reported it was doing, which annotates the state the pane decided rather than replacing it.
`role`	AgentRole	What the agent was launched to do, which decides the half of the review briefing it is sent.
`promptTruncated`	bool	Whether prompt holds only its opening, which a summary listing returns so that a page of agents does not carry every briefing they were launched with.
`treeStanding`	ReviewTreeStanding	Where the agent's worktree stood when last measured against the round tree_standing_sha names.
`treeStandingSha`	string	The snapshot of the round tree_standing was measured against, empty before any measurement.
`movedSinceRound`	string	The snapshot of its newest round while its worktree no longer hashes to it, empty otherwise.
`heldAt`	string	When a person stopped this agent and took its worktree, empty while nobody is holding it.

AgentMetadata#

Field	Type	Description
`key`	string	What the fact is filed under, such as pr or branch.
`value`	string	The fact as the panel shows it, which is why a URL belongs here whole.

AgentState#

AgentState is what the panel last decided an agent was doing, read off the tail of its pane.

Value	Description
`AGENT_STATE_IDLE`	The pane is at rest with nothing typed.
`AGENT_STATE_THINKING`	The CLI is working on a turn.
`AGENT_STATE_WAITING`	The CLI is blocked on a human answering a selection.
`AGENT_STATE_SETTING_UP`	The agent is being launched and has no pane to read yet.
`AGENT_STATE_FAILED_TO_CREATE`	The launch failed, which retry_agent is for.
`AGENT_STATE_FAILED_TO_CLEANUP`	A delete failed to take the worktree down, and the reason is on the row.
`AGENT_STATE_UNCERTAIN`	The pane could be read but its tail decided nothing.

AgentRole#

AgentRole is what an agent was launched to do.

Value	Description
`AGENT_ROLE_IMPLEMENTER`	An agent that lands work on a branch of its own.
`AGENT_ROLE_REVIEWER`	A child that reads another agent's work and gives a review.
`AGENT_ROLE_ORCHESTRATOR`	The agent drawn on a workflow's own row that hands work out.

ReviewTreeStanding#

ReviewTreeStanding is where an agent's worktree stands against the round its last verdict was given on.

Value	Description
`REVIEW_TREE_STANDING_MOVED`	The worktree differs from the round and the base does not hold the round.
`REVIEW_TREE_STANDING_LANDED`	The base holds the round whole and the worktree carries nothing beyond the base.
`REVIEW_TREE_STANDING_LANDED_MOVED`	The base holds the round whole and the worktree carries new work on top of the base.