Getting started

This guide walks you through connecting an external AI agent to Atlassian Rovo using the A2A (Agent2Agent) protocol. By the end, you'll be able to send a message/stream request to Rovo from an A2A-compatible agent.

Prerequisites

Before you begin, ensure you have:

• An Atlassian Cloud site with Jira and/or Confluence.
• Rovo enabled on your Atlassian site.
• A2A enabled for your organization (see Admin controls).
• An external agent that supports A2A protocol version 0.3.0, Dynamic Client Registration, and the OAuth 2.0 authorization code flow with PKCE.
• A modern web browser to complete the OAuth 2.0 consent flow.

A2A endpoints

All A2A communication happens through two endpoints:

Step 1: Discover the Agent Card

The Agent Card is a public JSON document that describes Rovo's capabilities, skills, and authentication requirements. Any agent can fetch it without authentication:

1
2
curl -s https://a2a.atlassian.com/.well-known/agent.json | jq .

The response includes:

• name and description — Rovo's identity.
• url — The JSON-RPC endpoint to send task requests to.
• skills — The capabilities Rovo advertises (search Jira, create Confluence pages, etc.).
• securitySchemes — The OAuth 2.0 configuration for authentication.
• capabilities — What protocol features Rovo supports (streaming, push notifications, etc.).

See Architecture for the key Agent Card fields and how the gateway serves the card.

Step 2: Authenticate via OAuth 2.0

A2A uses the OAuth 2.0 authorization code flow with PKCE (S256). Dynamic Client Registration is required, because the full_access:chat:rovo scope cannot be added to an app created in the Atlassian Developer Console.

1. Let your agent register with Atlassian through Dynamic Client Registration.
2. Redirect the user to the authorizationUrl from the Agent Card to obtain an authorization code. The request must include code_challenge and code_challenge_method=S256.
3. Exchange the code for an access token at the tokenUrl from the Agent Card, sending the matching code_verifier.
4. Include the token in the Authorization: Bearer <token> header when calling the JSON-RPC endpoint.

The required OAuth scopes are:

For a detailed walkthrough of DCR, PKCE, and organization enablement, see Authentication.

Step 3: Send your first message

Use message/stream for the first end-to-end request. It sends SSE events while Rovo processes the request, avoiding the roughly 30-second limit that applies to synchronous responses:

1
2
REQUEST_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')
MESSAGE_ID=$(uuidgen | tr '[:upper:]' '[:lower:]')

curl -sS -N --max-time 240 \
  -X POST https://a2a.atlassian.com/v1/rovo \
  -H "Content-Type: application/json" \
  -H "Accept: text/event-stream" \
  -H "Authorization: Bearer <your_access_token>" \
  --data "{
    \"jsonrpc\": \"2.0\",
    \"id\": \"$REQUEST_ID\",
    \"method\": \"message/stream\",
    \"params\": {
      \"message\": {
        \"kind\": \"message\",
        \"messageId\": \"$MESSAGE_ID\",
        \"role\": \"user\",
        \"parts\": [
          { \"kind\": \"text\", \"text\": \"Show me all open bugs assigned to me in Jira\" }
        ]
      }
    }
  }"

The endpoint returns SSE comments and JSON-RPC events during processing. A successful stream ends with a status update whose state is completed. See End-to-end testing for validation criteria and timeout details.

Step 4: Explore Rovo's skills

Ask Rovo about different Atlassian tasks. The Agent Card's skills array lists what Rovo can do. The card advertises two skills, each covering both reading and writing:

• Work in Jira (work-in-jira) - Get Jira context like project status, work item details, or sprint data. You can also create, edit, delete, and update work items.
• Work in Confluence (work-in-confluence) - Find answers from Confluence and create pages. You can also edit, delete, and update existing pages.

Each skill carries its own examples array of sample prompts. Read them from the live card rather than relying on a copy here.

See Agent skills for the full list and Agent Card schema for the complete field reference.

Next steps

• Architecture — Understand the full request flow and components.
• Authentication — Deep dive into OAuth 2.0 and DCR.
• Admin controls — Confirm the organization-level setup required before testing.
• Agent skills — Full reference of Rovo's advertised skills.
• Troubleshooting — Common issues and solutions.