Build your own wrapper
Add a new backend to a2a-wrapper by implementing the A2AExecutor interface and wiring it with createCli from @a2a-wrapper/core. A minimal TypeScript example and the steps to add it to the monorepo.
Because the protocol work lives in @a2a-wrapper/core, a new wrapper only needs a backend-specific executor and a thin CLI. You get the server, agent card, version negotiation, sessions and config loading for free.
Install
npm install @a2a-wrapper/core
npm install @a2a-js/sdk express uuid # peer dependenciesA minimal wrapper
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
class MyExecutor implements A2AExecutor {
constructor(private config: Required<MyConfig>) {}
async initialize() { /* connect to your backend */ }
async shutdown() { /* clean up */ }
async execute(context: any, event: any) { /* handle an A2A task */ }
}
// 3. Wire it up
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:8080What execute() should do
- Register the task with
publishTask(bus, taskId, contextId)when there is no prior task record. - Publish progress with
publishStatus(...)(working, thencompletedorfailed). - Deliver output with
publishFinalArtifact(...), or stream withpublishStreamingChunk(...)andpublishLastChunkMarker(...). - Optionally publish sideband events through
AgentEventEmitter. - Honour cancellation through an
AbortController.
For session handling, extend BaseSessionManager and implement getOrCreate(contextId).
Adding it to this monorepo
The repository's contributing guide has the full checklist for adding a new wrapper package: directory layout, workspace registration, changesets and documentation.
Integrate with agent frameworks
Use a2a-wrapper agents as execution nodes inside LangGraph, Google ADK, CrewAI, Microsoft Agent Framework or any A2A-capable orchestrator. The wrappers complement orchestration frameworks rather than replace them.
Troubleshooting
Fix common a2a-wrapper problems. Model not available, authentication errors, a missing core build or stale dependencies, unreachable agents, Codex sandbox failures in Docker, and expired sessions.