`runAgentTUI()`
runAgentTUI()
대화형 터미널 UI에서 로컬 에이전트 또는 채팅 transport를 실행해요. 터미널 UI는 사용자 프롬프트를 읽고, 어시스턴트 응답을 스트리밍하고, 마크다운을 렌더링하고, tool 및 추론 섹션을 표시하고, 수동 tool 승인을 처리해요.
runAgentTUI 는 사용자가 Esc 또는 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-6-astra'),
instructions: 'You are a helpful terminal assistant.',
});
await runAgentTUI({
title: 'Assistant',
agent,
});
출처: 문서
본문
Import
<Snippet text={import { runAgentTUI } from "@ai-sdk/tui"} prompt={false} />
API 시그니처
매개변수 (Parameters)
<PropertiesTable
content={[
{
name: 'options',
type: 'RunAgentTUIOptions',
isRequired: true,
description: 'Options for starting the terminal UI.',
properties: [
{
type: 'RunAgentTUIOptions',
parameters: [
{
name: 'agent',
type: 'AgentTUIAgent',
isOptional: true,
description:
'The agent to run. Provide exactly one of agent or transport. The agent must not require per-call options and must not use structured output.',
},
{
name: 'transport',
type: 'ChatTransportagent or transport.',
},
{
name: 'title',
type: 'string',
isOptional: true,
description:
'The title shown in the terminal UI. If omitted, no title is shown.',
},
{
name: 'tools',
type: "'full' | 'collapsed' | 'auto-collapsed' | 'hidden'",
isOptional: true,
description:
'Controls how tool call sections are displayed. Defaults to auto-collapsed.',
},
{
name: 'reasoning',
type: "'full' | 'collapsed' | 'auto-collapsed' | 'hidden'",
isOptional: true,
description:
'Controls how reasoning sections are displayed. Defaults to auto-collapsed.',
},
{
name: 'responseStatistics',
type: "'outputTokenCount' | 'outputTokensPerSecond'",
isOptional: true,
description:
'Controls which response statistic is shown in response headers. Defaults to outputTokensPerSecond.',
},
{
name: 'contextSize',
type: 'number',
isOptional: true,
description:
'The model context window size in tokens. When provided, the terminal UI shows total token usage as a percentage of this context window.',
},
{
name: 'sandbox',
type: 'Experimental_SandboxSession',
isOptional: true,
description:
'Sandbox session that is passed through to the agent as experimental_sandbox on every call.',
},
],
},
],
},
]}
/>
반환값 (Returns)
<PropertiesTable
content={[
{
name: 'returns',
type: 'Promise
타입 (Types)
AgentTUIAgent
터미널 UI와 호환되는 에이전트:
type AgentTUIAgent = Agent<undefined, any, any, never>;
즉 에이전트에 호출별 옵션과 구조화된 출력이 없음을 의미해요.
TerminalPartDisplayMode
터미널 섹션이 표시되는 방식을 제어해요:
type TerminalPartDisplayMode =
| 'full'
| 'collapsed'
| 'auto-collapsed'
| 'hidden';
"full": 섹션 헤더와 전체 콘텐츠 표시."collapsed": 섹션 헤더만 표시."auto-collapsed": 다른 보이는 섹션이 나타날 때까지 최신 섹션을 펼침, 그 후 접기."hidden": 섹션을 완전히 생략.
ResponseStatisticsMode
표시되는 응답 통계를 제어해요:
type ResponseStatisticsMode = 'outputTokenCount' | 'outputTokensPerSecond';
"outputTokenCount": 응답의 출력 토큰 수 표시."outputTokensPerSecond": 응답의 출력 토큰 처리량 표시.
Tool 표시 옵션이 있는 예제
await runAgentTUI({
title: 'Assistant',
agent,
tools: 'auto-collapsed',
reasoning: 'collapsed',
responseStatistics: 'outputTokenCount',
contextSize: 200_000,
});
채팅 Transport가 있는 예제
import { DefaultChatTransport } from 'ai';
await runAgentTUI({
title: 'Remote Assistant',
transport: new DefaultChatTransport({
api: 'https://example.com/api/chat',
}),
});
Sandbox가 있는 예제
import { createJustBashNetworkSandboxSession } from '@ai-sdk/sandbox-just-bash';
const sandboxSession = await createJustBashNetworkSandboxSession({
cwd: '/home/user',
});
try {
await runAgentTUI({
title: 'Sandbox Assistant',
agent,
sandbox: sandboxSession.restricted(),
});
} finally {
await sandboxSession.destroy();
}
sandbox는 experimental_sandbox 로 모든 agent.stream() 호출에 전달되어 tool 설명 함수와 tool execute 함수에 사용할 수 있어요. 모델이 작업 디렉터리나 노출된 포트 같은 sandbox 특화 세부사항을 알아야 한다면 에이전트 지시에 sandbox 설명을 포함하세요.
호환성 (Compatibility)
자유 형식 사용자 입력에서 직접 실행할 수 있는 에이전트에는 agent 옵션을 사용하세요. 원격 에이전트와 통신하려면 transport 옵션을 사용하세요. 고정 프롬프트, 호출별 옵션, 구조화된 출력, 커스텀 결과 검사 또는 커스텀 스트림 처리가 필요할 때는 agent.generate() 또는 agent.stream() 을 직접 사용하세요.