ai sdk tui

12 notes, read out of this brain and free to use. Each one was extracted from a source and is re-checked against its exam.

runAgentTUI function overview

runAgentTUI runs a local agent or chat transport 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.

runAgentTUI import

Import runAgentTUI from '@ai-sdk/tui'.

runAgentTUI parameters

runAgentTUI takes an options parameter of type RunAgentTUIOptions (required). The options object has the following fields: agent (AgentTUIAgent, optional) - The agent to run; must provide exactly one of agent or transport. The agent must not require per-call options and must not use structured output. transport (ChatTransport<UIMessage>, optional) - The transport used to communicate with a remote agent; provide exactly one of agent or transport. title (string, optional) - The title shown in the terminal UI; if omitted, no title is shown. tools ('full' | 'collapsed' | 'auto-collapsed' | 'hidden', optional) - Controls how tool call sections are displayed; defaults to 'auto-collapsed'. reasoning ('full' | 'collapsed' | 'auto-collapsed' | 'hidden', optional) - Controls how reasoning sections are displayed; defaults to 'auto-collapsed'. responseStatistics ('outputTokenCount' | 'outputTokensPerSecond', optional) - Controls which response statistic is shown in response headers; defaults to 'outputTokensPerSecond'. contextSize (number, optional) - The model context window size in tokens; when provided, the terminal UI shows total token usage as a percentage of this context window. sandbox (Experimental_SandboxSession, optional) - Sandbox session that is passed through to the agent as experimental_sandbox on every call.

runAgentTUI return type

runAgentTUI returns Promise<void>. The promise resolves when the terminal UI exits.

AgentTUIAgent type definition

AgentTUIAgent is defined as Agent<undefined, any, any, never>. This means the agent has no per-call options and no structured output.

TerminalPartDisplayMode type definition

TerminalPartDisplayMode controls how terminal sections are displayed. Type is 'full' | 'collapsed' | 'auto-collapsed' | 'hidden'. 'full' shows the section header and full content. 'collapsed' shows only the section header. 'auto-collapsed' shows the latest section expanded until another visible section appears, then collapses it. 'hidden' omits the section entirely.

ResponseStatisticsMode type definition

ResponseStatisticsMode controls which response statistic is shown. Type is 'outputTokenCount' | 'outputTokensPerSecond'. 'outputTokenCount' shows the number of output tokens in the response. 'outputTokensPerSecond' shows output token throughput for the response.

runAgentTUI basic example

Example showing basic runAgentTUI usage with ToolLoopAgent: ```ts 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, }); ```

runAgentTUI example with display options

Example showing runAgentTUI with tool display options: ```ts await runAgentTUI({ title: 'Assistant', agent, tools: 'auto-collapsed', reasoning: 'collapsed', responseStatistics: 'outputTokenCount', contextSize: 200_000, }); ```

runAgentTUI example with chat transport

Example showing runAgentTUI with a remote chat transport: ```ts import { DefaultChatTransport } from 'ai'; await runAgentTUI({ title: 'Remote Assistant', transport: new DefaultChatTransport({ api: 'https://example.com/api/chat', }), }); ```

runAgentTUI example with sandbox

Example showing runAgentTUI with a sandbox session: ```ts 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.

runAgentTUI compatibility guidance

Use the agent option for agents that can run directly from free-form user input. Use the transport option to communicate with a remote agent. Use agent.generate() or agent.stream() directly when you need fixed prompts, per-call options, structured output, custom result inspection, or custom stream processing.

Give your agent this brain