AI SDK 런타임
AI SDK 6를 애플리케이션 계층 표준으로 사용해 agent, tool, MCP, telemetry를 구성하는 방법을 정리합니다.
핵심 요약
- AI SDK는 단순 모델 호출 래퍼가 아니라 메시지·tool·approval·structured output·telemetry를 한 인터페이스로 묶는 앱 계층 표준입니다.
- 사용자-facing 요청은
streamText, JSON 계약이 핵심인 구간은 structured output, 도구 반복은ToolLoopAgent로 구분합니다. - mutating tool은 모두 strict schema와
needsApproval후보로 분류하고, 금전·권한·외부 커뮤니케이션에는 승인 게이트를 둡니다. - MCP의 resources(앱이 공급하는 읽기 문맥)와 tools(실행 권한)를 같은 수준으로 다루면 권한 경계가 흐려집니다.
- 장기 실행은 AI SDK 루프가 아니라 Workflow durable state로 옮깁니다.
AI SDK는 모델 호출 래퍼가 아니라 애플리케이션 계층에서 LLM 인터랙션을 표준화하는 인터페이스입니다.
엔터프라이즈에서는 이 계층에서 메시지, tool, approval, structured output, telemetry가 함께 움직여야 합니다.
AI SDK 6/7 경계 — 다음 세대 준비
AI SDK 문서는 Gateway model string, structured output, tool approval, agent UI stream을 계속 갱신합니다. 본문 예제는 plain provider/model 문자열과 최신 structured output 패턴에 맞췄습니다.
베타 주의
WorkflowAgent처럼 Workflow와 AI SDK를 더 직접 연결하는 기능은 빠르게 바뀝니다. 프로덕션 마이그레이션은 공식 GA/마이그레이션 문서를 기준으로 하고, 지금은 preview 환경에서 호환성을 검증하는 선에서 접근하세요.
Chat SDK 확장
Chat SDK에 두 가지 주요 어댑터가 추가되었습니다.
| 어댑터 | 용도 | 엔터프라이즈 활용 |
|---|---|---|
| WhatsApp 어댑터 | WhatsApp 채널을 통한 AI 대화 | 고객 지원, 알림 자동화 |
| PostgreSQL 상태 백엔드 | 대화 상태를 PostgreSQL에 영속화 | 기존 DB 인프라 활용, 규제 환경의 데이터 보존 요건 충족 |
PostgreSQL 백엔드는 기존 인메모리/Redis 기반 상태 관리보다 감사 추적과 데이터 보존 정책을 적용하기 쉬워서, 규제가 강한 엔터프라이즈 환경에서 특히 쓸모가 있습니다.
언제 AI SDK를 표준으로 볼 것인가
| 요구사항 | 필요한 기능 | AI SDK에서 보는 위치 |
|---|---|---|
| 채팅/생성 응답 | generateText, streamText | Core generation |
| 구조화된 결과 | generateText + Output.object() | output contract |
| tool loop | tools, agent loop | execution control |
| 승인 요구 | needsApproval | human gate |
| 외부 데이터 연결 | MCP client, resources, prompts | system context |
| 관측성 | telemetry, DevTools | traceability |
런타임 배치
low-level 호출과 agent 추상화의 경계
| 상황 | 권장 방식 | 이유 |
|---|---|---|
| 단일 요청, 단일 응답 | generateText / streamText | 제어 단순성 |
| JSON contract가 핵심 | structured output | downstream 오류 축소 |
| 도구를 1~2개만 제한적으로 사용 | tool calling + strict schema | 의도치 않은 action 축소 |
| 여러 tool을 반복 호출 | ToolLoopAgent | 루프 상태와 승인 포인트 명확화 |
| 장시간 대기/재시도 필요 | Workflow로 승격 | SDK 단독으로 durable state를 대체하지 않음 |
예시: 라우트 핸들러에서 thin runtime 유지
import { streamText, stepCountIs, tool } from 'ai'
import { z } from 'zod'
export async function POST(req: Request) {
const { messages } = await req.json()
const result = streamText({
model: 'openai/gpt-5-mini',
messages,
tools: {
searchDocs: tool({
description: '사내 문서를 검색합니다.',
inputSchema: z.object({
query: z.string(),
}),
execute: async ({ query }) => {
return fetchInternalDocs(query)
},
}),
},
stopWhen: stepCountIs(3),
})
return result.toUIMessageStreamResponse()
}승인·strict tools·MCP의 결합
| 기능 | 운영 목적 | 엔터프라이즈 기본값 |
|---|---|---|
| strict input/output | tool misuse 감소 | 모든 mutating tool에 적용 |
needsApproval | 사람 승인 게이트 | 금전·권한·외부 커뮤니케이션에 적용 |
| MCP resources | 애플리케이션 주도 문맥 공급 | 읽기 전용 기본값 |
| MCP tools | 실행 가능한 도구 | OAuth + audit log 필수 |
실무 해석
MCP를 붙였다고 agent가 저절로 안전해지지는 않습니다. resources는 앱이 공급하는 문맥이고, tools는 실행 권한입니다. 둘을 같은 수준으로 다루면 권한 경계가 흐려집니다.
telemetry 설계 원칙
| 추적 대상 | 이유 | 추천 태그 |
|---|---|---|
| model id | 비용/품질 비교 | provider, model, tier |
| conversation / task id | 사용자 영향 추적 | tenant, workflow id |
| tool call | side effect 감시 | tool name, approval 여부 |
| schema failure | 품질 이슈 감지 | output contract name |
| latency | 체감 성능 확인 | TTFT, total duration |
운영 기준
- 사용자-facing 요청은
streamText우선으로 설계합니다. - 데이터 계약이 중요한 구간은 JSON contract를 먼저 정의하고 prompt는 나중에 붙입니다.
- mutating tool은 모두 schema strict + approval candidate로 분류합니다.
- 장기 실행은 AI SDK loop가 아니라 Workflow state로 이동합니다.
ADR 스타일 결론
Decision
AI SDK는 앱 계층의 표준 인터페이스로 쓰고, 모델 벤더 SDK를 직접 노출하지 않습니다. generation, tool, MCP, telemetry를 한 인터페이스로 묶어야 운영과 평가가 일관됩니다.
실무 체크리스트
generateText와streamText사용 기준이 정해져 있는가- structured output이 필요한 경로에 schema contract가 정의돼 있는가
- mutating tool에 strict schema와 approval 후보 분류가 있는가
- telemetry에 model, tenant, workflow, tool tag가 남는가