38편 · 약 17분

AI SDK 7: WorkflowAgent·Tool Approval·MCP Apps로 에이전트 런타임을 재구성한 방식

왜 지금 봐야 하나

Vercel은 2026년 6월 25일 AI SDK 7을 공개했다. 이번 릴리스는 모델 호출 헬퍼에 기능 몇 개를 더 얹은 수준이 아니다. TypeScript 기반 AI SDK를 '모델 호출 라이브러리'에서 '에이전트 런타임 표면'으로 넓힌 릴리스에 가깝다.

이번 변화가 중요한 이유는 세 가지다.

ToolLoopAgent 위에 durable/resumable 실행 경로인 WorkflowAgent가 올라왔다.
프롬프트에 섞어 넣던 환경값, 파일, 스킬을 runtime context / tool context / provider reference로 분리했다.
MCP를 단순한 도구 연결이 아니라 모델 가시성(model-visible)과 사용자 UI(app-visible)를 분리하는 호스트 구조로 밀어 올렸다.

즉, AI SDK 7은 “모델을 어떻게 부를까”보다 에이전트를 어디에서 멈추고, 무엇을 승인하고, 어떤 상태를 저장하고, 어떤 UI를 노출할까를 코드 표면에 드러낸다. 에이전트를 실제 서비스로 운영하는 팀이라면 이 변화가 더 중요하다.

핵심 변화 한눈에 보기

축	AI SDK 6까지의 감각	AI SDK 7에서 달라진 점	운영자가 바로 받는 영향
에이전트 실행 모델	메모리 안의 tool loop 중심	`WorkflowAgent`로 durable/resumable 실행 추가	재시도, 승인 대기, 프로세스 재시작 이후 복구를 런타임 차원에서 설계 가능
실행 컨텍스트	프롬프트/앱 코드에 흩어짐	`runtimeContext`, `toolsContext`, tool `contextSchema`	API 키·tenant·request ID 같은 서버 상태를 프롬프트 밖에서 안전하게 전달
자산 전달	파일/지침을 매 호출마다 다시 전송	`uploadFile`, `uploadSkill`, `ProviderReference`	큰 파일·스킬을 반복 전송하지 않고 참조로 재사용
HITL/가드레일	앱 바깥에서 임시로 막음	`toolApproval`, timeout, sandbox 표면	민감한 도구 승인, hung step 차단, 실행 경계 설명을 SDK 설정으로 표현
MCP 통합	도구 목록을 모델에 붙이는 수준	MCP Apps, model-visible/app-visible 분리, sandboxed iframe	모델에 보여줄 도구와 사람에게 보여줄 UI를 분리한 호스트 설계 필요
개발/검증 표면	데모 앱이나 임시 CLI 의존	`@ai-sdk/tui`, harness 연동	에이전트 루프를 터미널과 샌드박스에서 짧게 반복 검증 가능

AI SDK 7이 다시 그은 경계

AI SDK 7: 모델 호출 라이브러리에서 에이전트 런타임으로 넓어진 구조

1. `ToolLoopAgent` 위에 durable runtime이 생겼다

AI SDK 7 블로그는 이번 릴리스를 "에이전트를 개발하고, 실행하고, 관측하고, 다양한 harness와 연결하는 층"으로 설명한다. 그중 가장 구조적인 변화는 WorkflowAgent다.

WorkflowAgent 문서는 이를 durable, resumable agent라고 직접 규정한다. 같은 문서는 표준 ToolLoopAgent가 메모리 안에서만 돌기 때문에 프로세스가 죽으면 진행 상황이 사라진다고 설명한다. 반면 WorkflowAgent는 다음을 명시적으로 해결 대상으로 둔다.

프로세스 경계를 넘는 상태 유지
실패 시 처음부터가 아니라 마지막 체크포인트부터 재시도
승인 대기 같은 human-in-the-loop 중단/재개
툴 호출을 discrete workflow step으로 남기는 관측성

여기서 중요한 운영상의 차이

WorkflowAgent는 단순히 ToolLoopAgent의 확장판이 아니다. 문서 표를 보면 다음처럼 성격이 다르다.

