Debug your AI agent locally with real breakpoints, real data.
Print-statement guessing and redeploy-to-find-out is a slow way to fix an agent. Debug it on your own machine instead. `a2a dev --local --host-runtime` runs your agent as a plain Python (uvicorn) process you can attach a debugger to — set breakpoints in your tools, drive individual tool calls from the /_dev console, watch requests and outputs stream, and reproduce against a real local Postgres and Qdrant. Find the bug and fix it before anything deploys.
host-runtime process · breakpoints · /_dev console · real local data
You can't attach a debugger to a black box.
Most agent workflows leave you debugging by inference: add a print, redeploy, read the log, form a new guess, redeploy again. The agent runs somewhere you can't reach, so you can't set a breakpoint, can't pause on the failing tool call, and can't inspect the argument the model actually passed. To reproduce a bug that only appears with a specific tool call you re-drive the whole agent to reach that one step — and if the failure depends on real data, your mocks don't reproduce it at all. Every hypothesis costs a round-trip, and you only ever see what you thought to log.
Run the agent as a local process you control.
`a2a dev --local --host-runtime` runs your agent as a direct Python (uvicorn) process on your machine — attach your debugger, set breakpoints, read tracebacks. The /_dev console drives a single tool or skill with your test inputs and streams the result, so you reproduce a failing call on demand. And `a2a chat` brings up real local Postgres and Qdrant, so you debug against production-parity data, not mocks. (Docker mode also runs locally; host-runtime is the debugger-friendly path.)
A plain Python process to attach to
`a2a dev --local --host-runtime` runs your agent as a direct uvicorn process on your machine — not buried in a container. Point your debugger at it, set breakpoints, and step through the tool that's misbehaving with the whole call stack in front of you. It's your interpreter, your PID, your pdb.
Set breakpoints in your tools
Drop a breakpoint inside the tool body, hit it on the next invocation, and inspect args, locals, and the model's inputs at the moment of failure. Because host-runtime is a real Python process, breakpoints in your IDE or a plain `breakpoint()` land exactly where you put them — no remote-debug plumbing.
Drive one tool from the /_dev console
The /_dev console lets you invoke a single tool or skill in isolation, set env vars, and upload test inputs — then watch the result stream back. Reproduce a failing tool call on demand instead of coaxing the whole agent into the exact state that triggered it.
Inspect tool calls as they stream
Watch requests come in and outputs go out in real time: which tool the model chose, the arguments it passed, what came back. When a tool returns the wrong thing, you see the exact call and payload — not a summarized log line after the fact.
Debug against real local data
`a2a chat` brings up local Postgres and Qdrant so you debug against real data with production parity, not mocks. Reproduce the bug that only shows up with actual rows and vectors, fix it, and confirm the fix against the same store — all on your machine.
Hot reload and retry the fix
Change the tool, save, and the local runtime reloads — retry the same call from /_dev or your debugger immediately. The edit-run-inspect loop stays on your machine and stays fast, so you converge on the fix in seconds, not deploy cycles.
Print-statement guessing vs. a debugger on the real runtime.
Frequently asked.
How do I debug an AI agent locally?
Run `a2a dev --local --host-runtime`. That starts your agent as a direct Python (uvicorn) process on your machine instead of inside a container, so you can attach your IDE's debugger, set breakpoints, and read tracebacks locally. Use the /_dev console to invoke individual tools with test inputs, and bring up real local Postgres and Qdrant with `a2a chat` so you're debugging against production-parity data. Fix, hot reload, retry — all before anything deploys.
How do I set a breakpoint in an AI agent?
Start the agent with `a2a dev --local --host-runtime` so it runs as a plain Python process, then set a breakpoint inside the tool or skill you're investigating — either in your IDE or with a `breakpoint()` call in the code. On the next invocation (drive it from the /_dev console or a normal request) execution pauses there and you can inspect the arguments the model passed, your locals, and the full call stack. Because host-runtime is a real interpreter rather than a remote sandbox, breakpoints just work without remote-debug wiring.
How do I inspect a failing tool call?
Use the /_dev console to invoke that single tool in isolation: set the env it needs, upload or type the exact inputs that trigger the failure, and watch the result stream back. You see the arguments going in and the output coming out without re-driving the whole agent to reach that step. Combine it with a breakpoint in the tool body under `a2a dev --local --host-runtime` and you can pause mid-call to read args and locals at the exact moment it goes wrong.
Why not just add print statements and redeploy?
Print-and-redeploy is a slow guessing loop: each hypothesis costs a deploy, and you only see what you thought to log. Debugging locally with `a2a dev --local --host-runtime` gives you the live process — set a breakpoint, inspect any variable you didn't anticipate, step through the tool, and reproduce the failing call from /_dev against real local data. You converge on the actual cause instead of narrowing it one redeploy at a time.
Is this the same as debugging a failed deployment?
No — this is dev-time debugging on your own machine, before anything ships. It's about attaching a debugger, setting breakpoints, and driving tools locally. Debugging a deploy that already failed in the cloud — build errors, crashlooping pods, Argo sync — is a different job handled by the deployment timeline; see Debug AI Agent Deployment (/debug-ai-agent-deployment) for build, pod, and Argo logs. Local debugging is where you fix the logic; the deployment timeline is where you diagnose the rollout.
Related guides.
All guides live in the guides index.
Trust the receipt.
a2a cloud runs any agent — LangGraph, OpenAI Agents SDK, CrewAI, or custom — and `a2a dev --local --host-runtime` runs it as a plain Python process on your machine so you can attach a debugger, set breakpoints in your tools, and step through the failing call. Drive single tools from the /_dev console, watch requests and outputs stream, and reproduce against real local Postgres and Qdrant via `a2a chat`. Hot reload the fix and retry immediately. Find the bug locally — and when a rollout breaks instead, the deployment timeline has the build and pod logs.