Run an AI agent locally in one command.
a2a dev --local starts your agent at http://127.0.0.1:8000 with a live dev console — invoke tools by hand, set env vars, upload test files, stream results, and hot-reload on every save. Add a real Postgres and Qdrant with a2a chat, in the shape production uses. Then deploy the exact same runtime: running locally is running the real thing.
a2a dev --local · 127.0.0.1:8000 · /_dev console · hot reload
A hand-rolled dev harness never matches what deploys.
Running an agent on your machine usually means standing up a uvicorn or flask harness, a Procfile, a dev Dockerfile, and a Postgres you wire by hand — then hoping it resembles what actually ships. You curl the endpoint to test tools, restart the process on every edit, and still hit surprises in production because the local setup drifted from the deployed image. 'Works on my machine' stops meaning anything.
One command, a live console, then the same thing deploys.
a2a dev --local serves the agent at http://127.0.0.1:8000 with a dev console at /_dev. Add prod-shaped Postgres and Qdrant with a2a chat, iterate against hot reload, and deploy the identical runtime. The steps below are the whole local loop.
1 · Install and log in
Install the a2a CLI and authenticate once. From here every command — running locally, adding resources, deploying — is a2a. No per-framework harness, no bespoke Dockerfile to keep in sync with production.
2 · a2a dev --local
One command starts the agent at http://127.0.0.1:8000. It runs in Docker by default (--host-runtime for a direct Python process). Flags when you need them: --port, --host, --env-file .env.local, --workspace, --reload/--no-reload.
3 · Open the dev console
Point a browser at http://127.0.0.1:8000/_dev. Invoke tools by hand, set env vars, upload test files, and stream results as they run. The agent card is served at /.well-known/agent-card, exactly as it will be in the cloud.
4 · Add local resources
Run a2a chat to bring up the resources declared in a2a.yaml — a Docker Compose Postgres and Qdrant — so the agent has a real database and vector store on your machine. Same shape as prod, which runs managed Neon and Qdrant.
5 · Save, reload, repeat
Hot reload fires on every save. Change a tool, hit save, invoke it again from /_dev — no restart, no redeploy. The tight loop is the point: you test the agent on your machine before anything leaves it.
6 · Deploy the same thing
The runtime you ran locally is the runtime that deploys — same container, same agent card, same tool contract. Running locally is running the real thing, so a2a deploy ships exactly what you just tested, not a re-packaged approximation of it.
Hand-rolled harness vs. a2a dev --local.
Frequently asked.
How do I run an AI agent on localhost?
Install the a2a CLI, log in once, and run a2a dev --local in your agent directory. The agent starts at http://127.0.0.1:8000, with a dev console at http://127.0.0.1:8000/_dev and the agent card at /.well-known/agent-card. It runs in Docker by default; pass --host-runtime to run it as a direct Python process instead, and --port or --host to change where it binds.
How do I test an agent's tools locally?
Open the dev console at http://127.0.0.1:8000/_dev. It lets you invoke each tool by hand, set env vars for the run, upload test files, and stream results as they execute — no need to curl the endpoint or write a throwaway harness. Hot reload fires on every save, so you can change a tool, save, and invoke it again immediately without restarting.
Do I need Docker to run an agent locally?
By default a2a dev --local runs the agent in Docker, which is the closest match to how it runs in the cloud. If you'd rather run a direct Python process on your machine, pass --host-runtime. For local Postgres and Qdrant, a2a chat uses Docker Compose from your a2a.yaml — so Docker is the smoother path, but the agent process itself can run host-native.
How do I give the local agent a database and vector store?
Run a2a chat. It brings up the resources declared in a2a.yaml — a Docker Compose Postgres and Qdrant — so the agent has a real database and vector store on your machine. The shape matches production, which runs managed Neon Postgres and managed Qdrant, so the code paths you exercise locally are the ones that run in the cloud.
Is running locally the same as what deploys?
Yes. The runtime you run with a2a dev --local is the runtime that deploys — same container, same agent card at /.well-known/agent-card, same tool contract. Running locally is running the real thing, so a2a deploy ships exactly what you tested. If you'd rather iterate against a public URL without running anything on your machine, a2a dev spins up a scale-to-zero cloud dev box instead.
Related guides.
All guides live in the guides index.
Run the agent locally, then deploy the same thing.
a2a dev --local runs any agent — LangGraph, OpenAI Agents SDK, CrewAI, or custom — at http://127.0.0.1:8000 with a live /_dev console, hot reload, and local Postgres + Qdrant from a2a.yaml. The runtime you test on your machine is the runtime that deploys: same container, same agent card, same tools. Prefer a public URL without running anything locally? a2a dev gives you a scale-to-zero cloud dev box instead.