항목	`ToolLoopAgent`	`WorkflowAgent`
패키지	`ai`	`@ai-sdk/workflow`
실행 환경	프로세스 메모리	workflow runtime
충돌/재시작 이후	진행 상황 유실	재개 가능
tool retry	수동	workflow step 기반 자동
주 사용 API	`generate()` / `stream()`	`stream()` 중심

즉, 단일 요청 안에서 짧게 끝나는 agent라면 ToolLoopAgent로 충분하지만, 승인 대기·외부 API 지연·다단계 툴 루프 때문에 실행 수명이 길어진다면 7.x에서는 아예 다른 런타임으로 넘어가라는 메시지다.

이 변화가 왜 중요하나

대부분의 실패는 모델 품질보다 실행 수명주기에서 난다. 예를 들어,

네 번째 툴 호출 직후 프로세스가 재배포됨
사람 승인 대기 중 서버가 재시작됨
장시간 돌아가는 agent가 step 6에서 일시적 API 오류를 만남

이때 처음부터 다시 시작하면 비용도 들고, side effect가 있는 도구라면 중복 실행 위험도 생긴다. AI SDK 7은 이 문제를 프롬프트 엔지니어링이 아니라 워크플로 런타임으로 끌고 간다.

2. prompt가 아니라 context와 reference로 상태를 넘긴다

AI SDK 7의 두 번째 핵심은 “환경 상태를 어디에 둘 것인가”에 대한 정리다. Runtime and Tool Context 문서는 컨텍스트를 shared runtime state와 per-tool execution state로 나눠 설명한다.

핵심 문장은 간단하다.

context는 서버 측 상태를 generation 또는 agent loop에 전달하지만, 자동으로 프롬프트에 들어가지는 않는다.

이 분리가 중요한 이유는 agent가 실제 환경에서 다루는 값이 대부분 모델 토큰으로 보내기 부적절하기 때문이다.

tenant 정보
feature flag
request ID
access token / API credential
내부 라우팅 값

`runtimeContext`와 `toolsContext`를 분리한 이유

공식 문서는 runtimeContext를 전체 루프가 공유하는 상태로, toolsContext를 tool 이름별 맵으로 설명한다. 그리고 각 도구는 자기 contextSchema로 검증된 값만 받는다.

이 설계가 실무에서 주는 이점은 분명하다.

서드파티 도구가 필요 없는 credential까지 읽지 못한다.
prepareStep에서 모델 선택/프롬프트/정책을 조정하면서도 민감값을 prompt에 싣지 않아도 된다.
telemetry에 어떤 context 필드를 포함할지 따로 정할 수 있다.

즉, “도구가 쓸 값”과 “모델이 볼 텍스트”를 더 이상 같은 통로로 보내지 않는다는 뜻이다.

파일과 스킬도 같은 방식으로 다룬다

File Uploads와 Skill Uploads 문서는 uploadFile / uploadSkill이 모두 ProviderReference를 반환한다고 설명한다. 이 값은 provider별 식별자 매핑이다.

실무 해석은 이렇다.

큰 PDF, 이미지, 데이터셋을 매 호출마다 다시 보내지 않는다.
SKILL.md 같은 지침 번들을 컨테이너형 provider 환경에 반복 전송하지 않는다.
대신 업로드 한 번 후 참조값만 다음 호출에 넘긴다.

하지만 여기에는 분명한 제한도 있다.

`ProviderReference`는 진짜 범용 자산 ID가 아니다

공식 문서는 provider를 바꾸면 파일을 양쪽 provider에 업로드하고 reference를 합쳐야 한다고 말한다. 즉, ProviderReference는 다중 provider 추상화처럼 보이지만 실제로는 provider별 로컬 ID 묶음이다.

이 점을 놓치면 “OpenAI에서 올린 파일을 Anthropic 호출에도 그대로 쓰겠지” 같은 잘못된 기대가 생긴다. AI SDK 7은 자산 전달 비용을 줄여 주지만, 자산 저장의 진짜 표준을 제공하는 것은 아니다.

3. MCP Apps는 '도구 노출'과 'UI 노출'을 분리한다

AI SDK 7 블로그에서 눈에 띄는 부분 중 하나가 MCP Apps다. 이 기능의 핵심은 단순히 MCP 서버에 붙는 것이 아니다. MCP Apps 문서는 호스트가 해야 할 일을 매우 명확히 적어 둔다.

