Architecture

The Atlassian A2A Gateway is a cloud-hosted service that implements the A2A (Agent2Agent) protocol specification. It acts as a bridge between external AI agents and Atlassian Rovo, which in turn accesses Atlassian Cloud product APIs.

Request flow

When an external agent sends a request, the request flows through several layers:

1
2
External Agent
  → Agent Card discovery (/.well-known/agent.json)
    → OAuth 2.0 authentication
      → Admin enablement check
        → JSON-RPC dispatcher
          → JSON-RPC method handler
            → Rovo Agent Adapter
              → Rovo backend
                → Atlassian Cloud APIs (Jira, Confluence, etc.)

Each layer handles a specific concern:

1. Agent Card discovery - The external agent fetches /.well-known/agent.json to learn about Rovo's identity, advertised skills, and authentication requirements. This endpoint is public.
2. OAuth 2.0 authentication - The agent completes the OAuth 2.0 authorization code flow using the security information advertised by the Agent Card. A2A does not support API tokens or session cookies.
3. Admin enablement - The gateway checks an organization-level A2A setting before executing requests. When A2A is not enabled for the organization, the gateway returns 403 with an A2A-specific error.
4. JSON-RPC dispatcher - Validates the JSON-RPC 2.0 request structure and routes to the appropriate method handler.
5. Transport selection - Synchronous methods use a JSON response. message/stream and tasks/resubscribe use SSE and are piped without buffering.
6. Downstream proxy - The gateway forwards the JSON-RPC envelope to the downstream Rovo service with service and user context.
7. Rovo backend - The downstream Rovo service handles protocol execution, task state, artifacts, and Atlassian product tool calls.

Agent Card

The Agent Card at https://a2a.atlassian.com/.well-known/agent.json is the gateway's public discovery document. Agents fetch it before authentication to learn where to send requests, which OAuth scopes are required, and which high-level skills Rovo advertises.

Key fields

The static fallback card advertises text/plain input and output modes and the two skills documented in Agent skills. The downstream card may advertise different values. Inspect the live Agent Card for capabilities in the target environment.

Components

Agent Card Provider

The Agent Card is the entry point for A2A discovery. The gateway uses a cache → fetch → fallback strategy:

1. Check the cache — If a cached card exists, hydrate with local auth config and return.
2. Cache miss — Fetch the card from the downstream Rovo service.
3. On success — Store in the cache (5-minute TTL), hydrate with local auth config, and return.
4. On failure — Fall back to a static, hardcoded Agent Card.

Hydration happens at serve-time (not cache-time), so changes to OAuth configuration take effect immediately without waiting for cache expiry.

The gateway always replaces these fields on the downstream card with locally managed values: url, version, protocolVersion, documentationUrl, iconUrl, securitySchemes, security, additionalInterfaces, and preferredTransport. It also forces capabilities.pushNotifications and capabilities.stateTransitionHistory to false, and always includes its own capabilities.extensions entries alongside any the downstream supplies.

Two fields are adjusted rather than replaced. provider is taken from the downstream card when present and back-filled with Atlassian details otherwise. Skill inputModes and outputModes are normalized to media types, so a legacy "text" value is served as text/plain.

The remaining fields come from the downstream card when available: name, description, capabilities.streaming, defaultInputModes, defaultOutputModes, and skills.

JSON-RPC Dispatcher

The dispatcher validates inbound requests against the JSON-RPC 2.0 specification:

• Checks for required fields (jsonrpc, id, method)
• Validates jsonrpc is "2.0" and id is a string or number
• Routes recognized methods to their handlers
• Rejects batch-style array payloads
• Returns -32601 Method not found for unknown methods

Downstream proxy

The gateway keeps the JSON-RPC envelope intact and forwards it to the downstream Rovo service:

• Synchronous methods return the downstream JSON-RPC envelope unchanged.
• Streaming methods pipe the downstream text/event-stream body directly to the client without buffering.
• The gateway adds service authentication and forwards validated user context.
• The downstream Rovo service validates A2A message models, starts or resumes the Rovo workflow, manages task state, and produces artifacts and status events.
• The gateway does not synthesize task IDs or translate A2A messages into a separate chat schema.

Endpoints

Production URLs

Supported JSON-RPC methods

Task handling

The gateway does not own task state. It forwards downstream Message, Task, artifact, status, and error envelopes unchanged. message/send returns a single response after Rovo finishes the task. Requests that run longer than roughly 30 seconds can be terminated at the network edge with an HTTP 500 before Rovo finishes. That limit is enforced by the CDN rather than by the gateway, so treat the number as approximate. Use message/stream for any request that may run longer, including multi-step work.

DNS and routing

A2A is served from a2a.atlassian.com, which is a separate host from the Rovo MCP server at mcp.atlassian.com. The two do not share a request path, so an A2A client should never send JSON-RPC requests to mcp.atlassian.com.

Next steps

• Authentication — OAuth 2.0, PKCE, and DCR.
• Getting started — Connect an external agent and send your first request.
• Agent skills — Review the skills Rovo advertises to external agents.
• Agent Card schema — Full field-by-field reference for the Agent Card.
• Admin controls — Understand the organization-level enablement check on requests.
• Debugging — Run quick endpoint and request verification checks.
• Troubleshooting — Debug common A2A integration failures.