---
title: "A2A Transport"
url: "https://docs.caracal.run/sdks/transport-a2a/"
markdown_url: "https://docs.caracal.run/markdown/sdks/transport-a2a.md"
description: "TypeScript helper for agent-to-agent calls with STS exchange and Caracal context propagation."
page_type: "page"
concepts: []
requires: []
---

# A2A Transport

Canonical URL: https://docs.caracal.run/sdks/transport-a2a/
Markdown URL: https://docs.caracal.run/markdown/sdks/transport-a2a.md
Description: TypeScript helper for agent-to-agent calls with STS exchange and Caracal context propagation.
Page type: page
Concepts: none
Requires: none

---

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

## Install

```bash
npm install @caracalai/transport-a2a
```

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

## Core API

```ts
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.