MCP Apps capability로 서버에 연결
도구를 받아 model-visible과 app-visible로 분리
모델에는 model-visible tool만 전달
tool part에 붙은 ui:// 리소스를 읽음
HTML 리소스를 sandboxed iframe에 렌더링
iframe에서 허용된 요청만 다시 MCP 서버로 프록시

왜 이 구조가 중요한가

기존에는 “MCP 서버가 있으니 모델에 tool 목록을 다 붙이면 된다”는 식으로 접근하기 쉬웠다. 하지만 실제 서비스에서는 그렇지 않다.

모델이 직접 봐도 되는 도구
사람만 봐야 하는 설정/검토 UI
앱 내부에서만 불려야 하는 tool endpoint

이 셋은 권한 경계가 다르다. AI SDK 7은 이걸 _meta.ui.visibility와 sandboxed iframe 모델로 분리한다.

실무적으로는 오히려 호스트 책임이 늘어난다

공식 문서도 "안전하게 fetch/render할 수 있을 때만 MCP Apps capability를 광고하라"고 적어 둔다. 즉, 기능이 늘어난 대신 호스트 구현체가 책임져야 할 것이 늘었다.

모델에 넘길 tool filtering
ui:// 리소스 fetch 정책
iframe sandbox 옵션
어떤 iframe 요청을 다시 MCP 서버로 프록시할지 allowlist

이 구조는 강력하지만, 잘못 구현하면 도구 호출은 제한했는데 UI 경로가 우회 채널이 되는 문제가 생길 수 있다.

4. 승인·timeout·sandbox가 명시적 가드레일이 됐다

`toolApproval`은 민감한 도구를 공식적으로 멈추는 표면이다

Tool Approvals 문서는 기본 실행 모델이 “execute가 있으면 자동 실행”이라고 설명한다. 그리고 승인 상태를 네 가지로 나눈다.

not-applicable
approved
denied
user-approval

이 표면이 중요한 이유는 승인 로직을 애플리케이션 바깥 임시 코드가 아니라 agent loop 일부로 끌어왔기 때문이다. 파일 삭제, 결제, 메시지 전송, private data 접근 같은 작업을 특정 입력 조건에서 자동 거부하거나 사람에게 넘길 수 있다.

다만 문서는 중요한 제한도 분명히 적는다.

provider-executed tools는 provider 측에서 실행되므로 AI SDK tool approval을 사용하지 않는다.

즉, SDK 내부 툴과 provider 측 툴을 섞는 시스템이라면 “모든 도구가 같은 승인 규칙을 탄다”고 생각하면 안 된다.

timeout은 이제 모델 호출이 아니라 에이전트 루프 기준이다

AI SDK 7 블로그는 timeout이 total / per-step / per-chunk / per-tool 수준으로 들어왔다고 설명한다. 이건 long-running agent 운영에 더 가깝다.

예전에는 “모델 응답 하나가 오래 걸리는가”만 봤다면, 이제는 다음을 따로 끊어 볼 수 있다.

전체 run이 너무 길어지는가
특정 step이 멈췄는가
스트리밍 chunk가 끊겼는가
특정 tool만 유난히 오래 걸리는가

에이전트는 실패 방식이 일반 RPC보다 훨씬 많다. AI SDK 7은 그 실패들을 설정 가능한 budget으로 바꾼다.

sandbox는 생겼지만, 아직 완전한 격리는 아니다

블로그는 SandboxSession을 first-class abstraction처럼 소개하지만, 현재 reference 문서는 타입 이름 자체가 Experimental_SandboxSession이며 경고를 명확히 남긴다.

이 API는 experimental이며 patch release에서도 바뀔 수 있다.
sandbox를 넘긴다고 해서 tool 자체가 자동으로 격리되는 것은 아니다.
실제 tool 코드는 여전히 앱 프로세스에서 돌고, tool이 명시적으로 sandbox에 위임해야 한다.

이건 매우 중요한 운영 포인트다. “샌드박스 옵션을 켰으니 코드 실행 툴이 격리된다”고 오해하면 안 된다. AI SDK 7은 샌드박스로의 위임 인터페이스를 준 것이지, 임의의 tool을 자동으로 안전하게 만들지는 않는다.

