get_agent
Get one agent by id, archived or not, with its prompt in full.
read-onlyidempotentMCP toolAgent
Calling it#
curl -X POST http://127.0.0.1:8787/komrad.agent.v1.AgentService/GetAgent \
-H 'Content-Type: application/json' \
-d '{
"id": "<id>"
}'komrad rpc get-agent \
--id '<uuid>'{
"name": "get_agent",
"arguments": {
"id": "<id>"
}
}Offered by the komrad MCP server to writer, reviewer, orchestrator agents.
Request#
GetAgentRequest#
| Field | Type | Description |
|---|---|---|
id | uuid* | The agent to get, by id. Archived agents are included. |
Response#
GetAgentResponse#
| Field | Type | Description |
|---|---|---|
agent | Agent | The agent, with the prompt in full. |
unread_mail | bool | Whether mail is waiting that the agent has not read. |
pull_request | PullRequestStanding | The state of the current pull request from the agent's branch. |
pull_requests | PullRequest[] | Every pull request from the agent's branch, the current one first. |
local_review_snapshots | int32 | How many review snapshots the agent's work has. |
reviewer_comments | CommentCounts | The comments reviewers have left on the agent's work. Unset while there are none. |
person_comments | CommentCounts | The comments the person has left on the agent's work. Unset while there are none. |
task | Task | The agent's task. Unset for an agent on no task. |
forge_comments | CommentCounts | The comments copied from the forge onto the agent's work. Unset while there are none. |
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. |
PullRequestStanding#
PullRequestStanding is the current pull request from an agent's branch.
| Field | Type | Description |
|---|---|---|
state | PullRequestState | The state of the current pull request. |
number | int32 | The current pull request's number. Unset for |
url | string | The current pull request's web address. Unset for |
title | string | The current pull request's title. Unset for |
merge_readiness | MergeReadiness | Whether the forge would merge the current pull request. Unspecified for |
head_sha | string | The commit at the head of the current pull request on the forge. Unset for |
forge | Kind | The kind of forge the current pull request is on. Unspecified for |
PullRequest#
PullRequest is a pull request as komrad last read it from the forge.
| Field | Type | Description |
|---|---|---|
id | uuid* | The pull request's id. |
forge | Kind | The kind of forge the pull request is on. |
provider_id | string | The forge's own stable id for the pull request, such as GitHub's |
url | string | The pull request's web address. |
repository_url | string | The web address of the repository the pull request merges into. |
head_repository_url | string | The web address of the repository the pull request's branch is in. Empty when the forge no longer has that repository. |
number | int32 | The pull request's number, unique within its repository. |
title | string | The pull request's title. |
head_branch | string | The branch the pull request merges from. |
head_sha | string | The commit at the tip of the pull request's branch. |
base_branch | string | The branch the pull request merges into. |
base_sha | string | The commit at the tip of the branch the pull request merges into. |
draft | bool | Whether the pull request is a draft. |
state | PullRequestState | The pull request's state. |
opened_at | timestamp | When the pull request was opened. |
changed_at | timestamp | When the pull request last changed on the forge. |
merged_at | timestamp | When the pull request merged. Unset until the pull request merges. |
closed_at | timestamp | When the pull request closed, merged or not. Unset while the pull request is open. |
merge_readiness | MergeReadiness | How close the forge is to merging the pull request. |
author | string | The login of the pull request's author. Empty when the forge no longer has the account. |
body | string | The pull request's description. Empty when it has none. |
CommentCounts#
CommentCounts counts the comments on an agent's work.
Task#
Task is one piece of work that agents do.
| Field | Type | Description |
|---|---|---|
id | uuid* | The task's id. |
workflow_id | uuid* | The id of the workflow the task belongs to. |
slug | string | The task's slug, such as |
title | string | The task's title. |
goal | string | What the task is meant to achieve, in markdown. |
created_at | timestamp | When the task was created. |
updated_at | timestamp | When the task last changed. |
archived_at | timestamp | When the task was archived. Unset while the task is live. |
cwd | string | The directory of the task's checkout. Unset while the task has no checkout. |
branch | string | The git branch of the task's checkout. Unset when the task has no checkout or git cannot read the branch. |
repository_url | string | The canonical web address of the repository the task's checkout pushes to, such as |
head_sha | string | The commit checked out in the task's checkout. Unset when the checkout is gone or git cannot read it. |
worktree_removal_reason | WorktreeRemovalReason | Why the task's worktree is no longer on disk. Unspecified while it is. |
sequence | Sequence | The git operation stopped part way in the task's checkout. |
moved_since_snapshot | string | The commit of the task's newest snapshot, set while the checkout has changed since that snapshot. Empty otherwise. |
diff_stat | DiffStat | How many lines the task's checkout adds and removes since it left the base branch. Unset when there is no base branch to measure against. |
adopted_branch | string | The existing branch the task was put on. Unset when komrad created the branch. |
failure_reason | string | Why the task's last delete failed to remove its checkout. Empty unless a delete failed. |
notes | string | The task's notes, in markdown, written by its agents and the person. |
notes_updated_at | timestamp | When the task's notes were last written, or when the task was created if they never were. |
parent | Parent | The task this task depends on. Unset for a task on the workflow's base branch. |
snapshots | int32 | How many snapshots komrad has taken of the task's checkout. |
guides | int32 | How many guides agents have written for the task. |
MergeReadiness#
MergeReadiness is how close a pull request's head commit is to merging.
| Field | Type | Description |
|---|---|---|
decision | ReviewDecision | The forge's review decision. |
checks | Checks | The state of the checks on the head commit. Unspecified when the forge last reported on an older head. |
mergeability | Mergeability | The forge's mergeability, or the last value for the same head while the forge recomputes it. |
mergeability_unconfirmed | bool | Whether |
auto_merge | bool | Whether auto-merge is on, so the forge merges once the checks and reviews pass. |
auto_mergeable | bool | Whether the forge would let komrad turn auto-merge on now. The forge refuses for a draft, a pull request with nothing left to wait for, and a repository that does not allow auto-merge. |
credential_approved | bool | Whether komrad's credential has an approval standing on the pull request. |
credential_can_approve | bool | Whether the forge would take an approval from komrad's credential now. The forge refuses one from the pull request's author and from a user it does not let approve. |
reviewers | Reviewer[] | The users who have reviewed the pull request or have a review request waiting, without its author. Empty before the forge has been read. |
DiffStat#
DiffStat counts the lines a checkout adds and removes, committed or not.
Parent#
Parent is the task a child depends on, and the fork point where the child's own commits begin on the parent's branch. Snapshots and line counts measure from fork_point.
| Field | Type | Description |
|---|---|---|
task_id | uuid* | The id of the parent task. |
fork_point | string | The commit of the parent's branch the child's own commits sit on. |
pull_request_id | uuid | The id of the parent's pull request, which komrad reads for the parent's newest commit and its merge. Empty until the parent has one. |
blocked | CascadeBlock | Why the cascade cannot rebase the child onto its parent. |
Reviewer#
Reviewer is one user who has reviewed a pull request or been asked to.
| Field | Type | Description |
|---|---|---|
login | string | The reviewer's login on the forge. |
verdict | ReviewerVerdict | Where the reviewer's latest review leaves them. |
requested | bool | Whether a review request to the reviewer 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. |
PullRequestState#
PullRequestState is the state of a pull request, worked out from the forge's report. A finished state wins over an open one.
| Value | Description |
|---|---|
unread | Komrad has not read the repository yet. |
none | Komrad read the repository and found no pull request from the branch. |
open | Open, without a review decision that decides it. |
approved | Open, and the forge would merge it now. |
changes_requested | Open, with a reviewer asking for changes. |
draft | A draft, whatever its reviews say. |
merged | Merged. |
closed | Closed without merging. |
failing | Open, with a failing check on the head commit, whatever its reviews say. |
approved_waiting | Approved, but behind its base branch or blocked by a branch rule. |
conflicting | Open, and in conflict with its base branch, whatever its reviews say. |
checks_running | Open, with checks running on the head commit and no reviewer asking for changes. |
rereview_requested | Open, and every reviewer who asked for changes has been asked to review again. |
Kind#
Kind is the kind of forge a host runs.
WorktreeRemovalReason#
WorktreeRemovalReason is why a task's worktree is no longer on disk.
Sequence#
Sequence is a git operation stopped part way in a task's checkout.
| Value | Description |
|---|---|
none | No git operation is stopped part way. |
rebase | A rebase stopped on a commit it could not replay. |
am | A |
merge | A merge stopped on conflicts. |
cherry_pick | A cherry-pick stopped on conflicts or paused between commits. |
revert | A revert stopped on conflicts or paused between commits. |
ReviewDecision#
ReviewDecision is the forge's decision on a pull request's reviews.
| Value | Description |
|---|---|
none | The forge reports no decision. |
pending | A required review has not been given. |
approved | The forge counts the pull request as approved. |
changes_requested | A reviewer is asking for changes. |
rereview_requested | Every reviewer who asked for changes has been asked to review again. |
Checks#
Checks is the overall state of the checks on a pull request's head commit.
| Value | Description |
|---|---|
none | The head commit has no checks. |
pending | Checks are still running. |
passing | Every check passed. |
failing | At least one check failed, and every check has finished. |
failing_running | At least one check failed, and others are still running. |
Mergeability#
Mergeability is whether the forge would merge a pull request, given its base branch and branch rules.
| Value | Description |
|---|---|
unknown | The forge has not worked it out yet. |
clean | The forge would merge the pull request now. |
unstable | Some checks are not passing. |
blocked | A branch rule is not met, such as a required review. |
behind | The base branch has commits the pull request's branch does not. |
conflicting | The branch is in conflict with its base branch. |
CascadeBlock#
CascadeBlock is why the cascade cannot rebase a child onto its parent.
| Value | Description |
|---|---|
conflicted | Rebasing the child's own commits onto its parent stopped on conflicts. |
orphaned | The child is orphaned: its branch holds neither its fork point nor any of its parent's own commits. |
parent_closed | The parent's pull request closed without merging. |
ReviewerVerdict#
ReviewerVerdict is where one reviewer's latest review of a pull request leaves them.
| Value | Description |
|---|---|
none | The reviewer has not reviewed the pull request. |
approved | The reviewer approved. |
changes_requested | The reviewer asked for changes. |
commented | The reviewer left comments without approving or asking for changes. |
dismissed | The reviewer's latest review was dismissed. |