Test your AI agent locally, tool by tool.
Before you deploy, drive the agent on your own machine. `a2a dev --local` runs it in the same runtime it'll ship in and opens a dev console at http://127.0.0.1:8000/_dev — invoke each tool and skill by hand, set the credentials the run needs, upload real test inputs, and watch results stream live. When it passes here, the deployed agent works, because it's the same runtime.
a2a dev --local · /_dev console · same runtime · prod parity
print-debugging an agent tells you almost nothing.
The usual way to try an agent tool locally is to hand-write a curl, paste a fixture inline, export a few env vars in a shell, and read the run out of print statements after it finished. You're testing one endpoint at a time with no view into what the agent actually did, against mocks that diverge from production, so 'works on my machine' means nothing once it deploys. And to exercise the whole agent you end up standing up half your stack by hand every time.
Run it locally and drive it from the /_dev console.
`a2a dev --local` runs the agent in its real runtime and opens a console at http://127.0.0.1:8000/_dev. Invoke each tool and skill by hand, set env vars and credentials for the run, upload files to .a2a/workspace/inputs, and stream results live. Bring up real Postgres and Qdrant with `a2a chat` for prod parity — and because the runtime is the same one you deploy, a local pass is the real thing.
Invoke each tool by hand
The /_dev console lists every tool and skill your agent exposes and lets you call them one at a time with your own arguments. See exactly what a single tool returns before you wire it into a larger flow — no orchestrating the whole agent just to check one function.
Set credentials right there
Set env vars and provider keys in the console for the run you're testing. Point a tool at a real API with a real key and watch it succeed or fail for a real reason — not a mocked stub that always says yes.
Upload test inputs
Drop test files straight into the console; they land in .a2a/workspace/inputs and outputs come back in .a2a/workspace/outputs. Feed the agent the messy PDF or CSV it'll actually get in production and inspect what it writes back.
Stream results live
Invocations stream token-by-token and tool-call-by-tool-call, so you watch the agent think and act in real time. When something goes wrong you see where — which tool call, which argument — instead of reading it out of a log after the fact.
The same runtime you'll ship
`a2a dev --local` runs the agent in the same runtime it uses when deployed — Docker or --host-runtime, your choice. A local pass isn't a lookalike of production; it's the real thing on your machine, so green locally means the deployed agent works.
Real DB and vector store
`a2a chat` brings up the Postgres and Qdrant defined in a2a.yaml via Docker Compose, so you test tools against a real database and vector store — prod parity — instead of an in-memory fake that hides the queries that'll actually run.
curl-and-print vs. the /_dev console.
Frequently asked.
How do I test an AI agent locally with a2a?
Run `a2a dev --local` in your agent's directory. It stands the agent up on your machine — in Docker, or with --host-runtime if you'd rather run it directly — and opens a dev console at http://127.0.0.1:8000/_dev. From there you invoke each tool and skill by hand, set env vars and credentials, upload test files, and watch results stream live. The agent card is served at /.well-known/agent-card, and the workspace lives at .a2a/workspace with inputs and outputs directories.
How is this different from a2a's build-time agent testing?
This is the local dev loop: you drive the agent interactively on your machine before you ever deploy. Build-time testing is what happens on the platform — live smoke tests against a real preview URL, an automated reviewer gate, and an Ed25519-signed receipt per run. The /_dev console is where you get the agent working; the smoke tests and receipts are where the platform proves it works on every build. See AI agent testing for that side.
Can I test my agent's tools against a real database?
Yes. `a2a chat` uses Docker Compose to bring up the Postgres and Qdrant instances declared in your a2a.yaml, so your tools run against a real database and vector store instead of an in-memory stub. That prod parity matters: the queries and embeddings you exercise locally are the ones that'll run in production, so a local pass tells you the wiring actually holds.
Do I need to deploy to try my agent before shipping it?
No — that's the point of testing locally. `a2a dev --local` runs the agent in the same runtime it uses when deployed, so you can invoke every tool, feed it real inputs and credentials, and confirm the outputs before anything leaves your machine. Because the local and deployed runtimes are the same, a local pass means the deployed agent will behave the same way — you try it before you deploy, not after.
The agent worked locally but broke after deploy — where do I look?
That's a different phase from local testing, and it usually comes down to environment: credentials, config, or build steps that differ between your machine and the cluster. a2a proxies build and runtime logs into the control plane and dashboard so you can read exactly what the deployed agent did. See debugging AI agent deployment for the deploy-log side; the /_dev console covers the local runtime, and the deploy logs cover what happened once it shipped.
Related guides.
All guides live in the guides index.
Invoke every tool locally, then deploy with confidence.
a2a cloud deploys any agent — LangGraph, OpenAI Agents SDK, CrewAI, or custom — and gives you a local dev loop before you ever push. `a2a dev --local` runs the agent in the same runtime it ships in and opens the /_dev console: invoke tools and skills, set credentials, upload test inputs, and stream results, against real Postgres and Qdrant from your a2a.yaml. Deploy adds a managed database, an MCP server, an API, a frontend, scoped grants, and an Ed25519-signed receipt per run. Local parity first, proof on every build after.