Integrating with the DevOps Agent A2A server

With the AWS DevOps Agent Agent-to-Agent (A2A) server, your autonomous agent can delegate operational work to the DevOps Agent over the A2A v1.0 protocol. Your agent discovers the DevOps Agent through an agent card, then sends messages to investigate incidents, review architecture, analyze costs, and map topology. The server implements the A2A v1.0 specification with the HTTP+JSON binding.

This page describes the DevOps Agent's own A2A server. To connect the DevOps Agent as a client to a remote A2A agent that you host, see Connecting Remote A2A Agents instead.

Endpoint

The A2A server is available at a regional URL. Replace {region} with your Agent Space's Region, for example us-east-1.

https://connect.aidevops.{region}.api.aws

Operation	Method and path
Agent card discovery	GET /.well-known/agent-card.json
SendMessage	POST /a2a/message:send
SendStreamingMessage	POST /a2a/message:stream
GetTask	GET /a2a/tasks/{id}
ListTasks	GET /a2a/tasks
CancelTask	POST /a2a/tasks/{id}:cancel
SubscribeToTask	POST /a2a/tasks/{id}:subscribe

For the list of available Regions, see Supported Regions.

Request headers

Pass the following headers on A2A requests.

Header	Required	Description
A2A-Version	Yes	Must be 1.0. The server rejects a request that omits this header or sends another value with HTTP 400.
Authorization	Yes	An access token (Bearer <access-token>) or an AWS Signature Version 4 (SigV4) signature. The mcp-proxy-for-aws proxy adds the SigV4 signature for you.
X-Agent-Space-Id	SigV4 only	The target Agent Space ID. See the following section on tenancy for how the server resolves the Agent Space for each authentication method.
Content-Type	Body only	application/json for a request that sends a body, such as message:send.

For token creation and SigV4 setup, see Authentication and security.

Agent card discovery

Retrieve the agent card to discover the server's interfaces, security schemes, and skills.

GET https://connect.aidevops.{region}.api.aws/.well-known/agent-card.json

The card lists two supportedInterfaces entries, one per tenant, both using the HTTP+JSON binding at the /a2a base path. It also declares the bearer and sigv4 security schemes and the investigate and chat skills, and reports streaming: true and pushNotifications: false.

Tenancy

The DevOps Agent A2A server is multi-tenant in two independent dimensions: the Agent Space a request runs against, and the interface tenant that selects between conversational chat and asynchronous investigation.

Agent Space isolation

Every A2A request runs against exactly one Agent Space, and the server uses the caller's own AWS credentials for all downstream work. Tasks, chats, and results created through one Agent Space are not visible from another.

How the server resolves the Agent Space depends on your authentication method.

• Access token (Bearer) — The token is bound to a single Agent Space when it is created. The server resolves the Agent Space from the token, so you do not send the X-Agent-Space-Id header. If you include it, the server ignores it.

• AWS SigV4 — IAM credentials are not bound to an Agent Space. You must name the target Agent Space in the X-Agent-Space-Id request header. A SigV4 request that omits this header is rejected with HTTP 400 and the message Agent space not resolved. This lets one SigV4 client route across several Agent Spaces by changing the header per request.

Interface tenant: chat and investigation

The agent card advertises two interfaces, distinguished by a tenant value. With the tenant value, you select which skill runs and which operations are available.

Tenant	Skill	Behavior	Supported operations
chat	Operational Chat	Real-time conversational analysis for cost optimization, architecture review, topology mapping, and knowledge discovery. Returns a completed result in the response.	message:send, message:stream
investigation	Incident Investigation	Deep asynchronous root cause analysis. Returns a working task immediately; the analysis takes 5–8 minutes.	message:send, then GetTask, ListTasks, CancelTask, or SubscribeToTask

Send the chosen tenant with the request. For message:send and message:stream, include it in the request body as a top-level tenant field. For GetTask and ListTasks, pass it as a tenant query parameter. For CancelTask and SubscribeToTask, pass it as a tenant field in the request body.

The tenant boundary is strict for follow-up operations. The investigation task operations (GetTask, ListTasks, CancelTask, SubscribeToTask) accept only the investigation tenant and reject a chat tenant with HTTP 400 (UNSUPPORTED_TENANT). Streaming (message:stream) accepts only the chat tenant; to stream an investigation's progress, start it with message:send and then call SubscribeToTask.

If you omit the tenant field, the server currently applies a compatibility fallback: message:send infers the tenant from keywords in your message text, and the other operations default to investigation. This fallback is temporary and exists only for migration. Always send an explicit tenant so routing stays deterministic.

Skills

• investigate — Deep asynchronous root cause analysis for AWS incidents, such as ECS 503 errors, Lambda timeout spikes, or RDS connection exhaustion. Use the investigation tenant.

