# Build your own wrapper (/docs/guides/build-a-wrapper)



Because the protocol work lives in [`@a2a-wrapper/core`](/docs/reference/packages/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 [#install]

```bash
npm install @a2a-wrapper/core
npm install @a2a-js/sdk express uuid   # peer dependencies
```

## A minimal wrapper [#a-minimal-wrapper]

```ts title="src/cli.ts"
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:

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

## What `execute()` should do [#what-execute-should-do]

1. Register the task with `publishTask(bus, taskId, contextId)` when there is no prior task record.
2. Publish progress with `publishStatus(...)` (`working`, then `completed` or `failed`).
3. Deliver output with `publishFinalArtifact(...)`, or stream with `publishStreamingChunk(...)` and `publishLastChunkMarker(...)`.
4. Optionally publish [sideband events](/docs/concepts/observability) through `AgentEventEmitter`.
5. Honour cancellation through an `AbortController`.

For session handling, extend `BaseSessionManager` and implement `getOrCreate(contextId)`.

## Adding it to this monorepo [#adding-it-to-this-monorepo]

The repository's [contributing guide](/docs/community/contributing) has the full checklist for adding a new wrapper package: directory layout, workspace registration, changesets and documentation.

<Cards>
  <Card title="Core API reference" href="/docs/reference/packages/core" />

  <Card title="Contributing" href="/docs/community/contributing" />
</Cards>