Vercel AI SDK 7 해설: AI 앱 개발은 모델 호출보다 런타임 컨텍스트·승인·하네스 경계를 먼저 설계해야 하는 이유

1. 한 줄 문제 정의

핵심 요약: AI SDK 7은 “모델을 부르는 라이브러리”가 아니라 장시간 동작하는 에이전트 런타임의 경계를 정하는 도구에 가깝다.

2026년의 AI 앱 개발에서 실제로 어려운 지점은 모델 API를 한 번 호출하는 코드가 아니다. 문제는 도구 호출, 파일 입력, 사람 승인, 재시도, 타임아웃, 관측 로그가 한 요청 안에 뒤섞이면서 어디까지를 애플리케이션 책임으로 볼지 흐려진다는 점이다.

Vercel이 2026년 6월 25일 공개한 AI SDK 7은 이 문제를 TypeScript 개발자가 다루기 쉬운 형태로 묶는다. reasoning 옵션, tool context, runtime context, WorkflowAgent, HarnessAgent, MCP Apps, TUI, telemetry가 한꺼번에 들어온 이유도 여기 있다.

이 글의 적용 범위는 Next.js, React, Node.js에서 AI 기능이나 내부 에이전트 도구를 만드는 개발팀이다. 반대로 단순 챗봇 하나를 빠르게 붙이는 수준이라면 AI SDK 7의 새 에이전트 계층을 전부 도입할 필요는 없다.

2. 먼저 결론

핵심 요약: AI SDK 7은 “모델 교체가 잦고, 도구 실행 리스크가 있고, 운영 로그가 필요한 팀”에게 먼저 가치가 있다.

추천 대상은 세 가지다. 첫째, 여러 모델과 provider를 비교하면서 비용과 품질을 조정해야 하는 팀이다. 둘째, agent가 shell, database, SaaS API 같은 실제 도구를 호출하는 팀이다. 셋째, Codex, Claude Code, OpenCode 같은 외부 agent harness를 제품이나 사내 도구 안에 통합하려는 팀이다.

아직 관찰만 해도 되는 경우도 있다. 단일 provider, 단일 prompt, 단일 응답 UI만 필요한 작은 기능이라면 `generateText`와 `streamText` 중심으로 충분하다. WorkflowAgent나 HarnessAgent까지 올리면 운영 경계가 선명해지는 대신 학습 비용과 테스트 범위가 늘어난다.

작성자 관점의 결론은 명확하다. AI SDK 7을 “최신 SDK니까 업그레이드”로 접근하면 과하다. 하지만 팀 안에 이미 tool calling, 승인, sandbox, 장기 실행, 모델 fallback 문제가 보인다면 이번 버전은 런타임 계약을 정리할 좋은 계기다.

3. 핵심 구조 분해

핵심 요약: AI SDK 7의 구조는 model call, agent loop, runtime state, external harness, observability 다섯 층으로 보면 이해가 쉽다.

첫 번째 층은 모델 호출이다. `generateText`, `streamText`, `generateObject` 같은 API가 provider 차이를 숨긴다. Vercel 문서 기준 AI SDK는 OpenAI, Anthropic, Google 등 여러 provider를 바꾸더라도 호출 형태를 크게 바꾸지 않게 설계되어 있다.

두 번째 층은 agent loop다. ToolLoopAgent는 모델이 생각하고 도구를 고르고 결과를 다시 읽는 반복 구조를 다룬다. 여기서 중요한 것은 도구가 단순 함수가 아니라 “실제 시스템에 영향을 줄 수 있는 실행 단위”라는 점이다.

세 번째 층은 context다. tool context는 특정 도구에만 필요한 API key, tenant id, sandbox id 같은 값을 전달한다. runtime context는 step 준비, model selection, tool approval, telemetry에서 공유되는 실행 상태다. 쉽게 말하면 tool context는 도구별 주머니, runtime context는 agent 실행 전체의 작업 메모장이다.

