Package com.xebialabs.xlrelease.osgi.api.a2a

Interface A2aTransportExtension

All Superinterfaces:
HostExtensionPoint
public interface A2aTransportExtension extends HostExtensionPoint
Implemented by a plugin bundle to provide the A2A wire layer — Agent Card resolution and the protocol calls — typically on the official a2a-java SDK, which the bundle embeds as its own private dependencies so the SDK's stack (its Jackson, transports, etc.) never touches the host classpath. This is the dependency-isolation seam: the host ships a minimal built-in JSON-RPC transport, and installing a transport bundle upgrades the wire layer without a restart.

Transport, not policy. The host's A2aAgentGateway remains the only caller and the policy enforcement point: feature toggle, agent allowlist (on the caller-supplied URL and the card-resolved endpoint), and audit all happen around this extension. An implementation must not add its own retry loops or redirect-following — a redirect answered by an agent must surface as an error, never be followed, or it would bypass the host's allowlist.

All parameter and return types are plain host-exported views (com.xebialabs.xlrelease.a2a.api.views); SDK/wire types must never appear in an implementation's public surface. Methods are synchronous, one round trip each, and must honour Thread.interrupt(). Failures are reported by throwing A2aGatewayException with a message a release author can act on.

Ordinary Spring bean in the bundle's X-Plugin-Context configuration, discovered via the plugin extension registry like every other HostExtensionPoint. When several transport bundles are installed, the host uses the first registered and logs the rest as ignored.

  • Method Details

    • fetchAgentCard

      A2aAgentIdentity fetchAgentCard(String agentCardUrl, String bearerToken)
      Fetches and parses the Agent Card. agentCardUrl may be the agent's base URL (the well-known path /.well-known/agent-card.json is appended) or the card URL itself (already ending in .json).

    • sendMessage

      A2aSendResult sendMessage(String endpointUrl, A2aSendRequest request)
      Sends one message to the agent's service endpoint (as resolved from its card — the host has already allowlist-checked it).

    • sendMessage

      default A2aSendResult sendMessage(String endpointUrl, A2aSendRequest request, A2aCallback callback)
      Like sendMessage(String, A2aSendRequest), additionally offering the agent a push-notification callback so it can wake the waiting Release task instead of being polled.

      A default that drops the callback on purpose: a transport bundle built before push support keeps resolving against this interface and keeps working — the task simply falls back to its slow polling heartbeat. Implementations with push support override this and attach the callback as the message's push-notification configuration.

    • getTask

      A2aTaskView getTask(String endpointUrl, String taskId, String bearerToken)
      Fetches the current state of a remote task.

    • cancelTask

      A2aTaskView cancelTask(String endpointUrl, String taskId, String bearerToken)
      Requests cancellation of a remote task.