Vercel Agent Runs in the MCP + CLI: why it matters

Vercel Agent Runs are now inspectable directly from the Vercel MCP and the Vercel CLI, and the interesting part is not the feature itself. It is that "watch what your AI agent actually did" is quietly becoming a normal part of the toolchain, not a paid dashboard you squint at after the fact. Your coding agent can now ask another system for its own trace.

The announcement is short. I'm commenting on it, not reprinting it. Read the original: eve Agent Runs now available in the Vercel MCP and CLI. Everything factual below comes from there.

---

🔍 What actually shipped

Vercel added four MCP tools and four CLI commands that let a coding agent (or you) find, list, and read the full trace of an Agent Run. A trace here means the real internals: turns, messages, reasoning, tool calls, token usage, and tool input/output.

Here is the mapping, MCP tool to CLI command:

What you want	MCP tool	CLI command
Find projects with agent activity	list_agent_run_projects	vercel agent-runs projects
List recent runs for a project	list_agent_runs	vercel agent-runs list
Inspect one run's metadata + usage	get_agent_run	vercel agent-runs inspect <runId>
Pull the full trace	get_agent_run_trace	vercel agent-runs trace <runId>

get_agent_run exposes metadata, lifecycle events, usage, and subagent data. get_agent_run_trace is the deep one: it hands back the turn-by-turn record including reasoning and token counts.

Key takeaway: The headline is observability, not automation. You are being handed the flight recorder for your agent, and it speaks both MCP (for other agents) and plain CLI (for you).

---

⚡ The CLI-first detail most people will skim past

The line I care about most: every CLI subcommand supports --json for machine-readable output, and traces render as markdown when piped. Vercel's own note is that coding agents without MCP access can call the CLI directly to debug their own runs.

That is a bigger deal than it sounds for a small team.

• --json means it is scriptable. You can pipe a run's usage into jq, sum tokens across a day, or fail a CI step when a run burns more than a threshold.
• Markdown-on-pipe means it is readable. Redirect a trace into a file and it is a review artifact you can paste into a pull request or a bug report.
• No MCP requirement means no lock-in to one agent client. Any tool that can shell out can read the trace.

# rough shape of what becomes possible
vercel agent-runs list --json | jq '.[].id'
vercel agent-runs trace <runId> > run-trace.md   # markdown you can actually read

The moment your agent's behaviour is a text file, it stops being a black box and starts being something you can grep, diff, and blame.

---

💰 Why token usage in the trace is the sleeper feature

For anyone building on a learning budget, and that is most students and solo devs I know here in Sri Lanka, the expensive surprise with AI agents is not the mistake. It is the mistake that quietly loops five times and spends tokens doing it.

Because get_agent_run and the trace both expose token usage and subagent data, you can finally answer the question that actually costs money:

• Which run ate the tokens?
• Was it one bad prompt, or a subagent stuck in a retry loop?
• Is my agent reasoning for 20 turns to do a 2-turn job?

AI usage is billed in USD, so a token spike is a dollar spike, and a dollar spike is a real LKR number by the time it hits your card. If you want to sanity-check what a burn actually costs you locally, our freelancer USD to LKR calculator does that conversion in one field. Trace first, then translate the bill.

Signal in the trace	What it tells you
High token usage on one run	Cost outlier worth reading turn by turn
Many turns, little tool output	Agent is over-reasoning; tighten the prompt
Subagent data with repeated calls	Possible retry loop, the classic budget leak

---

🛠️ How I'd use it on a small project

You do not need an enterprise setup to get value here. My honest workflow if I were shipping on Vercel:

1. After a flaky agent task, run vercel agent-runs list to find the run.
2. vercel agent-runs inspect <runId> to check usage and lifecycle before reading anything.
3. If usage looks wrong, vercel agent-runs trace <runId> > trace.md and read the reasoning where it went sideways.
4. Wire --json into a tiny script that flags any run over a token budget, so the next surprise shows up in logs, not on the invoice.

None of that needs a paid observability vendor or a metrics stack you have to babysit. It is one CLI and a few lines of shell, which is exactly the budget a student project or a two-person team can carry. The habit is what matters more than the tooling: read one trace a day and you will build an instinct for what "normal" costs look like, so the abnormal one jumps out before it clears your card.

Bottom line: treat the trace like you already treat server logs. You would not run a production app with logging off. Running an AI agent with its trace unread is the same bet.

---

💡 What this means for you

If you are building with AI agents, the industry is telling you something with releases like this: agent output is not enough, agent process is the thing you now inspect, version, and cost-control. Vercel putting traces behind a --json-friendly CLI, and not only a fancy dashboard, is the part worth copying in your own tools.

You do not have to be on Vercel to take the lesson. Whatever agent you run, ask the same three questions after every task: what did it reason, what did it call, and what did it cost. If your setup cannot answer those, that is your next thing to fix. This release just made the answer one command away for people who happen to deploy there.