5. TUI와 harness는 데모가 아니라 검증 루프를 짧게 만든다

AI SDK 7 블로그는 Codex, Claude Code 같은 agent harness와의 통합을 강조한다. Harnesses with Terminal UI 문서를 보면 @ai-sdk/tui는 reasoning, tool call, approval prompt를 터미널에 렌더링할 수 있다.

이 기능이 좋은 이유는 화려한 UI가 아니라 검증 비용을 낮춘다는 점이다.

브라우저 앱을 만들지 않고도 tool loop를 반복 실험 가능
harness + sandbox 조합으로 실제 에이전트 세션을 짧게 검증 가능
한 세션 수명 동안 동일한 상태를 유지하며 상호작용 가능

다만 문서는 세션당 터미널 런을 하나로 잡고, 재개가 필요하면 detach()나 stop()에서 상태를 따로 다루라고 적는다. 즉, TUI는 durability 그 자체가 아니라 durability를 시험하는 개발 표면에 가깝다.

6. 어떤 팀이 지금 도입을 검토해야 하나

팀/상황	AI SDK 7이 특히 맞는 이유	먼저 확인할 것
TypeScript 기반으로 agent 앱을 운영하는 팀	모델 호출, tool loop, UI stream, MCP, approval을 한 SDK 계열로 묶을 수 있음	실제로 Vercel Workflow를 쓸 것인지, 단순 `ToolLoopAgent`면 충분한지
긴 파일/문서를 반복적으로 다루는 팀	`uploadFile` / `uploadSkill`로 반복 전송 비용을 줄일 수 있음	provider를 바꾸는 경로가 있는지, re-upload 전략이 필요한지
MCP 기반 agent UI를 만들 팀	model-visible / app-visible 분리를 공식 패턴으로 가져갈 수 있음	iframe sandbox / proxy allowlist / `ui://` fetch 정책
HITL이 필수인 팀	`toolApproval`로 승인·거부·보류를 루프 표면에 올릴 수 있음	provider-executed tool이 승인 우회를 만들지 않는지
Codex/Claude Code 같은 harness를 내부 툴에 붙이려는 팀	TUI + harness + sandbox로 로컬 검증 루프를 빠르게 만들 수 있음	세션 수명주기, sandbox credential, 포트 노출 정책

7. 도입 전에 반드시 확인할 체크리스트

아키텍처 체크

WorkflowAgent가 필요한가, 아니면 ToolLoopAgent로 충분한가?
승인 대기/프로세스 재시작/장시간 툴 실행이 실제 문제인가?
provider별 파일/스킬 업로드를 중앙에서 관리할 저장 전략이 있는가?

보안 체크

toolApproval 대상 도구와 provider-executed 도구를 구분했는가?
MCP Apps host가 model-visible과 app-visible 도구를 확실히 분리하는가?
sandbox가 자동 격리라고 착각하지 않고, 실제 위임 경로를 코드로 강제하는가?

운영 체크

timeout을 total/step/tool 관점에서 각각 정의했는가?
workflow step 단위 관측성을 어디에 남길지 정했는가?
TUI/harness 검증 경로와 실제 프로덕션 승인 경로가 뒤섞이지 않는가?

8. 한 줄 결론

AI SDK 7의 핵심은 새 모델 커넥터가 아니라 에이전트를 어디서 멈추고, 무엇을 저장하고, 어떤 UI와 어떤 도구를 누구에게 보여줄지를 SDK 차원에서 나누기 시작했다는 점이다.

그래서 이 릴리스를 평가할 때는 단순히 “에이전트를 더 쉽게 만들 수 있나”를 묻기보다, 다음을 봐야 한다.

crash 이후 다시 이어갈 수 있는가
승인과 거부를 루프 안에서 공식적으로 다루는가
파일/스킬/credential을 prompt 밖으로 빼냈는가
MCP 도구와 UI의 가시성 경계를 분리했는가
sandbox가 실제로 격리를 보장하는지, 아니면 위임 인터페이스만 주는지 이해했는가

이 기준으로 보면 AI SDK 7은 단순한 SDK 업그레이드가 아니라, TypeScript 에이전트 런타임의 운영 표면을 한 단계 넓힌 릴리스다.