An AI agent dev server with a console built in.
Run `a2a dev --local` and you get two things: a local HTTP server for your agent at http://127.0.0.1:8000, and a built-in development console at /_dev to drive it. The server is a FastAPI app mounting the real agent from your DSL — it serves the agent card, handles tool invocation, and does real file I/O. It's the agent's actual runtime, not a mock harness.
127.0.0.1:8000 · /_dev console · real runtime · hot reload
A mock harness lies to you until you deploy.
The usual local loop for an agent is a scratch harness: a script that fakes tool responses, a hand-written agent card fixture, stubbed file I/O. It runs, it's green, and then the agent breaks on deploy because none of it exercised the real server. You've been testing a simulation, not the runtime — and you find that out in production, not on your laptop.
The dev server is the agent's real server.
`a2a dev --local` mounts your agent on FastAPI and serves it at 127.0.0.1:8000 — the same runtime that runs deployed. A console at /_dev lets you invoke tools, set credentials, upload test files, and stream results, all against a real workspace with hot reload on save.
A real server, not a mock
`a2a dev --local` boots a FastAPI app that mounts your agent — built straight from the agent DSL — and serves it at http://127.0.0.1:8000. It is the same runtime that runs in production, not a stub that fakes responses. What passes locally is what ships.
Console built in at /_dev
Open http://127.0.0.1:8000/_dev and you get an agent development console: invoke tools and skills, set env vars and credentials, upload test files, and stream results back live. No Postman collection, no curl scaffolding — the UI to drive your agent ships with the server.
Serves the real agent card
The dev server exposes /.well-known/agent-card, the same discovery endpoint deployed agents serve. Point any A2A client at your local server and it sees the exact card, tools, and message surface it will see in production.
Real file I/O and workspace
The workspace is mounted at .a2a/workspace with inputs and outputs directories. Upload a test file in the console, the run reads it from inputs, writes to outputs — the same file plumbing your agent uses when deployed, running against your local disk.
Hot reload on save
Edit a tool, save, and the dev server reloads the agent — no restart, no lost console session. The loop is tight: change the DSL, hit the tool in /_dev, watch the streamed result. A2A_LOCAL_DEV=1 is set and .env.local is loaded so local config stays local.
Same server on a cloud dev box
Run the identical dev server on a scale-to-zero cloud dev box and it comes up with a public URL — hand it to a teammate, a webhook, or a real A2A client. Same console at /_dev, same agent card, same runtime; just reachable from off your laptop.
A mock harness vs. the real agent dev server.
Frequently asked.
What is the a2a agent dev server?
It is a local HTTP server for your agent. Running `a2a dev --local` boots a FastAPI app that mounts your agent — built from the agent DSL — and serves it at http://127.0.0.1:8000. It handles tool invocation, file I/O, and messaging, and serves the agent card at /.well-known/agent-card. It is the same runtime that runs when the agent is deployed, not a mock or stub.
How do I run the agent dev server locally?
From your agent project, run `a2a dev --local`. The server comes up at http://127.0.0.1:8000 with A2A_LOCAL_DEV=1 set and your .env.local loaded. Open http://127.0.0.1:8000/_dev for the built-in console, or point an A2A client at the server directly. Edits to your agent hot reload on save, so you rarely need to restart.
What is the /_dev console?
It is the agent development console the dev server mounts at /_dev. From the UI you can invoke any tool or skill, set environment variables and credentials for the run, upload test files into the workspace, and stream results back as they happen. It is the agent dev UI — the thing you use to drive the local server without writing curl commands.
Is the local dev server the real agent or a simulation?
It is the real agent. The dev server mounts the same agent built from your DSL and runs it on the same FastAPI runtime that serves the deployed agent. File I/O runs against a real workspace at .a2a/workspace with inputs and outputs directories, and the agent card served is the real one. There is no separate mock code path, so behavior that passes locally is the behavior that ships.
Can I run the dev server somewhere with a public URL?
Yes. The same dev server runs on a scale-to-zero cloud dev box and comes up with a public URL, so you can hand it to a teammate, a webhook, or an external A2A client that needs to reach your agent over the network. It is the identical server — same console at /_dev, same agent card, same runtime — just not bound to localhost.
Related guides.
All guides live in the guides index.
Drive your real agent from a console on localhost.
a2a cloud builds any agent — LangGraph, OpenAI Agents SDK, CrewAI, or custom — from the agent DSL and gives you `a2a dev --local`: a FastAPI dev server at 127.0.0.1:8000, a console at /_dev to invoke tools, set creds, and upload files, real workspace I/O, and hot reload. The same server runs on a scale-to-zero cloud dev box with a public URL. It's the agent's runtime, not a mock.