runAgentTUI()

Runs a ToolLoopAgent in an interactive terminal UI. The terminal UI reads user prompts, streams assistant responses, renders markdown, displays tool and reasoning sections, and handles manual tool approvals.

runAgentTUI runs until the user exits with Esc or Ctrl+C.

import { openai } from '@ai-sdk/openai';
import { runAgentTUI } from '@ai-sdk/tui';
import { ToolLoopAgent } from 'ai';


const agent = new ToolLoopAgent({
  model: openai('gpt-5'),
  instructions: 'You are a helpful terminal assistant.',
});


await runAgentTUI({
  title: 'Assistant',
  agent,
});

Import 

import { runAgentTUI } from "@ai-sdk/tui"

API Signature

Parameters

options:

RunAgentTUIOptions
RunAgentTUIOptions

agent:

AgentTUIAgent

title?:

string

tools?:

'full' | 'collapsed' | 'auto-collapsed' | 'hidden'

reasoning?:

'full' | 'collapsed' | 'auto-collapsed' | 'hidden'

responseStatistics?:

'outputTokenCount' | 'outputTokensPerSecond'

contextSize?:

number

sandbox?:

Experimental_SandboxSession

Returns

returns:

Promise<void>

Types

AgentTUIAgent

An agent that is compatible with the terminal UI:

type AgentTUIAgent = Agent<undefined, any, any, never>;

This means the agent has no per-call options and no structured output.

TerminalPartDisplayMode

Controls how terminal sections are displayed:

type TerminalPartDisplayMode =
  | 'full'
  | 'collapsed'
  | 'auto-collapsed'
  | 'hidden';
  • "full": Show the section header and full content.
  • "collapsed": Show only the section header.
  • "auto-collapsed": Show the latest section expanded until another visible section appears, then collapse it.
  • "hidden": Omit the section entirely.

ResponseStatisticsMode

Controls which response statistic is shown:

type ResponseStatisticsMode = 'outputTokenCount' | 'outputTokensPerSecond';
  • "outputTokenCount": Show the number of output tokens in the response.
  • "outputTokensPerSecond": Show output token throughput for the response.

Example with Tool Display Options 

await runAgentTUI({
  title: 'Assistant',
  agent,
  tools: 'auto-collapsed',
  reasoning: 'collapsed',
  responseStatistics: 'outputTokenCount',
  contextSize: 200_000,
});

Example with Sandbox 

import { createJustBashSandbox } from '@ai-sdk/sandbox-just-bash';


const sandboxSession = await createJustBashSandbox({
  cwd: '/home/user',
}).createSession();


await runAgentTUI({
  title: 'Sandbox Assistant',
  agent,
  sandbox: sandboxSession.restricted(),
});

The sandbox is forwarded to every agent.stream() call as experimental_sandbox, making it available to tool description functions and tool execute functions. Include the sandbox description in the agent instructions when the model should know sandbox-specific details such as the working directory or exposed ports.

Compatibility

Use runAgentTUI for agents that can run directly from free-form user input. Use agent.generate() or agent.stream() directly when you need fixed prompts, per-call options, structured output, custom result inspection, or custom stream processing.