invoking a tool
curl + print debugging
Hand-craft a curl or a throwaway script to hit one endpoint.
a2a /_dev console
Click the tool in /_dev, fill its args, and call it — no boilerplate.
agent dev console
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
0
runtime local vs. deployed
0
deploys to try a tool
console at 127.0.0.1:8000
the problem
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.
curl and throwaway scripts test one endpoint, not the agent invoking it.
Inline fixtures and shell exports drift from the real inputs and keys.
Print statements reconstruct a run after the fact — you don't see it happen.
Local mocks diverge from prod, so a local pass proves nothing about deploy.
the a2a way
Run it locally and drive it from the /_dev console.
`a2a dev --local` runs the agent through the local runtime contract 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 Postgres and Qdrant with `a2a chat` to reduce resource drift, then verify the deployed revision and smoke-test critical hosted skills separately.
Invoke each tool by handSet credentials right thereUpload test inputsStream results liveThe same runtime you'll shipReal DB and vector store
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.
side-by-side
curl-and-print vs. the /_dev console.
credentials
curl + print debugging
Export env vars in a shell and hope you set the right ones.
a2a /_dev console
Set keys and env vars in the console for the exact run you're testing.
test inputs
curl + print debugging
Paste a fixture inline or juggle temp files by hand.
a2a /_dev console
Upload files to .a2a/workspace/inputs; read outputs back from outputs.
seeing what happened
curl + print debugging
Sprinkle print statements and reconstruct the run from stdout.
a2a /_dev console
Watch tokens and tool calls stream live as the agent runs.
parity with prod
curl + print debugging
Local mocks diverge from prod; it works here, breaks there.
a2a /_dev console
Same runtime, plus real Postgres + Qdrant from a2a.yaml.
dimension
curl + print debugging
a2a /_dev console
invoking a tool
Hand-craft a curl or a throwaway script to hit one endpoint.
Click the tool in /_dev, fill its args, and call it — no boilerplate.
credentials
Export env vars in a shell and hope you set the right ones.
Set keys and env vars in the console for the exact run you're testing.
test inputs
Paste a fixture inline or juggle temp files by hand.
Upload files to .a2a/workspace/inputs; read outputs back from outputs.
seeing what happened
Sprinkle print statements and reconstruct the run from stdout.
Watch tokens and tool calls stream live as the agent runs.
parity with prod
Local mocks diverge from prod; it works here, breaks there.
Same runtime, plus real Postgres + Qdrant from a2a.yaml.
questions
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 before deployment. On the platform, deployment verification checks the expected image, runtime, live Agent Card, and advertised skills, while source review is asynchronous and advisory. To test behavior, explicitly invoke a hosted skill with bounded input and assert on its output; that real invocation can emit an Ed25519-signed ExecutionReceipt. See AI agent testing for the layered model.
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 — `a2a dev --local` lets you invoke tools, exercise inputs, and inspect outputs before anything leaves your machine. It reduces environment drift by using the same project and runtime contract, but a local pass is not a guarantee about cloud credentials, managed resources, networking, or the deployed revision. After deployment, check readiness and run a bounded hosted smoke invocation for critical behavior.
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.
keep reading
Related guides.
All guides live in the guides index.
try it before you ship it
Invoke every tool locally, then deploy with confidence.
a2a cloud gives you a local dev loop before you push: `a2a dev --local` opens the /_dev console for tools, skills, credentials, test inputs, and streamed results. Deployment adds managed services and scoped-grant support; Agent API, public `/invoke`, and standard MCP `tools/call` executions produce signed evidence.