네 번째 층은 harness다. HarnessAgent는 Codex, Claude Code, Deep Agents, OpenCode, Pi처럼 이미 자체 실행 루프를 가진 agent를 AI SDK 쪽에서 같은 방식으로 다루기 위한 계층이다. 앱이 외부 agent마다 별도 adapter를 덕지덕지 붙이지 않도록 하는 장치다.

다섯 번째 층은 운영 관측이다. AI SDK 7은 telemetry, Node.js tracing channel, lifecycle events, performance statistics를 강조한다. agent가 실패했을 때 “모델이 틀렸다”가 아니라 어느 step, 어느 tool, 어느 timeout, 어느 approval에서 막혔는지 추적하기 위한 층이다.

4. 설계 의도 해설

핵심 요약: AI SDK 7의 설계 방향은 provider 추상화에서 runtime 추상화로 이동했다.

초기 AI SDK의 핵심 가치는 provider별 SDK 차이를 줄이는 데 있었다. 그러나 2026년의 AI 앱은 provider 호출보다 실행 흐름이 더 복잡하다. 모델은 파일을 참조하고, 도구를 부르고, 사람 승인을 기다리고, 프로세스 재시작 뒤에도 이어서 실행되어야 한다.

그래서 AI SDK 7은 “모델 옵션 통일”만으로 해결되지 않는 문제를 SDK 안으로 끌어들였다. reasoning control은 provider마다 다른 추론 설정을 한 줄 옵션으로 다루게 한다. tool approval은 위험 도구 실행 전에 사람 또는 정책이 멈출 수 있게 한다. WorkflowAgent는 승인 대기나 배포 중단 같은 현실적인 끊김을 견디도록 만든다.

이 선택의 trade-off도 있다. SDK가 더 많은 런타임 책임을 맡을수록 개발자는 편해지지만, 프레임워크에 묶이는 면도 커진다. 특히 durable workflow, sandbox, gateway routing까지 한 번에 도입하면 Vercel 생태계의 운영 모델을 받아들이는 결정이 된다.

따라서 AI SDK 7의 핵심 질문은 “Vercel을 쓸 것인가”보다 “우리 AI 기능을 단순 HTTP handler로 볼 것인가, 실행 상태가 있는 작은 작업 시스템으로 볼 것인가”에 가깝다.

5. 근거 및 비교

핵심 요약: AI SDK 7은 LangChain류 orchestration, 직접 provider SDK, 별도 coding agent harness 사이의 중간 계층을 노린다.

공식 발표에 따르면 AI SDK는 주간 다운로드 1,600만 이상이며, AI SDK 7은 develop, run, integrate, observe, beyond text agents의 다섯 영역을 확장했다. 이 숫자는 “많이 쓴다”는 근거일 뿐 “모든 팀에 맞다”는 뜻은 아니다. 중요한 근거는 SDK가 기존 텍스트 생성 API를 넘어 승인, durability, sandbox, tracing으로 이동했다는 방향성이다.

6. 실제 동작 흐름 / 단계별 실행 방법

핵심 요약: 업그레이드는 버전 변경보다 실행 경계 목록을 먼저 쓰고, 그다음 codemod와 작은 pilot로 진행해야 한다.

1단계는 현재 AI 기능을 분류하는 것이다. 단순 응답, 구조화 출력, tool calling, 장시간 실행, 사람 승인, 파일 입력, 외부 agent harness 중 어떤 유형인지 표시한다. 이 분류 없이 SDK만 올리면 새 기능을 어디에 써야 할지 모호해진다.

2단계는 v6 코드베이스라면 공식 codemod를 별도 branch에서 실행하는 것이다.

npx @ai-sdk/codemod v7

3단계는 tool context를 먼저 분리하는 것이다. 예를 들어 날씨 도구, 결제 도구, CRM 도구가 모두 같은 전역 context를 읽고 있다면 위험하다. AI SDK 7의 tool context는 도구별로 필요한 값만 주입하는 방향을 지원한다.

