Skip to content
AIPDocs
AIP 1.055 pagesGuide
Release status
DocumentationAIP 1.0GuideBuild with AIP

Use AIP through A2A

AIP exposes an A2A 1.0 compatibility edge backed by the same native gateway, policy engine, durable action store, and handlers used by native AIP and MCP. Use this path when an external agent already speaks A2A and should participate without becoming responsible for AIP lifecycle semantics.

What the Profile Provides

The A2A profile projects AIP capabilities as Agent Card skills and maps A2A tasks to native AIP actions. It supports:

  • Agent Card discovery;
  • message send and streaming send;
  • task read, list, cancellation, and subscription;
  • task push-notification configuration create, read, list, and delete;
  • authenticated extended Agent Card retrieval;
  • legacy v0.3 method names as inbound aliases.

Current A2A names are advertised. Legacy aliases are accepted for migration but must not be used to infer a second task model.

Discover the Agent Card

The preferred discovery endpoint is:

curl --fail-with-body http://127.0.0.1:18080/.well-known/agent-card.json

Compatibility aliases are /.well-known/agent.json and /a2a/agent-card. The card declares the JSON-RPC interface URL, available skills, supported content modes, security schemes, and whether push notifications are enabled.

Treat the card as discovery data, not authorization. A skill visible in a card can still require AIP scopes, approval, idempotency, or transaction policy.

Send a Message

The preferred JSON-RPC endpoint is /a2a/v1. Send A2A-Version: 1.0 when the client supports version headers.

curl --fail-with-body \
  -H 'Authorization: Bearer local-development-token' \
  -H 'A2A-Version: 1.0' \
  -H 'Content-Type: application/json' \
  --data @a2a-request.json \
  http://127.0.0.1:18080/a2a/v1

a2a-request.json selects one native capability explicitly:

{
  "jsonrpc": "2.0",
  "id": "request-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "message-1",
      "contextId": "support-case-42",
      "role": "ROLE_USER",
      "parts": [
        {
          "text": "Check service health"
        }
      ]
    },
    "metadata": {
      "aip": {
        "capability_id": "cap:aipd:health",
        "input": {}
      }
    }
  }
}

metadata.aip.capability_id is required because a human-readable skill name is not a stable routing authority. When metadata.aip.input is absent, the profile derives native input from the message parts. The A2A message id becomes the native idempotency basis.

Set configuration.returnImmediately to true to request asynchronous native execution. The returned task id remains the stable handle for later reads and cancellation.

Follow and Manage Tasks

Operation Purpose
SendStreamingMessage Start work and receive ordered task updates over SSE
GetTask Read one task projected from the durable action record
ListTasks List tasks visible to the authenticated principal and tenant
CancelTask Persist cancellation intent and ask the handler to stop
SubscribeToTask Resume task updates from retained native events
CreateTaskPushNotificationConfig Create encrypted callback configuration for one task
GetTaskPushNotificationConfig Read one authorized task callback configuration
ListTaskPushNotificationConfigs List callback configurations visible to the caller
DeleteTaskPushNotificationConfig Delete one callback configuration and stop future delivery
GetExtendedAgentCard Retrieve the authenticated extended card

Streaming and subscription state is derived from native action events and chunks. A disconnected client must reconnect with the task identity and cursor supported by its operation; it must not assume that an open socket is the durable source of truth.

Configure Push Notifications Safely

Push delivery is advertised only when aipd has both a callback signing key and an encryption key for stored A2A credentials. Production configuration also needs an exact callback-host allowlist:

AIPD_CALLBACK_SIGNING_SEED_HEX="$AIP_CALLBACK_SIGNING_SEED_HEX" \
AIPD_A2A_PUSH_ENCRYPTION_KEY_HEX="$AIP_A2A_PUSH_KEY_HEX" \
cargo run -p aipd -- \
  --bind 127.0.0.1:18080 \
  --service-id agent:aipd:a2a \
  --native-bearer-token-file /run/secrets/aip-native-token \
  --callback-allowed-host callbacks.example.com \
  --storage-dir /var/lib/aip

AIP encrypts callback credentials at rest, signs delivery payloads, persists delivery state, and applies retry fencing. Private-network and plaintext HTTP targets remain disabled unless the deployment explicitly weakens those controls for an owned isolated network.

The current daemon accepts these two key values through environment variables or inline hexadecimal CLI options; inject them from a secret manager and avoid placing them in shell history or checked-in environment files.

Authentication and Authority

A2A JSON-RPC operations require the native bearer identity configured by aipd. The authenticated principal, not JSON-RPC metadata, determines tenant, scope, approval authority, and action visibility. Public Agent Card discovery does not grant task access.

At an internet boundary, terminate TLS at a trusted edge and replace static development credentials with deployment identity policy. Do not forward a user-supplied principal as authenticated context.

Deployment Boundary

A2A is a compatibility profile, not a second scheduler. Native AIP owns:

  • action and task durability;
  • authorization and approval;
  • idempotency and transaction state;
  • event ordering and receipts;
  • cancellation and recovery.

An A2A client therefore observes the same outcome as a native or MCP client calling the same capability.

Next Steps