@a2a-wrapper/core

This page is generated from packages/core/README.md and stays in sync with the repository.

Shared infrastructure core for A2A protocol wrapper projects. Provides logging, configuration loading, event publishing, agent card building, server bootstrapping, session management, and CLI scaffolding — so each wrapper only needs to implement its backend-specific executor. All A2A protocol/spec-version-specific logic lives here and nowhere else in this monorepo — see Protocol Versions.

InstallationCopy Anchor Link

npm install @a2a-wrapper/core

Peer dependencies (your wrapper project must install these):

npm install @a2a-js/sdk express uuid

Release ChannelsCopy Anchor Link

Canary builds publish automatically after each merge, tagged like @a2a-wrapper/[email protected]. They're unreviewed and have no changelog entry — useful for trying a fix ahead of a stable release, not for production. npm install @a2a-wrapper/core always resolves to the latest stable release regardless of how many canaries have shipped since.

Quick StartCopy Anchor Link

A minimal wrapper project using createCli:

import {
  createCli,
  type BaseAgentConfig,
  type A2AExecutor,
} from "@a2a-wrapper/core";

// 1. Define your backend-specific config
interface MyBackendConfig {
  apiUrl: string;
}
type MyConfig = BaseAgentConfig<MyBackendConfig>;

// 2. Implement the executor interface
class MyExecutor implements A2AExecutor {
  constructor(private config: Required<MyConfig>) {}
  async initialize() { /* connect to backend */ }
  async shutdown() { /* cleanup */ }
  async execute(context: any, event: any) { /* handle A2A tasks */ }
}

// 3. Wire it up with createCli
createCli<MyConfig>({
  packageName: "my-a2a-wrapper",
  version: "1.0.0",
  defaults: { /* full default config */ } as Required<MyConfig>,
  usage: "Usage: my-a2a-wrapper [options]",
  executorFactory: (config) => new MyExecutor(config),
  parseBackendArgs: (values) => ({
    backend: { apiUrl: values["api-url"] as string },
  }),
  loadEnvOverrides: () => ({
    backend: { apiUrl: process.env.MY_API_URL },
  }),
  extraArgDefs: {
    "api-url": { type: "string" },
  },
});

Run it:

node dist/cli.js --port 3000 --log-level debug --api-url http://localhost:8080

Protocol VersionsCopy Anchor Link

createA2AServer() speaks A2A v1.0 natively and is fully backward compatible with v0.3.x clients out of the box — there is nothing to configure. This is built on @a2a-js/sdk@^1.0.0's own compat/v0_3 translation layer, not a hand-rolled shim.

How negotiation works, per request:

• buildAgentCard() produces the native v1.0 AgentCard shape — supportedInterfaces[] (not the old url/additionalInterfaces/protocolVersion fields), with both 0.3 and 0.3.0 legacy aliases per transport binding. This preserves compatibility with the SDK's canonical 0.3 value and this project's historically advertised 0.3.0 value.
• GET /.well-known/agent-card.json reads the caller's A2A-Version request header: 1.0 returns the native v1.0 card; 0.3, 0.3.0, or no header at all returns a fully v0.3-shaped legacy card (url, additionalInterfaces, protocolVersion: "0.3.0"), so old clients keep working unmodified.
• POST /a2a/jsonrpc and the HTTP+JSON routes below /a2a/rest accept their native v1.0 shapes and transparently translate v0.3 requests and responses. JSON-RPC uses legacy methods such as message/send and message/stream; HTTP+JSON uses legacy routes such as /a2a/rest/v1/message:send. No separately configured v0.3 server is required.

Signed Agent Cards (A2A v1.0, JWS per RFC 7515) are supported as an opt-in extra — pass ServerOptions.agentCardSigning (or set AgentCardConfig.signing in your resolved config, reading the private key from an env-var-held JWK) and AgentCard.signatures gets populated automatically. Unsigned cards (the default) simply omit signatures.

