list_agents
List the agents komrad tracks, most recently updated first.
read-onlyidempotentMCP toolAgent
Archived agents are left out unless archived is set.
Calling it#
curl -X POST http://127.0.0.1:8787/komrad.agent.v1.AgentService/ListAgents \
-H 'Content-Type: application/json' \
-d '{}'komrad rpc list-agents{
"name": "list_agents",
"arguments": {}
}Offered by the komrad MCP server to writer, reviewer, orchestrator agents.
Request#
ListAgentsRequest#
| Field | Type | Description |
|---|---|---|
pagination | Pagination | The page to read. |
archived | bool | Whether to list only archived agents instead of live ones. |
Response#
ListAgentsResponse#
| Field | Type | Description |
|---|---|---|
agents | AgentRow[] | The agents, most recently updated first. |
next_page_token | string | The cursor for the next page. Unset on the last page. |
Types#
Pagination#
Pagination selects one page of a listing.
AgentRow#
AgentRow is an agent with its mail, pull requests and review state.
| Field | Type | Description |
|---|---|---|
agent | Agent | The agent. |
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. |
forge_comments | CommentCounts | The comments copied from the forge onto the agent's work. Unset while there are none. |
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.
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. |
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.
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. |
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. |