터미널 UI
터미널 UI (Terminal UI)
@ai-sdk/tui 패키지를 사용하면 로컬 ToolLoopAgent 를 실행하거나 ChatTransport 를 통해 원격 에이전트에 연결해 대화형 터미널 인터페이스에서 사용할 수 있어요. 터미널 경험으로 충분하고 커스텀 UI를 만들고 싶지 않은 로컬 개발, 데모, 내부 도구에 유용해요.
터미널 UI는 프롬프트 입력, 스트리밍된 어시스턴트 응답, 마크다운 렌더링, tool 카드, 추론 섹션, 스크롤, tool 승인 프롬프트를 처리해요.
출처: 문서
본문
설치 (Installation)
ai 및 사용하는 프로바이더 패키지와 함께 @ai-sdk/tui 를 설치하세요:
<Snippet text={pnpm add @ai-sdk/tui ai @ai-sdk/openai} prompt={false} />
에이전트 실행하기 (Running an Agent)
ToolLoopAgent 를 만들어 runAgentTUI 에 전달하세요:
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-6-astra'),
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,
});
runAgentTUI 는 사용자가 Esc 또는 Ctrl+C 로 종료할 때까지 실행돼요.
원격 에이전트에 연결하기 (Connecting to a Remote Agent)
agent 대신 ChatTransport 를 전달해 터미널 UI를 원격 AI SDK UI 메시지 엔드포인트에 연결하세요:
import { runAgentTUI } from '@ai-sdk/tui';
import { DefaultChatTransport } from 'ai';
await runAgentTUI({
title: 'Remote Agent',
transport: new DefaultChatTransport({
api: 'https://example.com/api/chat',
}),
});
transport는 엔드포인트, 인증, 요청 본문 및 기타 원격 통신 동작을 제어해요. 터미널 UI는 내부 채팅 id와 메시지 기록을 transport 계약에 대해 비공개로 유지해요.
Sandbox
에이전트 tools가 실행 환경을 필요로 할 때 sandbox 옵션으로 sandbox 세션을 전달하세요:
import { createJustBashNetworkSandboxSession } from '@ai-sdk/sandbox-just-bash';
const sandboxSession = await createJustBashNetworkSandboxSession({
cwd: '/home/user',
});
try {
await runAgentTUI({
title: 'Sandbox Agent',
agent,
sandbox: sandboxSession.restricted(),
});
} finally {
await sandboxSession.destroy();
}
터미널 UI는 모든 에이전트 호출에 sandbox를 experimental_sandbox 로 전달해요. tool 설명 함수와 tool execute 함수는 옵션에서 이를 읽고 명령이나 파일 작업을 위임할 수 있어요. 모델이 작업 디렉터리, 공개 호스트네임, 노출된 포트 같은 세부사항을 알아야 한다면 에이전트 지시에 sandbox 설명을 추가하세요.
표시 옵션 (Display Options)
tool 호출, 추론, 응답 통계가 표시되는 방식을 제어할 수 있어요:
await runAgentTUI({
title: 'Weather Agent',
agent,
tools: 'auto-collapsed',
reasoning: 'collapsed',
responseStatistics: 'outputTokensPerSecond',
contextSize: 200_000,
});
설정:
tools: tool 호출 렌더링 제어."full"은 tool 입력과 출력 표시,"collapsed"는 tool 카드만 표시,"auto-collapsed"는 다른 보이는 섹션이 나타날 때까지 최신 tool을 펼침,"hidden"은 tool 호출 생략. 기본값은"auto-collapsed".reasoning: 추론 렌더링 제어."full"은 추론 표시,"collapsed"는 추론 카드만 표시,"auto-collapsed"는 다른 보이는 섹션이 나타날 때까지 최신 추론을 펼침,"hidden"은 추론 생략. 기본값은"auto-collapsed".responseStatistics:"outputTokensPerSecond"는 출력 토큰 처리량 표시,"outputTokenCount"는 출력 토큰 수 표시. 기본값은"outputTokensPerSecond".contextSize: 제공되면 터미널 UI가 모델 컨텍스트 창의 백분율로 총 토큰 사용량을 표시.
Tool 승인 (Tool Approvals)
runAgentTUI 는 ToolLoopAgent tool 승인 흐름을 지원해요. 에이전트가 수동 승인 요청을 내보내면 터미널 UI는 에이전트가 계속하기 전에 tool 호출 승인/거부를 사용자에게 묻습니다.
const agent = new ToolLoopAgent({
model: openai('gpt-6-astra'),
tools: { weather },
toolApproval: {
weather: ({ location }) =>
location.toLowerCase().includes('san francisco')
? 'approved'
: 'user-approval',
},
});
await runAgentTUI({ title: 'Weather Agent', agent });
호환성 (Compatibility)
agent 옵션을 사용할 때 에이전트는 터미널 사용자 입력에서 직접 실행 가능해야 해요. 호출별 옵션이 필요해서는 안 되고 구조화된 출력을 사용해서는 안 되는데, 터미널 UI는 자유 형식 프롬프트에서 그 값들을 추론할 수 없기 때문이에요. 커스텀 요청 처리가 필요한 원격 에이전트에는 transport 를 사용하세요.
고정 프롬프트, 호출 옵션, 구조화된 출력, 커스텀 결과 검사 또는 커스텀 스트림 처리가 필요한 예제나 앱에는 agent.generate() 또는 agent.stream() 을 직접 사용하세요.
컨트롤 (Controls)
Enter: 프롬프트 제출y/n: tool 호출 승인 또는 거부Up/Down: 대화 내용(transcript) 스크롤PageUp/PageDown: 대화 내용 전체 페이지 스크롤Ctrl+L: 다시 그리기Esc/Ctrl+C: 종료
다음 단계 (Next Steps)
ToolLoopAgent인스턴스 만들기는 Building Agents- tool 호출의 사람 검토 설정은 Tool Approvals
- 상세 매개변수 문서는 runAgentTUI API Reference