import { createA2AServer } from "@a2a-wrapper/core";

// protocolVersion here is only the informational A2A-Version response
// header value — it does not gate which wire format is actually served;
// that's negotiated per-request as described above.
const handle = await createA2AServer(config, executorFactory, {
  protocolVersion: "1.0", // default
});

API ReferenceCopy Anchor Link

All public symbols are exported from the package root (@a2a-wrapper/core). Imports from internal module paths are not supported.

UtilsCopy Anchor Link

ConfigCopy Anchor Link

EventsCopy Anchor Link

Event TransportCopy Anchor Link

Pluggable transport layer for sideband observability events (MCP tool calls, agent reasoning, lifecycle). Decouples event emission from A2A protocol internals so you can route trace data to any backend.

Built-in transportsCopy Anchor Link

JSON configCopy Anchor Link

{
  "events": {
    "enabled": true,
    "transport": "http",
    "httpUrl": "https://telemetry.example.com/events",
    "httpTimeout": 5000,
    "httpHeaders": {
      "Authorization": "Bearer ${TELEMETRY_TOKEN}"
    }
  }
}

Custom transport (programmatic API)Copy Anchor Link

For Kafka, Redis, databases, or any custom sink — pass a transport function to createA2AServer():

import { createA2AServer } from "@a2a-wrapper/core";

const handle = await createA2AServer(config, executorFactory, {
  eventTransport: async (event) => {
    await kafkaProducer.send({
      topic: "agent-traces",
      messages: [{ value: JSON.stringify(event) }],
    });
  },
});

Or implement the EventTransport interface for full control:

import type { EventTransport, AgentEvent } from "@a2a-wrapper/core";

class MyTransport implements EventTransport {
  async send(event: AgentEvent): Promise<void> {
    await db.insert("events", {
      id: event.eventId,
      type: event.eventType,
      agent: event.agentId,
      trace: event.traceId,
      data: event.data,
      ts: event.timestamp,
    });
  }
}

Using the emitter inside an executorCopy Anchor Link

import { resolveTransport, AgentEventEmitter } from "@a2a-wrapper/core";

// Inside your executor's execute() method:
const transport = resolveTransport(config.events, bus, taskId, contextId);
const emitter = new AgentEventEmitter({
  agentId: "my-agent",
  agentName: "My Agent",
  traceId: ctx.contextId,
  transport,
});

// Emit events — they flow through the resolved transport
await emitter.emit("tool_call_start", { toolName: "read_file", arguments: { path: "/data.json" } });
await emitter.emit("tool_call_end", { toolName: "read_file", result: "...", durationMs: 42 });
await emitter.emit("thinking", { content: "The data shows a spike in CPU usage..." });

ServerCopy Anchor Link

SessionCopy Anchor Link

ExecutorCopy Anchor Link

CLICopy Anchor Link

Memory PersistenceCopy Anchor Link

Materialize instructions and skills into the agent's workspace at startup. The LLM reads these files as part of its context, giving it persistent knowledge across sessions.

Config exampleCopy Anchor Link

{
  "memory": {
    "instructions": "./memory/instructions.md",
    "skills": ["./memory/skills/code-review", "./memory/skills/testing"]
  }
}

SKILL.md formatCopy Anchor Link

---
name: code-review
description: Provides code review guidelines and checklists
license: MIT
compatibility:
  - copilot
  - opencode
allowed-tools:
  - read_file
  - search_files
---

# Code Review Skill

Instructions for the LLM on how to perform code reviews...

Skill directory structureCopy Anchor Link

memory/skills/code-review/
├── SKILL.md              # Required: manifest + instructions
├── scripts/              # Optional: executable scripts
├── references/           # Optional: reference documents
└── assets/               # Optional: static assets

Backend path mappingCopy Anchor Link

Usage in an executorCopy Anchor Link

import { materializeMemory, WELL_KNOWN_PATHS } from "@a2a-wrapper/core";

