LogoA2A Docs

Push Notifications

Implementing remote agent to client updates in A2A.

Remote Agent to Client Updates

Some tasks can take more than seconds. They can take minutes, hours, or even days ("ship a sample to my client in Florida and notify me when it arrives"). A2A agents need to communicate over long periods of time, both while connected and disconnected.

Clients can check whether an agent supports streaming and pushNotifications capability in the agent card:

{
  "name": "your-agent-name",
  "description": "your-agent-description",
  // ... other fields
  "capabilities": {
    "streaming": true,
    "pushNotifications": false,
    "stateTransitionHistory": false
  }
  // ... other fields
}

Update Methods

The agent can use these methods to get updates about task execution:

  1. Persistent Connection: Clients can establish a persistent connection with the agent using HTTP + Server-sent events. The agent can then send task updates using those connections per client.

  2. Push Notifications: Agents can send the latest full Task object payload to client-specified push notification URL. This is similar to webhooks on some platforms.

Connected State

While connected, Agents update each other with Task (and related) messages. Clients and Remote Agents can work on multiple tasks concurrently over the same connection.

Clients use Task/Send to update a current task with more information or reply to an agent need. Remote Agents reply with Task Updates while streaming or Task while not streaming. While not streaming, it is acceptable to poll at reasonable intervals.

If the agents become disconnected, they can resume the connection and receive live updates via the Task/Resubscribe method.

Disconnected State

For disconnected scenarios, A2A supports a push notification mechanism whereby an Agent can notify a Client of an update outside of a connected session via a PushNotificationConfig. Within and across enterprises, it is critical that the agent verifies the identity of the notification service, authenticates itself with the service, and presents an identifier that ties the notification to the executing task.

The NotificationService should be considered a separate service from the client agent, and it is not guaranteed or even expected to be the client directly. This NotificationService is responsible for authenticating and authorizing the agent and for proxying the verified notification to the appropriate endpoint.

Setting Task Notifications

Clients need to set task push notification config to asynchronously receive task updates. They should generate a taskId and set the push notification configuration for the same using tasks/pushNotification/set RPC or directly in the pushNotification param of tasks/send or tasks/sendSubscribe.

interface PushNotificationConfig {
  url: string;
  token?: string; // token unique to this task/session
  authentication?: {
    schemes: string[];
    credentials?: string;
  }
}
 
// Request to send to a task (with push notification configuration)
{
  "jsonrpc": "2.0",
  "id": 1,
  "method":"tasks/send",
  "params": {
    "id": "de38c76d-d54c-436c-8b9f-4c2703648d64",    
    "message": {
      "role":"user",
      "parts": [{
        "type":"text",
        "text": "tell me a joke"
      }]   
    },
    "pushNotification": {
      "url": "https://example.com/callback",
      "authentication": {
        "schemes": ["bearer"]
      }
    },
    "metadata": {}
  }
}

Security Considerations

Agent Security

Agents should not blindly trust the push notification URL specified by the client. Some commonly used practices are:

  1. URL Verification: They should verify the push notification URL by issuing a GET challenge request.
    • The challenge request can include a validationToken as a URL query param or header
    • The notification service should respond by returning the same validationToken
    • This helps avoid tricking remote agent into DDOS-ing a URL by a malicious client
GET https://abc.com/callback-path?validationToken=randomString
Content-Length: 0
 
HTTP/1.1 200 OK
Content-Type: text/plain
 
randomString
  1. Service Identity Verification: To further verify the identity of the notification service, it can be asked to sign the validationToken using a pre-determined secret.

Notification Receiver Security

Notification Receivers should check the authenticity of the notifications they are receiving. Options include:

Asymmetric Keys

A pair of private and public keys can be generated using ECDSA, RSA, etc. Benefits include:

  • Only the agent knows the private key, reducing chances of key leakage
  • Agents can sign request payload using the private key
  • JWT protocol can be used to standardize fields like keyId and request timestamp

Symmetric Keys

Both notification server and agents use the same shared key to sign and verify.

OAuth

Agent gets an auth token from OAuth server and supplies that in the push notification request.

Bearer Token

Either party can generate the bearer token, though this has a higher chance of being leaked.

Other Security Considerations

  1. Replay Prevention: Use timestamps in JWT or other headers to prevent replay attacks. Ideally, events older than 5 minutes should be rejected.

  2. Key Rotation: Agents should implement key rotation with zero downtime, using mechanisms like JWKS that allow agents to publish both old and new public keys.

Implementation Example

The A2A repository includes implementation examples for push notifications:

Table of Contents