Remote agents (A2A)

createAgentTool turns a local agent into a tool. createA2ATool does the same for an agent on another server: it posts to that server's REST endpoint and returns the answer as a tool result. From the model's point of view nothing is different.

What makes it more than an HTTP call is the runId. It is derived deterministically from the call, so a repeated POST has no second side effect — the remote runDurable replays the same run and returns the recorded result. And when the tool sits inside a parent runDurable, the parent journals it too: on a parent resume the remote call is skipped entirely.

That is the last boundary in the chain. A tool call, a sub-agent, a network router, a queued job, a cron fire and now a call to a different machine — the same guarantee holds at each of them.

Point it at the remote server and agent. The result carries the answer text, any interrupts, the remote agent name and the runId the remote replayed under — that last field is the exactly-once handle, and it is worth logging.

import { createA2ATool } from '@gnldev/a2a';

const research = createA2ATool({
  endpoint: 'https://research.internal',
  agentName: 'researcher',
  timeoutMs: 30_000,
  secret: process.env.A2A_SECRET,   // opt-in HMAC signing
});

const res = await runDurable({
  runId: 'brief-9',
  journal,
  model,
  tools: { research },
  prompt: 'Summarise the competitor landscape',
});

// the tool result carries the remote handle:
// { text, interrupts, runId: 'a2a:brief-9:call-3', remoteAgent: 'researcher' }

Inside runDurable the wrapper supplies an idempotencyKey that is already scoped to the parent run — {parentRunId}:{toolCallId}, or {parentRunId}:{toolName}:{hash} in args mode — and the remote runId is derived from it. That scoping is the point: it is globally unique.

Outside a durable context there is no such key, so the raw toolCallId is used instead, and it is only unique within one run. Some providers issue short ids like call_1; two unrelated runs can produce the same one, and then the remote side would replay the first run's recorded answer for the second call. Reaching this tool through runDurable avoids that; using it in a bare AI SDK loop makes id uniqueness your responsibility.

Signing is opt-in. Give a secret and the request goes out with x-gnl-signature — an HMAC-SHA256 over timestamp + '.' + body — plus x-gnl-timestamp, so the timestamp is part of what is signed and a captured body cannot be replayed indefinitely. The receiving server verifies it with createRestApi({ a2aSecret }). Without a secret the request is unsigned, which is the older behaviour and unchanged.

timeoutMs defaults to 30 seconds. On timeout the error is shaped like a step timeout: the wrapping durableTool writes a failed record and the model sees the real error rather than a silent hang.

// on the receiving server — verifies x-gnl-signature over timestamp + '.' + body
app.route('/api', createRestApi(config, { title: 'Research', a2aSecret: process.env.A2A_SECRET }));