const agent = new ToolLoopAgent({
  model,
  tools: {
    crmLookup: tool({
      description: "고객 정보를 조회한다",
      inputSchema,
      contextSchema: z.object({
        tenantId: z.string(),
        readOnlyToken: z.string(),
      }),
      execute: async (input, { context }) => {
        return lookupCustomer(input.customerId, context);
      },
    }),
  },
  toolsContext: {
    crmLookup: { tenantId, readOnlyToken },
  },
});

4단계는 approval 기준을 코드로 적는 것이다. 읽기 도구는 자동 승인, 쓰기 도구는 정책 승인, 결제·삭제·외부 발송은 사용자 승인을 요구하는 식으로 나눈다.

const agent = new ToolLoopAgent({
  model,
  tools,
  toolApproval: {
    sendInvoice: "user-approval",
    deleteRecord: async ({ input, runtimeContext }) => {
      return runtimeContext.role === "admin" ? "user-approval" : "deny";
    },
  },
});

5단계는 장시간 실행이 필요한 작업만 WorkflowAgent 후보로 올린다. 모든 agent를 durable하게 만들 필요는 없다. 사람 승인을 기다리거나 배포 중 restart를 견뎌야 하는 작업부터 적용하는 편이 낫다.

6단계는 TUI로 로컬 pilot를 만든다. 앱 UI를 붙이기 전에 터미널에서 tool call, approval, timeout, trace가 의도대로 찍히는지 확인하면 디버깅 시간이 줄어든다.

7. 실수/함정(Pitfalls)

핵심 요약: AI SDK 7 도입 실패는 대부분 모델 선택이 아니라 권한, timeout, trace 누락에서 나온다.

함정 1: tool context에 너무 많은 값을 넣는다. 모든 도구에 user token, admin token, billing key를 한 번에 넘기면 tool context를 쓰는 의미가 사라진다. 예방 방법은 도구별 context schema를 최소화하고, 읽기 토큰과 쓰기 토큰을 분리하는 것이다. 복구 방법은 도구 실행 로그를 기준으로 실제 사용하지 않는 context 필드를 제거하는 것이다.

함정 2: approval을 UI 이벤트로만 생각한다. 승인은 버튼 하나가 아니라 재검증 지점이다. 사용자가 승인 버튼을 눌렀더라도 tool input, policy, role이 실행 직전에 다시 맞는지 확인해야 한다. AI SDK 7이 HMAC-signed approval과 replay hardening을 언급하는 이유도 여기에 있다.

함정 3: timeout을 request timeout 하나로 끝낸다. agent는 provider stream이 멈추거나, tool이 멈추거나, step 전체가 길어지는 식으로 여러 곳에서 stall된다. total, per-step, per-chunk, per-tool timeout을 나눠야 장애 원인을 찾을 수 있다.

함정 4: HarnessAgent를 “만능 adapter”로 오해한다. 외부 coding agent를 앱에 붙이면 코드 작성 능력은 올라가지만, repo 권한, sandbox, secret, PR 검증은 별도 정책이 필요하다. HarnessAgent는 통합 경계를 낮춰줄 뿐 운영 책임을 없애지 않는다.

8. 강점과 한계

핵심 요약: 강점은 TypeScript 앱과 agent runtime을 한 흐름으로 묶는 점이고, 한계는 운영 모델까지 같이 선택해야 한다는 점이다.

강점은 첫째, provider 전환 비용이 낮다는 점이다. Vercel 문서의 AI Gateway 설명처럼 모델과 provider를 문자열 또는 gateway provider로 지정하고 fallback, timeout, routing을 설계할 수 있다. 둘째, UI stream과 agent loop가 같은 TypeScript 생태계 안에서 이어진다. 셋째, tool approval과 WorkflowAgent가 장시간 agent 운영에서 자주 만나는 문제를 정면으로 다룬다.

