A2A & Agent Activity API
Shep’s web server (shep start, or shep ui) speaks A2A 1.0 over JSON-RPC. Another orchestrator can hand Shep a feature request and follow it as a task: watch it work, answer its agent’s questions, approve or reject its gates, and cancel it.
The same activity is also available as two plain HTTP endpoints, as CLI commands, as MCP tools, and in Herdr. They all give the same answer, because they read the same state.
A task is a feature. The A2A task id and context id are both the feature id.
Discover and authenticate
The agent card lives at the standard path:
curl http://localhost:4050/.well-known/agent-card.jsonIt names the endpoint (http://localhost:4050/api/a2a, binding JSONRPC, protocol version 1.0), two skills (build-feature, steer-feature), streaming support, and an HTTP bearer security scheme. Use your own port if Shep isn’t on the default 4050.
Every call to the endpoint needs your install’s token, stored in web-auth-token in the Shep home folder (~/.shep, or $SHEP_HOME):
TOKEN=$(cat ~/.shep/web-auth-token)
a2a() {
curl -s http://localhost:4050/api/a2a \
-H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
-H 'A2A-Version: 1.0' -d "$1"
}A call without the token gets HTTP 401. The agent card itself is readable without it unless you set SHEP_WEB_REQUIRE_TOKEN=1.
The server answers on loopback only. To reach it from another host, list that host in SHEP_ALLOWED_HOSTS. Clients that send the token in a header need no Origin, so server-to-server clients work as is.
In the web UI, Settings → Connect agents shows your endpoint, the token file’s path and a ready-to-copy request. It never shows the token itself.
Methods
| Method | What Shep does |
|---|---|
SendMessage without taskId | Creates a feature. The text parts are the request. The repository comes from a data part {"repositoryPath": "/abs/path"} or from metadata.repositoryPath on the message or request |
SendMessage with taskId | A data part {"decision": "approve"} or {"decision": "reject", "feedback": "…"} decides the waiting gate. Any other text answers the agent’s open question. Free text never approves anything |
SendStreamingMessage | The same, then streams the task over SSE |
GetTask | The feature as a task |
ListTasks | Every feature. Filters: contextId, status; paging with pageSize (1–100) and pageToken |
CancelTask | Stops the run. A finished task returns TaskNotCancelableError |
SubscribeToTask | SSE stream: the task, then one statusUpdate per change, ending after a terminal state |
| Push-notification methods | Not supported (-32003); use SubscribeToTask |
GetExtendedAgentCard | Not configured (-32007) |
Create a feature, check it, approve it
a2a '{"jsonrpc":"2.0","id":1,"method":"SendMessage","params":{"message":{"messageId":"m1","role":"ROLE_USER","parts":[{"text":"Add a login page"},{"data":{"repositoryPath":"/work/acme"}}]}}}'
a2a '{"jsonrpc":"2.0","id":2,"method":"GetTask","params":{"id":"<id>"}}'
a2a '{"jsonrpc":"2.0","id":3,"method":"SendMessage","params":{"message":{"messageId":"m2","role":"ROLE_USER","taskId":"<id>","parts":[{"data":{"decision":"approve"}}]}}}'A feature waiting at its merge gate reads like this (trimmed):
{
"id": "7a8252ce-8c09-413a-b1dc-e22e7a082e32",
"status": {
"state": "TASK_STATE_INPUT_REQUIRED",
"message": { "parts": [{ "text": "Waiting for approval of the merge phase. Reply with a data part {\"decision\":\"approve\"} or {\"decision\":\"reject\",\"feedback\":\"…\"}." }] }
},
"metadata": { "shep": { "activity": "blocked", "reason": "approval-gate", "phase": "merge" } }
}To reject with feedback, send {"data": {"decision": "reject", "feedback": "Keep the existing session cookie"}}. To answer a question the agent asked, send a text part instead.
Task states
| Shep activity | A2A state | Status message |
|---|---|---|
| working | TASK_STATE_WORKING | For example “Working on the plan phase.” |
| blocked at a gate | TASK_STATE_INPUT_REQUIRED | Which phase waits for approval, and the data part to send |
| blocked on a question | TASK_STATE_INPUT_REQUIRED | The agent’s question; reply with text |
| waiting | TASK_STATE_SUBMITTED | Queued, deferred, or waiting on a parent feature |
| done | TASK_STATE_COMPLETED | |
| failed | TASK_STATE_FAILED, or TASK_STATE_CANCELED for a cancelled run | The run’s error |
task.metadata.shep carries Shep’s own fields: name, repository, branch, activity, reason, phase, run status, open question, PR, the actions the run accepts, and a version that only ever increases within a stream.
Protocol notes
- Enums use their ProtoJSON names (
TASK_STATE_WORKING,ROLE_USER). A part holds exactly one oftext,data,urlorraw. - A request without an
A2A-Versionheader is served as 1.0. (The spec reads a missing header as 0.3; Shep doesn’t speak 0.3.) Any other major version returnsVersionNotSupportedError(-32009). You can also pass the version as anA2A-Versionquery parameter. - Errors:
-32700parse error,-32600invalid request,-32601unknown method,-32602invalid params (including a reply the feature can’t take right now; the message says why),-32001task not found,-32002not cancelable,-32004unsupported. - Streams are
text/event-stream: one JSON-RPC response perdata:line, plus a: keep-alivecomment every 15 seconds. - Interoperability is tested with the official
@a2a-js/sdkclient.
Agent activity over HTTP
If you don’t need A2A, two plain endpoints give the same answer. Send the same bearer token.
# Every active feature (add includeSettled=1 for finished ones)
curl -s -H "Authorization: Bearer $TOKEN" "http://localhost:4050/api/agent-activity"
# One feature, by id or id prefix
curl -s -H "Authorization: Bearer $TOKEN" "http://localhost:4050/api/agent-activity?featureId=<id>"
# Block until the feature needs someone, finishes or fails
curl -s -H "Authorization: Bearer $TOKEN" \
"http://localhost:4050/api/agent-activity/wait?featureId=<id>&until=blocked,done,failed&timeoutMs=600000"| Endpoint | Query | Responses |
|---|---|---|
GET /api/agent-activity | featureId (id or prefix), repositoryPath, includeSettled=1 | 200; 404 when featureId matches nothing |
GET /api/agent-activity/wait | featureId (required), until (comma-separated states; default blocked,done,failed), timeoutMs (at most 600000, the default) | 200 when the state is reached, the wait times out, or the request is closed; 404 unknown feature; 409 ambiguous prefix; 400 bad parameters |
Each activity has a state (working, blocked, waiting, done, failed), a reason such as approval-gate, agent-question or queued-for-capacity, any open question, and a version. Within one watch the version only increases. Between two separate reads it can drop once (answering a question removes that question’s timestamp), so if you poll, compare the state as well as the version. See Agent activity for every state and reason.
The same from the terminal
shep feat status <id> # what it's doing and why
shep feat status <id> --json
shep feat wait <id> # until it needs someone, finishes or fails
shep feat wait <id> --until done --timeout 3600 # secondsshep feat wait exits 0 when the state is reached, 1 if the feature isn’t found, 2 on timeout, 3 for an ambiguous id, and 130 when interrupted, so it fits in scripts.
In the web UI
- Agent activity (
/activityin the sidebar, with a badge for blocked features) lists every feature’s state, the reason, what the agent asks, and a link to the next step. Show finished adds done features. - A feature’s Overview tab opens with an Agent status card. Notify me on that card waits for the feature and raises a toast and a browser notification when it needs you, finishes or fails.
Herdr
Herdr shows which agents in your terminal panes need attention. Run shep tui inside a Herdr pane and Shep reports its state to Herdr’s sidebar: blocked (with “needs you: N”), working or idle. When you quit the console, Shep releases the pane.
Nothing to configure: Shep detects Herdr from the variables it sets in its panes (HERDR_ENV, HERDR_PANE_ID, HERDR_BIN_PATH). Outside Herdr nothing is reported, and Herdr isn’t a dependency.
Not supported
- A2A push notifications, the extended agent card, and the gRPC and REST bindings.
- Shep acting as an A2A client to other agents.
What’s next
- MCP server — the same capabilities as MCP tools.
- Agent activity — states and reasons in detail.
- Terminal console —
shep tui, which drives the Herdr report. - Decisions & agent questions — how agents ask and how you answer.