A2A Transport

@caracalai/transport-a2a helps one agent call another agent endpoint through a Caracal-authorized A2A request.

Install

npm install @caracalai/transport-a2a

The package targets Node >=22 and depends on @caracalai/oauth and @caracalai/sdk.

Core API

import { a2aCall } from "@caracalai/transport-a2a";

const response = await a2aCall({
  agentUrl: "https://agent.example.com",
  resource: "https://agent.example.com",
  method: "summarize",
  params: { ticketId: "T-123" },
  requestId: crypto.randomUUID(),
  scopes: ["agent:call"],
}, subjectToken, zoneId, applicationId, {
  stsUrl: process.env.CARACAL_STS_URL!,
  clientSecret: process.env.CARACAL_APP_CLIENT_SECRET,
});

Request fields

Field	Meaning
agentUrl	Target agent base URL; the helper posts to ${agentUrl}/a2a.
resource	Optional STS resource; defaults to agentUrl.
method	A2A method name.
params	Method payload.
requestId	Correlation ID; response must echo it.
scopes	STS scopes for the target call.
sessionId, agentSessionId, delegationEdgeId	Optional context anchors.
metadata	Optional request metadata forwarded in the A2A body.

Options

Option	Meaning
stsUrl	STS base URL.
clientSecret, clientAssertion, clientAssertionType	Application authentication for token exchange.
ttlSeconds	Requested mandate TTL.
timeoutMs, retries, retryBaseMs	Exchange and request retry controls.
retryTransientStatuses	Retry transient A2A HTTP responses when true.
fetchImpl	Custom fetch-like implementation.
oauthClient	Test or custom token-exchange client.

Validation behavior

The helper exchanges a mandate, injects Caracal envelope headers, posts the A2A JSON body, and verifies the response contains the same requestId and a result field.