Migrate remote agents in Jira from A2A 0.3 to 1.0

This guide covers the technical changes needed to update an existing Jira Remote Agent integration from A2A 0.3 to A2A 1.0.

For the full Jira integration guide, see Integrate remote agents with Jira.

Overview

Migrating to A2A 1.0 requires two significant changes:

1. Update your app manifest to opt into A2A 1.0.
2. Update your agent's A2A request, response, error, and streaming payload handling to match the A2A 1.0 protocol.

To update your app, add a new version: "1.0" property to your manifest as described in Forge manifest changes. Then update your A2A message, error, and streaming payload handling as described in the sections below.

Once you deploy your app with the updated version property, Jira will send A2A messages to your agent using the A2A 1.0 protocol. Unless you make other manifest changes, this is treated as a minor app version upgrade and rolls out immediately to all existing installations. Ensure you test thoroughly in your development environment before deploying to production.

Forge manifest changes

To opt into A2A 1.0, you must add a version: "1.0" property to the agent2Agent section of your rovo:agentConnector module.

1
2
modules:
  rovo:agentConnector:
    - key: claude-agent-connector
      name: ${APP_AGENT_NAME}
      productContexts:
        - jira
      protocols:
        agent2Agent:
          version: "1.0"
          jsonRpcTransport:
            endpoint: my-endpoint

JSON-RPC method changes

A2A 0.3 used slash-delimited JSON-RPC method names such as message/send and tasks/get.

A2A 1.0 uses PascalCase JSON-RPC method names such as SendMessage and GetTask.

For example, under A2A 0.3 a GetTask request is formatted as:

1
2
{
  "jsonrpc": "2.0",
  "id": "<requestId>",
  "method": "tasks/get",
  "params": {
    "taskId": "<taskId>"
  }
}

Under A2A 1.0, the same request is sent as:

1
2
{
  "jsonrpc": "2.0",
  "id": "<requestId>",
  "method": "GetTask",
  "params": {
    "taskId": "<taskId>"
  }
}

The JSON-RPC method name mappings are shown below.

JSON-RPC method reference

Message part structure changes

A2A 0.3 used two separate message part types for text and data identified with a kind discriminator.

A2A 1.0 removes the kind property and instead uses the presence of a text or data property to identify the part type.

Text part example

A2A 0.3:

1
2
{
  "kind": "text",
  "text": "Please summarize the latest blocker."
}

A2A 1.0:

1
2
{
  "text": "Please summarize the latest blocker."
}

Data part example

A2A 0.3:

1
2
{
  "kind": "data",
  "data": {
    "cloudId": "a436116f-02ce-4520-8fbb-7301462a1674",
    "issueId": "10001",
    "issueKey": "MCP-1305",
    "commentId": "10000"
  }
}

A2A 1.0:

1
2
{
  "data": {
    "cloudId": "a436116f-02ce-4520-8fbb-7301462a1674",
    "issueId": "10001",
    "issueKey": "MCP-1305",
    "commentId": "10000"
  }
}

Status and role enum changes

A2A 0.3 used lowercase enums for task state and role values, such as submitted, user, and agent.

A2A 1.0 uses SCREAMING_SNAKE_CASE values such as TASK_STATE_SUBMITTED, ROLE_USER, and ROLE_AGENT.

For example, under A2A 0.3 a task status might be formatted as:

1
2
{
  "status": {
    "state": "working"
  },
  "message": {
    "role": "agent",
    "parts": [
      {
        "kind": "text",
        "text": "Investigating the issue."
      }
    ]
  }
}

Under A2A 1.0, the same task status must be formatted as:

1
2
{
  "status": {
    "state": "TASK_STATE_WORKING"
  },
  "message": {
    "role": "ROLE_AGENT",
    "parts": [
      {
        "text": "Investigating the issue."
      }
    ]
  }
}

The task state and role value mappings are shown below.

Task state enum reference

Role enum reference

Error handling changes

A2A 0.3 encoded JSON-RPC errors using a flat error.data object.

A2A 1.0 uses structured error details based on google.rpc.ErrorInfo.

JSON-RPC error example

A2A 0.3:

1
2
{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32001,
    "message": "Task not found",
    "data": {
      "taskId": "123"
    }
  }
}

A2A 1.0:

1
2
{
  "jsonrpc": "2.0",
  "id": "1",
  "error": {
    "code": -32001,
    "message": "Task not found",
    "data": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "TASK_NOT_FOUND",
        "domain": "a2a-protocol.org",
        "metadata": {
          "taskId": "123"
        }
      }
    ]
  }
}

Streaming payload changes

A2A 0.3 used kind fields inside streaming events such as statusUpdate, and included a final boolean to indicate stream completion.

A2A 1.0 removes the kind and final fields and instead uses the JSON member name to identify the event type. Stream completion is indicated by closing the stream rather than by a final field.

Both A2A 0.3 and A2A 1.0 use append to indicate that the payload should be appended to the existing artifact, and lastChunk to indicate the final chunk for that artifact.

Status update event example

A2A 0.3:

1
2
{
  "statusUpdate": {
    "taskId": "task-123",
    "contextId": "ctx-456",
    "status": {
      "state": "working"
    },
    "message": {
      "role": "agent",
      "parts": [
        {
          "kind": "text",
          "text": "Analyzing the issue..."
        }
      ]
    },
    "kind": "status-update",
    "final": false
  }
}

A2A 1.0:

1
2
{
  "statusUpdate": {
    "taskId": "task-123",
    "contextId": "ctx-456",
    "status": {
      "state": "TASK_STATE_WORKING"
    },
    "message": {
      "role": "ROLE_AGENT",
      "parts": [
        {
          "text": "Analyzing the issue..."
        }
      ]
    }
  }
}

Artifact update event example

A2A 0.3:

1
2
{
  "artifactUpdate": {
    "taskId": "task-123",
    "contextId": "ctx-456",
    "artifact": {
      "artifactId": "artifact-1",
      "parts": [
        {
          "kind": "text",
          "text": "Partial response"
        }
      ]
    },
    "append": true,
    "lastChunk": false,
    "kind": "artifact-update"
  }
}

A2A 1.0:

1
2
{
  "artifactUpdate": {
    "taskId": "task-123",
    "contextId": "ctx-456",
    "artifact": {
      "artifactId": "artifact-1",
      "parts": [
        {
          "text": "Partial response"
        }
      ]
    },
    "append": true,
    "lastChunk": false
  }
}

Related resources

• Integrate remote agents with Jira
• Rovo agentConnector module reference
• A2A Protocol: What's New in v1.0