// In executor.initialize():
if (config.memory && workspaceDir) {
  await materializeMemory({
    memoryConfig: config.memory,
    configDir: config.configDir ?? process.cwd(),
    workspaceDir,
    paths: WELL_KNOWN_PATHS.copilot, // or wrapper-specific BackendPaths such as Antigravity's
  });
}

Note on agentCard.skills vs memory.skillsCopy Anchor Link

These are different concepts:

• agentCard.skills — A2A protocol metadata advertised to orchestrators and callers. External-facing. Describes what the agent can do at a high level for discovery and routing.
• memory.skills — Internal instructions materialized into the workspace for the LLM. Never exposed externally. Tells the LLM how to do things — patterns, guidelines, tool usage rules.

Keep both in sync manually. You may want different descriptions: the agent card skill is marketing-friendly for orchestrators, while the memory skill is technical and detailed for the LLM.

Sub-AgentsCopy Anchor Link

Expose remote A2A agents as MCP tools to the parent agent's underlying LLM runtime by spawning a2a-mcp-skillmap (GitHub) as a stdio child process. The parent reads a subAgents array from its config, generates a bridge configuration for skillmap, and registers the bridge as an MCP server before the executor handles its first request.

See .kiro/specs/a2a-subagents/ for the full spec (requirements, design, and tasks). See the a2a-mcp-skillmap GitHub repo for the bridge's own documentation — config schema, response modes, session continuity, sync budget, OpenTelemetry, and HTTP transport.

Config exampleCopy Anchor Link

{
  "subAgents": {
    "agents": [
      {
        "name": "coding",
        "agentCardUrl": "https://coding.example.com/.well-known/agent-card.json",
        "auth": { "mode": "bearer", "token": "${CODING_AGENT_TOKEN}" }
      },
      {
        "name": "research",
        "agentCardUrl": "https://research.example.com/",
        "endpointUrlOverride": "https://research.internal.local/.well-known/agent-card.json"
      }
    ],
    "options": { "responseMode": "artifact", "probeTimeoutMs": 5000, "syncBudgetMs": 30000 }
  }
}

Pinned skillmap versionCopy Anchor Link

The MCP entry invokes npx -y a2a-mcp-skillmap@<SKILLMAP_PACKAGE_VERSION> — never the unpinned package name — so a future skillmap release cannot silently change semantics. Bumping the pin is reviewed in PR.

Wrapper integrationCopy Anchor Link

Each wrapper provides a tiny adapter that maps the canonical SynthesizedMcpDescriptor into its own MCP entry shape (McpStdioServerConfig for a2a-copilot, McpLocalServerConfig for a2a-opencode), then merges the result into the resolved mcp map under descriptor.key:

import { bootstrapSubAgents } from "@a2a-wrapper/core";

if (this.config.subAgents?.agents?.length) {
  const result = await bootstrapSubAgents({
    subAgents: this.config.subAgents,
    workspaceDir,
    parentLogLevel: this.config.logging.level ?? "info",
    existingMcpKeys: new Set(Object.keys(this.config.mcp ?? {})),
  });
  this.config.mcp = {
    ...(this.config.mcp ?? {}),
    [result.descriptor.key]: this.toWrapperMcpEntry(result.descriptor),
  };
}

A2A SDK Re-exportsCopy Anchor Link

These re-exports isolate wrapper projects from direct SDK imports, so a major SDK upgrade only requires changes in @a2a-wrapper/core.

ContributingCopy Anchor Link

PrerequisitesCopy Anchor Link

• Node.js ≥ 20
• npm

DevelopmentCopy Anchor Link

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Type-check without emitting
npm run typecheck

# Clean build output
npm run clean

Code StandardsCopy Anchor Link

• TypeScript with strict: true
• JSDoc on every exported symbol
• Property-based tests (fast-check) alongside unit tests (vitest)
• Follow Keep a Changelog for CHANGELOG.md