• chat — Real-time conversational analysis for cost optimization, architecture review, topology mapping, and knowledge discovery. Use the chat tenant.

Send a chat message

The examples that follow use a Bearer access token for brevity. To use AWS SigV4 instead, replace the Authorization: Bearer <access-token> line with a SigV4-signed request and add the X-Agent-Space-Id header to name the target Agent Space. The request body and response are the same for both authentication methods. For setup, see Authentication and security.

A chat request returns a completed task with the answer in its artifact. Replace {region} and <access-token> with your own values.

POST https://connect.aidevops.{region}.api.aws/a2a/message:send
A2A-Version: 1.0
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "tenant": "chat",
  "message": {
    "parts": [
      { "text": "Analyze cost optimization opportunities for account 123456789012" }
    ]
  }
}

The response is an A2A task in the TASK_STATE_COMPLETED state, with the answer text in the artifact parts.

{
  "task": {
    "id": "<execution-id>",
    "contextId": "<context-id>",
    "status": {
      "state": "TASK_STATE_COMPLETED",
      "timestamp": "2026-01-01T00:00:00.000Z"
    },
    "artifacts": [
      { "artifactId": "<artifact-id>", "parts": [{ "text": "..." }] }
    ]
  }
}

To continue a conversation, send the returned task ID as taskId in the next message:send request. Chat also supports message:stream, which returns the same content as a server-sent event stream and continues a conversation the same way: send the returned task ID as taskId in the next message:stream request.

Start an investigation

An investigation request returns immediately with a working task. Poll GetTask or subscribe with SubscribeToTask for progress.

POST https://connect.aidevops.{region}.api.aws/a2a/message:send
A2A-Version: 1.0
Authorization: Bearer <access-token>
Content-Type: application/json

{
  "tenant": "investigation",
  "message": {
    "parts": [
      { "text": "Investigate why my ECS service is returning 503 errors" }
    ]
  }
}

The response is a task in the TASK_STATE_WORKING state. The artifact text carries the task ID and execution ID.

{
  "task": {
    "id": "<task-id>",
    "contextId": "<context-id>",
    "status": {
      "state": "TASK_STATE_WORKING",
      "timestamp": "2026-01-01T00:00:00.000Z"
    },
    "artifacts": [
      { "artifactId": "<artifact-id>", "parts": [{ "text": "{\"type\":\"investigation_started\",\"taskId\":\"...\"}" }] }
    ]
  }
}

Check investigation status

Use the returned task ID to poll for the latest state. Include the investigation tenant.

GET https://connect.aidevops.{region}.api.aws/a2a/tasks/{task-id}?tenant=investigation
A2A-Version: 1.0
Authorization: Bearer <access-token>

When the task reaches a terminal state, the response includes an artifacts array with the investigation result. Each terminal artifact carries an availability marker in its metadata, so a result that is still being written is reported as unavailable rather than as an error.

Subscribe to investigation updates

For a live progress stream instead of polling, subscribe to the task. The subscription streams updates as server-sent events until the task reaches a terminal state.

POST https://connect.aidevops.{region}.api.aws/a2a/tasks/{task-id}:subscribe
A2A-Version: 1.0
Authorization: Bearer <access-token>
Content-Type: application/json

{ "tenant": "investigation" }

Subscribing to a task that has already reached a terminal state returns HTTP 400 (UNSUPPORTED_OPERATION). Use GetTask for a completed task.

Task states

The server maps DevOps Agent task status to A2A v1.0 task states.

A2A task state	Meaning
TASK_STATE_SUBMITTED	The task was accepted but has not started.
TASK_STATE_WORKING	The task is in progress.
TASK_STATE_COMPLETED	The task finished successfully.
TASK_STATE_CANCELED	The task was canceled.
TASK_STATE_FAILED	The task ended without completing, for example it failed, timed out, or was skipped.

Errors

Errors use the A2A v1.0 google.rpc.Status shape. Common cases follow.

HTTP status	Reason	Cause
400	INVALID_ARGUMENT	A missing or invalid A2A-Version header, a missing message text, an unsupported tenant value, or a SigV4 request without X-Agent-Space-Id.
400	UNSUPPORTED_TENANT	The operation does not support the requested tenant, such as streaming an investigation or retrieving a chat task.
400	UNSUPPORTED_OPERATION	You subscribed to a task that is already in a terminal state.
401	UNAUTHENTICATED	The credentials are missing, invalid, or expired.
404	TASK_NOT_FOUND	No task exists for the given ID in the resolved Agent Space.
500	INTERNAL_ERROR	The task could not be executed. Retry the request.

For authentication troubleshooting, token lifecycle, and CloudTrail traceability, see Authentication and security.