Workflow Agent and Terminal UI

Purpose and Scope

This page explains the terminal-facing agent workflow in the AI SDK and how it relates to durable workflow agents. The immediate developer problem is practical: during local development, demos, coding-agent experiments, and internal tools, you often need a usable agent interface before investing in a custom web UI. The @ai-sdk/tui package provides that interface by running an agent in an interactive terminal, rendering streamed assistant output, reasoning sections, tool activity, scrolling, and approval prompts. Sources: content/docs/03-agents/08-terminal-ui.mdx, content/docs/03-ai-sdk-harnesses/08-terminal-ui.mdx

The terminal UI is not a separate agent runtime. It is a presentation and interaction layer over agent-compatible generation and streaming methods. In the standard agents path, you create a ToolLoopAgent from ai, configure its model, instructions, and tools, then pass it to runAgentTUI. In the harness path, HarnessAgent requires a session on each call, so the docs show a small AgentTUIAgent adapter that injects one session for the lifetime of the terminal run. Sources: content/docs/03-agents/08-terminal-ui.mdx, content/docs/03-ai-sdk-harnesses/08-terminal-ui.mdx

WorkflowAgent belongs to the same family of terminal and agent experiences, but solves a different durability problem. The official WorkflowAgent guide describes durable, resumable agents that run inside a workflow, persist state across workflow step boundaries, and support approval flows that can survive interruption. For browser chat, the official workflow guide pairs that with WorkflowChatTransport, a ChatTransport implementation that reconnects when a stream ends without a finish event. In practice, choose terminal UI when you want an interactive local shell experience, and choose workflow transport when you need durable web streaming and reconnection.

Relevant Source Files

• content/docs/03-agents/08-terminal-ui.mdx - Documents the @ai-sdk/tui package for ToolLoopAgent, including installation, the runAgentTUI entry point, sandbox forwarding, display options, approval prompts, and exit behavior.
• content/docs/03-ai-sdk-harnesses/08-terminal-ui.mdx - Documents using @ai-sdk/tui with HarnessAgent, including package installation, the AgentTUIAgent adapter pattern, session lifetime, cleanup, and resume guidance.

Core Primitives

The primary primitive in the terminal path is runAgentTUI, imported from @ai-sdk/tui. It accepts a title, an agent object, and display or execution options. With a ToolLoopAgent, the shape is direct: construct the agent with a model such as openai('gpt-5'), give it instructions, attach tools built with tool, and call runAgentTUI({ title, agent }). The docs explicitly state that the terminal session runs until the user exits with Esc or Ctrl+C, so the function should be treated as the main interactive loop for a terminal program. Sources: content/docs/03-agents/08-terminal-ui.mdx

Tools are first-class in this interface rather than hidden implementation details. The terminal UI renders tool cards, can show or hide tool inputs and outputs, and can prompt the user when an agent emits a manual approval request. That matters because terminal-based agents are often used for operational or coding tasks where commands, file writes, network calls, or external actions need human oversight. The display controls let you tune how much tool detail is visible without changing the agent definition itself. Sources: content/docs/03-agents/08-terminal-ui.mdx

Sandbox support is another core primitive for terminal agents. The docs show creating a sandbox session with createJustBashSandbox, passing a restricted session to runAgentTUI, and relying on the terminal UI to forward it as experimental_sandbox on every agent call. Tool description functions and tool execute functions can then read the sandbox from their options and delegate command or file operations to that execution environment. If the model needs to reason about the environment, the docs recommend adding details such as working directory, public hostname, or exposed ports to the agent instructions. Sources: content/docs/03-agents/08-terminal-ui.mdx

Running a ToolLoopAgent in the Terminal

A minimal terminal agent starts with the same pieces used in the non-terminal agent APIs: a provider model, instructions, and optional tools. The terminal UI adds the user interaction loop around those pieces. The example below follows the documented shape and is useful as a starting point for local assistants, small internal tools, or demos where terminal rendering is sufficient.

import { openai } from '@ai-sdk/openai';
import { runAgentTUI } from '@ai-sdk/tui';
import { ToolLoopAgent, tool } from 'ai';
import { z } from 'zod';
 
const agent = new ToolLoopAgent({
  model: openai('gpt-5'),
  instructions:
    'You are a helpful terminal assistant. Answer in markdown and use tools when they help.',
  tools: {
    weather: tool({
      description: 'Get the weather in a location',
      inputSchema: z.object({
        location: z.string().describe('The location to get the weather for'),
      }),
      execute: async ({ location }) => ({
        location,
        temperature: 72,
      }),
    }),
  },
});
 
await runAgentTUI({
  title: 'Weather Agent',
  agent,
});

The same entry point also controls terminal rendering behavior. tools accepts values such as full, collapsed, auto-collapsed, and hidden; reasoning accepts the corresponding reasoning display modes; responseStatistics can show output token throughput or output token count; and contextSize allows the UI to show total token usage as a percentage of the model context window. These settings are presentation concerns, so they can be changed for different audiences without modifying model selection, prompt instructions, or tool implementations. Sources: content/docs/03-agents/08-terminal-ui.mdx

HarnessAgent Adapter Pattern

HarnessAgent is session-oriented, so the terminal UI integration needs a thin adapter that supplies a session to every generate and stream call. The harness terminal UI docs show installing @ai-sdk/tui, @ai-sdk/harness, a concrete harness package such as @ai-sdk/harness-codex, and a sandbox package such as @ai-sdk/sandbox-vercel. The example constructs a HarnessAgent with codex and createVercelSandbox, creates one session, wraps the agent as an AgentTUIAgent, runs runAgentTUI, and destroys the session in a finally block. Sources: content/docs/03-ai-sdk-harnesses/08-terminal-ui.mdx

This pattern is important because it keeps terminal UI lifecycle and harness lifecycle aligned. A terminal run should use one session, which lets the harness maintain state across turns while the user interacts with the terminal. The docs also call out the long-lived case: if a terminal tool needs to resume later, persist state from session.detach() or session.stop() rather than assuming the in-memory session will remain available. That makes the harness terminal path a useful bridge between quick local interaction and more durable agent orchestration. Sources: content/docs/03-ai-sdk-harnesses/08-terminal-ui.mdx

WorkflowAgent and Resumable Streaming

The workflow side extends the same agent mental model into durable execution. Official AI SDK docs describe WorkflowAgent from @ai-sdk/workflow as providing the same agent loop as ToolLoopAgent while adding automatic state persistence, tool schema serialization, and built-in approval flows that survive workflow step boundaries. This is the right choice when the problem is not just terminal interaction, but production durability: process crashes, long-running tool loops, human approval pauses, and retrying from checkpoints instead of restarting an agent turn.

For browser chat over workflows, the official guide introduces WorkflowChatTransport from @ai-sdk/workflow. It is used with useChat from @ai-sdk/react and configured with an api, maxConsecutiveErrors, and initialStartIndex. The transport expects a POST endpoint to start a workflow run and return an x-workflow-run-id response header, plus a GET endpoint at {api}/{runId}/stream for reconnection. The stream is converted into UI message chunks with createModelCallToUIChunkTransform and returned through createUIMessageStreamResponse.

API and Option Reference

Next Steps

Start with @ai-sdk/tui when you need the fastest path to a real interactive agent. Add tools and approval policies early so you can observe the exact tool cards and approval prompts your users will see. If your agent needs command execution, pass a restricted sandbox and document the environment in the agent instructions. If you move from local terminal interaction to durable production chat, use the WorkflowAgent and WorkflowChatTransport guides next so your stream can resume after workflow interruption or network failure.