Version Compatibility

​

Method Mapping

​

Key Wire-Format Differences

​

Agent Card

​

Message and Task Objects

​

Pagination

​

Push Notification Config Params

​

SendMessage Result Shape

​

Role and State Values

• Roles serialize as user, agent, and unspecified
• Task states serialize as submitted, working, completed, failed, and other lowercase protocol values

​

Example Migration

​

V0 request

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "message/send",
  "params": {
    "message": {
      "kind": "message",
      "messageId": "msg-1",
      "role": "user",
      "parts": [
        {
          "kind": "data",
          "data": {
            "skill": "create-user",
            "projectUserId": "user_123"
          }
        }
      ]
    }
  }
}

​

V1 request

{
  "jsonrpc": "2.0",
  "id": "req-1",
  "method": "SendMessage",
  "params": {
    "message": {
      "messageId": "msg-1",
      "role": "user",
      "parts": [
        {
          "data": {
            "skill": "create-user",
            "projectUserId": "user_123"
          }
        }
      ]
    }
  }
}

​

Migration Checklist

1. Start sending A2A-Version: 1.0 on every request, including the public Agent Card request.
2. Rename JSON-RPC methods from slash-style V0 names to the PascalCase V1 names.
3. Remove kind fields from message parts and stop expecting kind on messages, tasks, and stream events.
4. Update SendMessage callers to read result.task instead of reading the task directly from result.
5. Replace limit and offset with pageSize and pageToken, and update your parser for the paged ListTasks response object.
6. Update task webhook config params to the V1 taskId and id field names.

​

When to Keep V0