Agent-to-Agent (A2A) Protocol

GoodData exposes an Agent-to-Agent (A2A) protocol endpoint that allows external AI agents to interact with the GoodData AI Assistant. Through this endpoint, third-party agents can discover available analytics skills, send natural-language requests, and receive structured responses, including visualizations, key driver analyses, and what-if scenarios, depending on the enabled skills and permissions.

For example, an external agent can request a revenue visualization and receive both its definition and computed data to use in its own application or workflow.

Prerequisites

• Enable the A2A Protocol for your GoodData environment. Contact GoodData Support if the feature is not available.
• Configure an active LLM endpoint for the target workspace.
• Have access to the workspace and the AI agent you intend to use.
• To address a specific AI agent through A2A, ensure that AI agent switching is enabled. Contact GoodData Support if the agent-specific endpoint is not available.
• The Visualization skill is available by default. Contact GoodData Support to discuss access to other experimental skills or opting in to data sharing with LLMs.

Connecting to the A2A Server

The default Agent Card URL for a workspace is:

https://<GOODDATA_HOST>/api/v1/ai/workspaces/<WORKSPACE_ID>/a2a

To address a particular AI agent, use its agent-specific Agent Card URL:

https://<GOODDATA_HOST>/api/v1/ai/workspaces/<WORKSPACE_ID>/a2a/agents/<AGENT_ID>

The agent ID is the id returned by GET /api/v1/ai/workspaces/<WORKSPACE_ID>/agents. This endpoint lists the AI agents available to the calling user.

Point your A2A-compatible client to the appropriate Agent Card URL. The card describes the endpoint to use for A2A messages, supported input and output modes, and available skills. An agent-specific card includes that agent’s name, description, and enabled skills. The A2A endpoint supports message/send and message/stream.

If you use the default /a2a endpoint, GoodData automatically selects the most recently modified AI agent you can access. This selection can change when an agent is edited. Use an agent-specific URL when your integration must consistently address the same AI agent. An agent-specific URL returns 404 Not Found when AI agent switching is not enabled.

Each call addresses one AI agent. If your application needs to combine results from multiple agents, it must coordinate those calls itself.

Authentication

The A2A endpoint supports the following authentication methods:

• API Token
• JSON Web Token (JWT)
• OAuth 2.1, when Interactive SSO is enabled for your organization

The Agent Card declares supported methods in its securitySchemes and security properties. It always declares API-token authentication as bearerAuth. When OAuth 2.1 is enabled, the card also declares oauth2 with the GoodData authorization and token URLs. For example:

{
  "securitySchemes": {
    "oauth2": {
      "type": "oauth2",
      "flows": {
        "authorizationCode": {
          "authorizationUrl": "https://<GOODDATA_HOST>/oauth2/authorize",
          "tokenUrl": "https://<GOODDATA_HOST>/oauth2/token",
          "scopes": {}
        }
      }
    },
    "bearerAuth": {
      "type": "http",
      "scheme": "bearer"
    }
  },
  "security": [{ "oauth2": [] }, { "bearerAuth": [] }]
}

Interactive SSO with OAuth 2.1

For A2A clients using OAuth 2.1, GoodData acts as the authorization server. The client starts an authorization code flow with Proof Key for Code Exchange (PKCE). GoodData directs the user through the organization’s existing OpenID Connect sign-in and then issues its own access token to the A2A client. The identity provider does not communicate with the A2A client directly or issue its token.

To enable interactive sign-in, open your organization’s Early Access settings and enable Interactive SSO. This setting is shared by the A2A Protocol and the MCP Server. If you also enable Interactive SSO - Consent Screen, users connecting through local clients are asked to approve the connection after signing in. For hosted clients, the consent screen is shown before an authorization code is sent to the client’s external callback, even when the consent-screen setting is disabled.

Interactive SSO is off by default and is not required when your A2A client authenticates using an API token or signed JWT. For shared configuration instructions, including activation, consent, and redirect policies, see OAuth 2.1 for Interactive AI Clients.

Whichever authentication method you use, the A2A client sends the token for the user on whose behalf it is calling GoodData in the same header:

Authorization: Bearer <TOKEN>

Every A2A call is associated with an authenticated user. GoodData applies that user’s data, metadata, and AI agent access permissions. The AI agent cannot access workspaces, datasets, or objects that the user is not authorized to access.

Visualization Results

When the AI Assistant creates a visualization through A2A, its response includes two artifacts: a visualization artifact containing the visualization definition as Analytics as Code JSON, and a visualization-data artifact containing executed data, including rows and columns. The calling agent can use the computed result without executing the visualization query separately.

Other artifacts depend on the skills enabled for the selected AI agent. For example, key driver analysis and what-if results can be returned when those capabilities are available to the agent.

Follow-Up Questions

If the AI Assistant needs more information to complete the request, the task enters the input-required state and the response includes questions with suggested answers. This state is not an error. Reply in the same conversation to continue.

Agent Selection and Error Handling

An agent-specific URL addresses the selected AI agent for both new requests and subsequent messages in the same conversation. GoodData checks the user’s access to that agent on each request.

For an unavailable or unauthorized agent, an Agent Card request returns an HTTP error. During an A2A conversation, errors can instead appear as a failed task with a machine-readable code in a DataPart. Check the task status and payload, not only the HTTP response status.

Other failures, such as reaching the AI query limit, can return a failed task with a text message but no error code.

For Agent Card requests, an unavailable agent returns HTTP 404, while an agent the user cannot access returns HTTP 403.

Limitations

The Beta implementation supports A2A requests and streaming but does not yet implement the full A2A protocol specification. The following limitations apply:

• Task cancellation: The cancel method is defined but does not cancel an ongoing request.
• Task resubscription: Reconnecting to an in-progress or completed task to receive its events again is not supported.
• Task pause and resume: Pausing and resuming an A2A task is not supported.
• Task listing: Listing previously completed tasks is not supported. You can retrieve an individual task by ID using tasks/get.
• Cross-agent orchestration: GoodData does not combine results from several AI agents in a single A2A call. The calling application is responsible for orchestration.