Debugging Agents Locally with the Vercel AI SDK v7 Terminal UI

Building agents that use tools is fun until something breaks. When a language model decides to pass a malformed JSON string into a tool, the standard debug process involves digging through massive, unreadable blocks of terminal output trying to find the exact frame where the hallucination happened.

Vercel AI SDK v7 introduces a built-in Terminal UI (TUI) to fix this. I built a quick local coding agent that reads files and runs bash commands to see if the TUI actually helps.

The Console.log Problem

Before v7, I would wrap every tool execution in a console.log and hope the output didn't scroll past my terminal buffer. You could use external tracing tools, but setting up OpenTelemetry for a local script you are just messing around with is overkill.

Enabling the TUI

You don't have to change your agent code to use the TUI. You just pass a reporter flag when you initialize the run.

import { generateText } from 'ai';
import { anthropic } from '@ai-sdk/anthropic';
import { TerminalReporter } from '@ai-sdk/tui';
import { z } from 'zod';
import fs from 'fs/promises';

async function runAgent() {
  const reporter = new TerminalReporter();
  
  const result = await generateText({
    model: anthropic('claude-3-5-sonnet-20240620'),
    prompt: 'Read my package.json and tell me what scripts I have.',
    reporter: reporter, // This activates the TUI
    tools: {
      readFile: {
        description: 'Read a file from the disk',
        parameters: z.object({ path: z.string() }),
        execute: async ({ path }) => {
          return await fs.readFile(path, 'utf-8');
        },
      },
    },
  });

  console.log('Final Answer:', result.text);
}

runAgent();

The Experience

When I ran the script, my terminal cleared and a split-pane interface appeared. On the left, I could see the live stream of the model's text generation. On the right, a structured log of tool calls appeared.

When the model called readFile, a loading spinner popped up next to the tool name. I could use my arrow keys to select the tool call and view the exact JSON payload the model sent, followed by the exact string my filesystem returned.

It feels like using React DevTools, but for LLMs in your terminal. I did notice it struggles with very long file outputs—reading a 5,000-line file caused the UI to stutter for a second before rendering. I would still rely on proper tracing for production observability, but for local development, I am never going back to raw console logs.