Package com.xebialabs.xlrelease.a2a.api

Interface A2aAgentGateway

public interface A2aAgentGateway
The host's governed gateway for talking to external A2A (Agent2Agent protocol) agents.

This is the only supported way for in-process code — plugin task extensions in particular — to reach an external agent. The gateway, not the caller, is the policy enforcement point: every call checks the A2A feature toggle and the configured agent allowlist, resolves and validates the remote Agent Card (including allowlist-checking the endpoint the card names), and logs the exchange server-side. A plugin bundle therefore cannot bypass governance by construction, and never needs an HTTP client or A2A protocol types of its own.

The wire layer behind this gateway is pluggable: a bundle may contribute an A2aTransportExtension (e.g. embedding the official a2a-java SDK privately); without one, the host's minimal built-in JSON-RPC transport is used. Callers never see the difference.

Exposed to plugin bundles through the curated host API catalog: inject it by type in the plugin's X-Plugin-Context configuration class, like any other bridged host API. Methods are synchronous and short-lived (one HTTP round trip); a task extension that must wait for a remote agent suspends between calls (see TaskExecutorExtension) rather than blocking.

All methods throw A2aGatewayException on policy refusal, transport failure, or protocol error, with a message a release author can act on.

  • Method Details

    • sendMessage

      A2aSendResult sendMessage(A2aSendRequest request)
      Sends one message to the agent, after allowlist and feature checks. Starts new remote work, or continues existing work when A2aSendRequest.getTaskId() is set.

    • getTask

      A2aTaskView getTask(String agentCardUrl, String taskId, String bearerToken)
      Fetches the current state of a remote task previously started via sendMessage(com.xebialabs.xlrelease.a2a.api.views.A2aSendRequest). Callers poll this while !getState().isTerminal().
      Parameters:
      agentCardUrl - same value the task was started with (also re-checked against the allowlist)
      taskId - the remote task id from A2aSendResult.getTaskId()
      bearerToken - static bearer token for the remote agent, or null

    • cancelTask

      A2aTaskView cancelTask(String agentCardUrl, String taskId, String bearerToken)
      Requests cancellation of a remote task — the outbound half of the cascading stop: aborting a Release task that delegated work propagates the cancellation to the agent.
      Returns:
      the task view after the cancellation request (state may lag on slow agents)