Cancel Agent Task

Runtime contract

The generated OpenAPI operation omits the JSON request body. Send the body shown here; an empty body is not a valid request. The generated response example also does not fully reflect the current A2A envelope.

Start the example A2A server and set the same OS_SECURITY_KEY in the client terminal. These examples target reference-agent on port 7777. On deployments using scoped bearer authorization, this operation requires agents:run (or a matching broader grant). The authenticated principal determines user identity; X-User-ID is only anonymous attribution and cannot override it.

First send a message and retain result.id and result.contextId. Substitute those real values for params.id and params.contextId below. For cancellation, scoped callers must provide the original session ID and own its persisted run; include it for unscoped calls too. RemoteAgent targets do not support this operation.

Request

curl -X POST "http://localhost:7777/a2a/agents/reference-agent/v1/tasks:cancel" \
  -H "Authorization: Bearer $OS_SECURITY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "jsonrpc": "2.0",
  "id": "request-1",
  "method": "tasks/cancel",
  "params": {
    "id": "returned-run-id",
    "contextId": "agent-session"
  }
}'

Response

The response result is the Task itself: use result.id for the Agno run ID, result.contextId for its session, and result.status.state for status. There is no result.task wrapper. JSON field names use camelCase. A representative envelope is:

{
  "jsonrpc": "2.0",
  "id": "request-1",
  "result": {
    "id": "returned-run-id",
    "contextId": "agent-session",
    "kind": "task",
    "status": {
      "state": "canceled"
    }
  }
}

The returned canceled status acknowledges cancellation intent. It does not prove that an active worker has already stopped. Unscoped or administrative cancellation can also record intent before a run starts.

curl --request POST 'https://example.com/a2a/agents/string/v1/tasks:cancel'

null

{  "detail": [    {      "loc": [        "string"      ],      "msg": "string",      "type": "string",      "input": null,      "ctx": {}    }  ]}