한계도 선명하다. AI SDK 7의 새 기능을 제대로 쓰려면 테스트가 단순 snapshot에서 끝나지 않는다. tool input fixture, approval replay, timeout, trace id, sandbox 실패 케이스까지 검증해야 한다. 또한 Python 중심 데이터 파이프라인이나 LangGraph 기반 기존 agent 운영이 이미 안정화된 팀이라면 굳이 중심축을 바꿀 이유가 약하다.

다른 선택이 더 나은 경우도 있다. RAG pipeline이 핵심이고 connector가 많다면 LlamaIndex류가 빠를 수 있다. 로컬 개발자 coding task가 전부라면 Codex나 Claude Code 단독 사용이 단순하다. 반대로 제품 안에 agent를 넣고 사용자별 승인, UI, runtime state, model routing까지 함께 다뤄야 한다면 AI SDK 7이 더 자연스럽다.

9. 더 깊게 공부할 포인트

핵심 요약: 문서를 기능별로 읽지 말고 “실행 경계” 순서로 읽으면 도입 판단이 빨라진다.

먼저 AI SDK 7 발표 글에서 새 기능을 전체 지도처럼 본다. 그다음 AI SDK 공식 문서에서 `generateText`, `generateObject`, tool calling의 기본 흐름을 확인한다. 이미 이 기본 계층을 쓰고 있다면 runtime/tool context, tool approvals, WorkflowAgent로 넘어가면 된다.

AI Gateway 문서는 모델 가격 비교용으로만 보지 말고 routing, provider fallback, provider timeout, metrics를 운영 계층으로 읽어야 한다. 모델을 쉽게 바꿀 수 있다는 말은 “장애나 비용 변화가 있을 때 정책으로 바꿀 수 있다”는 뜻에 가깝다.

GitHub 저장소는 실제 API 변화와 examples를 확인하는 진입점이다. 특히 agent 관련 예제, UI streaming 예제, provider package 변경은 공식 블로그보다 저장소 쪽이 더 빨리 바뀔 수 있다.

참고자료

• Vercel Blog: AI SDK 7, 2026-06-25
• Vercel Docs: AI SDK, last updated 2026-06-17
• Vercel Docs: AI Gateway Models & Providers, last updated 2026-06-20
• GitHub: vercel/ai repository, 확인 2026-07-07

10. 실행 체크리스트 + 작성자 관점

핵심 요약: AI SDK 7 도입의 완료 기준은 “응답이 나온다”가 아니라 실패·승인·관측까지 재현되는 것이다.

• 현재 AI 기능을 단순 호출, 구조화 출력, tool calling, 장시간 agent, 외부 harness 통합으로 분류했는가?
• 도구별 context schema가 최소 권한 원칙을 따르는가?
• 읽기, 쓰기, 결제, 삭제, 외부 발송 도구의 approval 기준이 분리되어 있는가?
• total, per-step, per-tool timeout과 복구 메시지가 정해져 있는가?
• trace id, step number, tool input, tool output, approval decision을 로그에서 추적할 수 있는가?
• v6에서 업그레이드한다면 codemod 결과를 작은 pilot route에서 먼저 검증했는가?
• WorkflowAgent는 승인 대기나 restart 복구가 필요한 작업에만 우선 적용했는가?
• 외부 coding agent harness를 붙일 경우 sandbox, secret, PR 검증 정책이 별도로 있는가?

Definition of Done: AI SDK 7 pilot는 정상 응답, tool 승인 거절, tool timeout, provider fallback, 프로세스 재시작 후 재개, trace 조회까지 한 번씩 재현되면 완료로 본다.

작성자 관점에서는 AI SDK 7을 새 문법 묶음보다 운영 설계 도구로 보는 편이 맞다. 지금 팀에 agent runtime 문제가 없다면 억지로 올리지 않아도 된다. 하지만 이미 승인, 도구 권한, 모델 fallback, 장시간 실행이 제품 코드에 흩어져 있다면 이번 버전은 그 조각들을 한곳에 모으는 기회다.