The Worker can serve the Agent2Agent (A2A) protocol, version 1.0. Another agent, on any machine, can then start a coding task in a workspace and read its result. It uses the JSON-RPC binding of A2A.
The endpoint is off by default. It is one more way to run code in your workspaces. Turn it on only when an agent needs it.
Turn it on
-
Add
"a2a": trueto~/.cf-opencode/config.json:{ "a2a": true } -
Run
cf-opencode upgrade.
To turn it off, remove the key, or set it to false, and run cf-opencode upgrade again. When it is off, the A2A paths answer like any unknown path.
What the Worker serves
| Path | What it is | Auth |
|---|---|---|
/.well-known/agent-card.json |
The Agent Card | None. The spec makes the card public. |
/a2a |
The JSON-RPC endpoint | The control token, as a bearer token |
The card says what the agent does, where the endpoint is, and that it needs a bearer token. It does not name a workspace, a repository or you. The endpoint URL comes from the request, for example https://cf-opencode.example.workers.dev/a2a.
Authentication
Send the control token in the Authorization header:
Authorization: Bearer <control token>The token is in ~/.cf-opencode/control-token. A request without it, or with a wrong one, gets HTTP 401. Give the token only to an agent that you trust with all your workspaces.
Send A2A-Version: 1.0 in each request. A request without it is an A2A 0.3 request, and the Worker refuses it with VersionNotSupportedError (-32009).
Start a task
Use SendMessage. Put the workspace ID in message.metadata.workspace:
{
"jsonrpc": "2.0",
"id": 1,
"method": "SendMessage",
"params": {
"message": {
"messageId": "8f0c2d6e-1b7a-4c55-9f0e-2a0d5c3e7b11",
"role": "ROLE_USER",
"parts": [{ "text": "Add a health check route at /health with a test. Run npm test." }],
"metadata": { "workspace": "my-app", "title": "Health check" }
},
"configuration": { "returnImmediately": true }
}
}| Metadata key | Required | Meaning |
|---|---|---|
workspace |
Yes | The workspace ID. A message without it gets -32602, invalid params. |
title |
No | The session title. One line, up to 200 characters. |
model |
No | provider/model. Default: the model of the workspace. |
branch |
No | The branch to start from, as it is on origin. |
The rules:
- Send the task in text parts. Other parts get
ContentTypeNotSupportedError(-32005). - The workspace must exist. Connect it once with
cf-opencode connectfrom its git checkout. The Worker cannot make a workspace, because it does not know the repository. - A paused workspace wakes. The wake can take a minute.
- The workspace clones from the Git remote. It does not see changes that are not committed or pushed.
- The Worker adds the same closing instruction as
cf-opencode run: commit, push the branch, open a pull request, and end with aResult:line.
Without returnImmediately, SendMessage waits until the task is not working, as the spec requires. It waits 5 minutes at most, then returns the task as it is, often still working: one request is not held open for a coding task’s hours. Send "returnImmediately": true and poll with GetTask.
The result is a task:
{
"task": {
"id": "my-app:ses_4f2a…",
"contextId": "my-app",
"status": { "state": "TASK_STATE_WORKING", "timestamp": "2026-11-12T10:00:00.000Z" },
"metadata": { "workspace": "my-app", "task": { "id": "ses_4f2a…", "state": "running" } }
}
}The task ID is <workspace>:<session>. The contextId is the workspace ID. metadata.task is the cf-opencode task record, with all its fields.
Follow a task
| Method | What it does |
|---|---|
GetTask |
Returns the task. params: { "id": "<task id>" }. Wakes nothing. |
CancelTask |
Interrupts the OpenCode session. Works only while the workspace runs. |
ListTasks |
Lists the tasks of one workspace. Set contextId to the workspace ID. |
ListTasks needs contextId, because the Worker keeps no list of all workspaces. It supports status, pageSize (1 to 100), pageToken, statusTimestampAfter and includeArtifacts.
States
| cf-opencode state | A2A state | Why |
|---|---|---|
running |
TASK_STATE_WORKING |
The agent works. |
waiting |
TASK_STATE_INPUT_REQUIRED |
The agent asks a question or a permission. |
done |
TASK_STATE_COMPLETED |
The agent finished. |
failed |
TASK_STATE_FAILED |
The turn stopped with an error, or did not start. |
stopped |
TASK_STATE_CANCELED |
The session was stopped before it finished. |
| Any other value | TASK_STATE_UNSPECIFIED |
The spec defines it as “unknown or indeterminate”. It claims neither success nor failure. |
Results
- A completed task has an artifact
result. It holds the last result text of the agent, which ends with theResult:line. - When the task record has a branch, commits, a pull request or changed files, an artifact
changesholds them as one data part. - A waiting, failed or canceled task has a status message that says why.
Not supported
These answer with the error that the spec gives:
| Method | Error |
|---|---|
SendStreamingMessage, SubscribeToTask |
UnsupportedOperationError (-32004). The card says streaming: false. |
| The four push notification config methods | PushNotificationNotSupportedError (-32003). The card says pushNotifications: false. |
GetExtendedAgentCard |
UnsupportedOperationError (-32004). |
A message with taskId |
UnsupportedOperationError (-32004). Answer a waiting task in OpenCode: cf-opencode connect <workspace> --session <ses_…>. |
Limits
- The request body is 160 KiB or less. A larger one gets HTTP 413.
- One control token gives access to all workspaces. There are no scopes.
- After
CancelTask,GetTaskshows the outcome that OpenCode records for the interrupted session.