parity, not approximation

Dev/prod parity for AI agents that kills 'works on my machine'.

Your laptop's OS, network, and local SQLite are not production, so agent bugs only show up after deploy. `a2a dev` runs your agent on a scale-to-zero cloud dev box that uses the same runtime and the same base image family as the deployed agent, wired to the same managed resources — real Postgres and Qdrant from one a2a.yaml. Behavior in dev matches prod, and parity bugs surface before you ship.

same runtime · same image family · same resources · same code

Try the cloud dev box Read the quickstart View the architecture

runtime match dev↔prod

translation layers

resource declaration

the problem

'It worked on my machine' is an environment gap, not a mystery.

Local development runs your agent against your laptop: a different OS, a different network, and usually a SQLite file standing in for the production database. None of that is what the agent runs against once deployed. So the code passes locally, ships, and then meets real Postgres, a real vector store, and a different base image — and the bug that was invisible in dev becomes a production incident. The gap between dev and prod is exactly where these bugs live.

Laptop OS, libraries, and network differ from the deployed runtime.

A local SQLite stand-in behaves unlike the Postgres the agent ships against.

Local vector shims aren't the managed Qdrant that runs in production.

Bugs from these differences only appear after deploy, as incidents.

the a2a way

The dev box runs what production runs.

`a2a dev` runs your agent on a scale-to-zero cloud dev box that shares the deployed agent's runtime and base image family. The resources you declare in a2a.yaml — Postgres, Qdrant — are provisioned from the same declaration in dev and in prod, with the same connection contract. The code you run is the code that deploys.

Runtime parityImage parityResource parityConfig & env paritySame code deploysParity surfaces bugs early

Runtime parity

`a2a dev` doesn't run your agent on your laptop. It runs on a scale-to-zero cloud dev box that uses the same runtime as your deployed agent. The interpreter, the process model, the way tool calls are dispatched — identical to production, not a local approximation of it.

Image parity

The dev box and the deployed agent come from the same base image family. Same OS libraries, same system dependencies, same defaults. A binary or a locale that exists in dev exists in prod, so 'it built fine locally' stops being a coin flip against the deploy target.

Resource parity

Declare `databases` and you get Postgres; declare `memory.tiers: [vector]` and you get Qdrant. The same a2a.yaml provisions those resources in dev and in prod from one declaration — Neon Postgres and managed Qdrant in production, the same connection contract in dev. Your agent talks to real Postgres, not a stand-in SQLite file.

Config & env parity

Resources are wired from your a2a.yaml declaration, so the connection strings, the environment your code reads, and the shape of the managed services match between dev and prod. There's no separate 'local config' that drifts from the deployed config over time.

Same code deploys

The agent code you run in `a2a dev` is the exact code that deploys. No translation layer, no build step that rewrites your agent for production, no 'works differently once shipped.' Dev and deploy run the same source against the same runtime and the same resource contract.

Parity surfaces bugs early

After deploy, in production, as an incident: 'but it worked on my machine.'

a2a dev box

In dev, while iterating — parity bugs surface before the deploy, not after.

dimension

laptop dev

a2a dev box

runtime

Your laptop OS, your local Python/Node, whatever versions you happen to have.

Same runtime as the deployed agent, on a scale-to-zero cloud dev box.

image

Local machine libraries and system deps that diverge from the deploy target.

Same base image family in dev and prod — one set of system defaults.

database

SQLite or a hand-rolled local Postgres that behaves unlike production.

Real Postgres in dev, Neon Postgres in prod — from one a2a.yaml declaration.

vector memory

A local vector shim or in-memory store that isn't what ships.

Qdrant in dev and managed Qdrant in prod — same connection contract.

when bugs appear

After deploy, in production, as an incident: 'but it worked on my machine.'

In dev, while iterating — parity bugs surface before the deploy, not after.

questions

Frequently asked.

What does dev prod parity mean for AI agents?

It means the environment you develop the agent in behaves the same as the one it runs in once deployed. With a2a, `a2a dev` runs your agent on a scale-to-zero cloud dev box that shares the deployed agent's runtime and base image family, and provisions the same managed resources — Postgres and Qdrant — from your a2a.yaml. So behavior in dev matches prod, and environment-specific bugs surface before you ship rather than after.

How does a2a kill 'works on my machine' for agents?

The 'works on my machine' problem comes from your laptop's OS, network, and local SQLite differing from production, so bugs only appear after deploy. a2a removes that gap: `a2a dev` doesn't run on your laptop at all — it runs on a cloud dev box using the same runtime and base image family as the deployed agent, wired to the same kind of managed Postgres and Qdrant. Same runtime, same image family, same resources means the same behavior.

Do I need a separate staging environment for my agent?

The dev box already mirrors production on the axes that usually cause staging-vs-production surprises: runtime, base image family, and the managed resources declared in a2a.yaml. Because dev matches prod on those, much of what a hand-maintained staging tier exists to catch surfaces during normal `a2a dev` iteration instead of in a separate environment you have to keep in sync.

Are the databases in dev the same as in production?

The declaration is the same, and so is the connection contract. Declaring `databases` in a2a.yaml gives you Postgres; declaring `memory.tiers: [vector]` gives you Qdrant. In production those are Neon Postgres and managed Qdrant; in dev the same declaration provisions the equivalent (locally via Docker Compose under `a2a chat`). Your agent talks to real Postgres and real Qdrant in both places — not a SQLite stand-in that behaves differently.

Is the code I run in dev the exact code that deploys?

Yes. There's no translation layer between dev and deploy — the agent source you run under `a2a dev` is what ships. Because the runtime, base image family, and resource contract match, running that same code in production doesn't reintroduce environment drift. Deployed agents additionally carry signed receipts, scoped grants, and an MCP server, but the agent logic itself is unchanged from dev to prod.

A real local HTTP server for your agent plus a `/_dev` console to invoke tools, set env, and stream results.

Read the guide →

All guides live in the guides index.

parity by default

Close the gap before you deploy, not after.

a2a cloud deploys any agent — LangGraph, OpenAI Agents SDK, CrewAI, or custom — and gives you a scale-to-zero cloud dev box that shares the deployed agent's runtime, base image family, and managed resources. One a2a.yaml declares your Postgres and Qdrant for both dev and prod; the code you run in dev is the code that ships. Deployed agents also carry signed receipts, scoped grants, and an MCP server — but the parity means what you saw in dev is what you get in prod.

Deploy from the CLI Describe an agent instead Plan a pilot