@cycgraph/a2a

Official Agent2Agent (A2A) adapter for @cycgraph/orchestrator.

The orchestrator defines a narrow A2AClient port and carries no protocol dependency. This package implements that port on the official @a2a-js/sdk, so a graph can delegate a step to a remote agent with an a2a node.

Install

npm install @cycgraph/a2a @cycgraph/orchestrator

Usage

Remote endpoints live in a trusted registry, never in the graph. A graph names a server_id; the registry resolves the Agent Card URL and credentials at call time. This means an LLM-authored graph cannot point the engine at an arbitrary host.

import { a2a, graph, run, InMemoryA2AServerRegistry } from '@cycgraph/orchestrator';
import { createA2AClient } from '@cycgraph/a2a';

const registry = new InMemoryA2AServerRegistry();
await registry.saveServer({
  id: 'research-service',
  name: 'Research Service',
  agentCardUrl: 'https://agents.example.com/.well-known/agent-card.json',
  auth: { type: 'bearer', tokenEnv: 'RESEARCH_SERVICE_TOKEN' },
});

const briefing = graph({
  name: 'briefing',
  nodes: [
    a2a('research-service', {
      id: 'research',
      reads: ['topic'],
      inputs:  { topic: 'query' },
      outputs: { report: 'findings' },
    }),
  ],
});

const { findings } = await run(briefing, {
  goal: 'Research the topic.',
  memory: { topic: 'solid-state batteries' },
}, {
  runner: { a2aRegistry: registry, a2aClient: createA2AClient() },
});

Credentials are named environment variables, never literal values. A registry row holds no secret, so a database dump or a listServers() response cannot leak one.

What the engine guarantees at the boundary

• Everything a remote agent returns is recorded in the taint registry as external data, and the marking survives subgraph composition.
• A task that ends rejected or auth-required is not retried. The agent decided, or the credential cannot change mid-run.
• A task that stops in input-required pauses the workflow through the same human-in-the-loop machinery an approval node uses. The answer resumes the same remote task rather than starting a new one, including when the a2a node sits inside a subgraph.
• Budget and capability ceilings stop at the network. Remote spend is unmetered, bounded only by timeouts and the failure policy.
• Concurrency is capped per remote agent when the registry entry sets maxConcurrentTasks (max_concurrent_tasks on the wire). Each task holds a slot for its whole remote exchange, so a map, voting, or parallel-branch graph queues against that agent instead of firing every branch at once. The cap is shared process-wide by every run that resolves to the same server id and agentCardUrl, so queuing shows up as added latency and serialized ordering under fan-out, not as a network fault. Omit the field to leave the server uncapped.

Agent Card caching

A client caches each resolved Agent Card under the agentCardUrl and the credential headers it was fetched with, and keeps it for the lifetime of that createA2AClient() instance. Two registry entries that share one agentCardUrl but differ in auth therefore each resolve the card with their own credentials — one fetch per distinct URL-and-header pair, not one per URL — so a card fetched for one entry is never served to the other. Trace headers are excluded from the key. There is no TTL and no invalidation on success; only a failed resolution is evicted, so a transient fetch fault never outlives the request that hit it.

Because the usage above hands one client to a runner for the whole run, a card that changes on the remote side — rotated skills, new capabilities, or the same URL repointed at a different deployment — is not picked up until you build a fresh client with createA2AClient() or restart the process. If an agent's card is expected to change while your process is up, construct a client per run rather than sharing one. Requests themselves are never cached: auth and trace headers are resolved per call.

Trace context

Set propagateTraceContext: true on a registry entry to send W3C traceparent headers, joining the remote agent's work to your trace. It is off by default because it discloses your trace id to the receiving party.

Testing

Unit tests run against an injected stub and need no network. The composition suite in test/composition.test.ts runs live against the scenario servers in @cycgraph/test-servers and skips unless A2A_SCENARIO_SERVER is set:

docker-compose --profile playground up -d scenario-servers
A2A_SCENARIO_SERVER=http://127.0.0.1:4001 npx vitest run test/composition.test.ts

Without Docker, run the servers directly in another shell instead:

npm run start --workspace=packages/test-servers

Limitations

• Verified against the scenario servers in this repository, which are built on the official SDK, and not yet against an independent third-party agent. Whether real agents use input-required and rejected faithfully is unconfirmed.
• The polling path for tasks that return while still working is covered by unit tests only; no scenario server currently exercises it live.
• This package is the consuming half. Serving a cycgraph graph as an A2A agent is planned separately; toAgentCard in the orchestrator already produces the card.