AI SDK 7 프로덕션 에이전트: 올바른 런타임 경계 선택하기

AI SDK 7에서 중요한 변화는 모델을 호출하는 방법이 하나 더 생긴 것이 아닙니다. 승인, durable 실행, 코딩 하네스, 타임아웃, 샌드박스, 텔레메트리를 위한 경계가 더 명확해졌습니다. 각 기능을 원래 해결하려던 실패 모드에 배치해야만 도움이 됩니다.

실용적인 규칙은 실패 뒤에도 보존해야 할 상태를 기준으로 런타임을 선택하는 것입니다. 제한된 도구 루프, 배포 뒤에 재개될 수 있는 승인, 저장소를 수정하는 코딩 에이전트는 같은 워크로드가 아닙니다.

Vercel은 2026년 6월 25일 AI SDK 7을 발표했습니다. 8월 5일 조사 cutoff에서 npm은 ai 7.0.52, @ai-sdk/workflow 1.0.52, @ai-sdk/harness 1.0.58을 표시했습니다. 이 글은 해당 cutoff에 문서화된 안정적인 AI SDK 7 동작을 사용합니다. 실험적 하네스 API는 여전히 정확한 버전 고정과 release note 검토가 필요합니다.

실패 뒤 보존할 상태를 기준으로 선택합니다

세 개의 클래스 이름보다 세 개의 질문에서 시작하세요.

질문	런타임 경계	이유
하나의 제한된 요청 안에서 작업이 끝나는가?	ToolLoopAgent	durable 상태를 추가하지 않고 재사용 가능한 다단계 모델·도구 루프를 제공합니다.
재시작, 배포, 지연된 승인 뒤에 작업을 재개해야 하는가?	WorkflowAgent	실행이 workflow step 사이에 보존됩니다.
세션, skill, 파일 수정, 명령 실행을 갖춘 기존 코딩 하네스를 실행하는가?	HarnessAgent	모델 호출 주위에 기능을 다시 만드는 대신 하네스 전체를 연결합니다.

이는 엔터프라이즈 에이전트 플랫폼 결정 전체보다 좁은 범위입니다. identity, tool gateway, business context, 평가 소유권, registry까지 필요하다면 엔터프라이즈 에이전트 플랫폼 아키텍처 가이드부터 확인하세요. AI SDK 7은 주로 runtime과 실행 제어 plane에 해당합니다.

제한된 루프는 ToolLoopAgent 안에 둡니다

루프가 짧고 결과를 하나의 작업으로 재시도할 수 있으며 진행 중인 상태가 요청보다 오래 살아남을 필요가 없을 때 ToolLoopAgent를 사용합니다. 읽기 전용 조사, 분류, 제한된 retrieval이 일반적인 출발점입니다.

AI SDK 7은 approval policy를 도구를 사용하는 call 또는 agent에 둡니다. 위험은 맥락에 따라 달라지기 때문에 중요합니다. 같은 storage tool도 읽기에는 안전할 수 있지만 제한 없는 삭제에는 부적절합니다.

import { ToolLoopAgent, tool } from 'ai';
import { z } from 'zod';

const publishPost = tool({
  description: 'Publish one reviewed article revision.',
  inputSchema: z.object({
    slug: z.string(),
    expectedSha: z.string(),
  }),
  execute: async ({ slug, expectedSha }) => {
    return publishReviewedRevision({ slug, expectedSha });
  },
});

export const editorAgent = new ToolLoopAgent({
  model,
  instructions: 'Never retry a denied publication request.',
  tools: { publishPost },
  toolApproval: {
    publishPost: 'user-approval',
  },
  timeout: {
    totalMs: 60_000,
    stepMs: 20_000,
    chunkMs: 5_000,
  },
});

코드 형태는 공식 AI SDK 7 release 예제를 기준으로 했습니다. 모델이나 발행 credential로 실행하지 않고 문서와 대조했습니다.

tool()에 needsApproval을 넣는 오래된 예제를 복사하지 마세요. AI SDK 7 changelog는 tool-level needsApproval을 deprecated로 표시하고 generateText, streamText, ToolLoopAgent의 toolApproval로 옮기도록 안내합니다.

지연되는 작업은 WorkflowAgent로 옮깁니다

일반 서버 요청은 몇 시간 동안 승인을 열어 두기에 적합하지 않습니다. 사용자가 결정하는 동안 프로세스가 재시작되거나 배포가 인스턴스를 교체하거나 네트워크 연결이 사라질 수 있습니다.

@ai-sdk/workflow의 WorkflowAgent는 step 사이의 실행을 보존합니다. 공식 WorkflowAgent 개요는 tool call이 재시도하고, 승인을 위해 suspend하고, 나중에 resume할 수 있는 durable step이라고 설명합니다.

그렇다고 모든 작업이 workflow가 되는 것은 아닙니다. 다음 상태 전이 중 하나라도 process loss를 견뎌야 할 때만 루프를 옮기세요.

• 사람이나 외부 event를 기다리는 상태
• 완료된 step을 반복하면 안 되는 긴 batch
• durable idempotency 근거가 필요한 side effect
• 배포 뒤 다시 연결해야 하는 stream 또는 session

live client나 열린 connection 대신 identifier와 직렬화 가능한 데이터를 보존합니다. tenantId, runId, repository, branch, expected revision을 저장하세요. database 또는 API client는 사용하는 step 안에서 다시 만듭니다.

코딩 하네스를 다시 만들지 말고 감쌉니다

Codex, Claude Code, Pi는 provider wrapper 이상입니다. 해당 하네스는 session, permission, compaction, skill, command execution, repository interaction을 소유합니다. generateText 위에서 이 기능을 다시 만들면 보안과 유지보수 범위가 커집니다.

실험적 HarnessAgent는 기존 하네스를 AI SDK Agent interface에 연결합니다. Vercel의 하네스 발표에는 Claude Code, Codex, Pi adapter가 포함됩니다.

import { HarnessAgent } from '@ai-sdk/harness/agent';
import { claudeCode } from '@ai-sdk/harness-claude-code';
import { createVercelSandbox } from '@ai-sdk/sandbox-vercel';

const codingAgent = new HarnessAgent({
  harness: claudeCode,
  sandbox: createVercelSandbox({
    runtime: 'node24',
    ports: [4321],
  }),
  instructions: 'Make small changes and verify them before reporting success.',
});

이 예제는 문서와만 대조했습니다. 프로덕션 구현에는 repository allowlist, 최소 credential, outbound network policy, command와 run budget, default branch 보호 규칙이 여전히 필요합니다.

애플리케이션에 하네스를 포함하는 것보다 하나의 Claude Code 환경 설정이 당장 문제라면 하네스 엔지니어링 가이드가 더 직접적인 출발점입니다.

승인을 서명된 상태 전이로 취급합니다

사용자가 효과를 예측할 수 없다면 approval dialog는 통제가 아닙니다. 요청은 다음을 식별해야 합니다.

1. tool과 정확한 operation
2. 관련 input과 target revision
3. 외부 side effect
4. replay와 rollback 동작

“발행 승인”은 약합니다. “slug example의 revision abc123을 protected branch에 발행”은 approver가 검사할 수 있는 안정적인 대상을 제공합니다.

AI SDK 7은 replay hardening도 추가합니다. 공식 release는 continuation 전에 input과 policy를 재검증하고 고위험 흐름에서 opt-in HMAC-signed approval token을 사용할 수 있다고 설명합니다. 서명은 작업이 안전한지 판단하지 않습니다. 검토한 작업과 승인을 결합합니다.

거절을 해당 제안의 terminal state로 설계하세요. 모델이 조금 다른 표현으로 같은 효과를 즉시 다시 요청할 수 있다면 approval boundary는 policy가 아니라 prompt 관례가 됩니다.

에이전트가 멈출 수 있는 모든 방식에 budget을 둡니다

하나의 timeout은 느린 provider, 멈춘 tool, 무한 loop를 구분하지 못합니다. AI SDK 7은 다음 budget을 따로 문서화합니다.

• 전체 call
• 개별 model step
• stream chunk 사이의 시간
• 기본 tool budget
• 실행 특성을 알고 있는 특정 tool

approval wait는 또 다릅니다. 의도적으로 parked 상태인 durable workflow가 응답이 멈춘 tool과 같은 clock을 사용해서는 안 됩니다.

실패의 결과를 기준으로 각 budget을 설정합니다. search timeout은 partial result를 반환할 수 있고, build timeout에는 더 큰 고정 window가 필요할 수 있으며, payment timeout은 retry 전에 provider가 charge를 완료했는지 reconcile해야 합니다.

token 합계뿐 아니라 실행 경로를 관측합니다

total token만으로는 에이전트가 실패한 이유를 설명할 수 없습니다. 최소한 다음 identifier를 log와 trace에서 연결하세요.

runId
├─ callId
│  ├─ stepNumber
│  ├─ toolCallId
│  └─ approvalId
└─ tenantId or projectId

duration, selected model, stop reason, retry, approval outcome, sanitized tool status를 기록합니다. 전체 prompt, credential, file content, tool response를 기본값으로 telemetry에 복사하지 마세요. observability payload 경계가 application 경계보다 넓으면 두 번째 data leak이 될 수 있습니다.

되돌릴 수 있는 단계로 마이그레이션합니다

AI SDK는 v7 codemod와 migration skill을 제공합니다.

npx @ai-sdk/codemod v7
npx skills add vercel/ai --skill migrate-ai-sdk-v6-to-v7

이를 출발점으로 취급하세요. 자동 변경 뒤에는 type checker가 증명하지 못하는 동작을 검증합니다.

1. write tool에 의도한 approval policy가 유지되는가
2. 오래된 tool-level needsApproval 규칙이 조용히 사라지지 않았는가
3. maxSteps 동작이 명시적 stop condition이 되었는가
4. 지연된 작업이 process restart 뒤 resume하는가
5. workflow context가 직렬화 가능한가
6. harness와 sandbox package를 검토한 version으로 고정했는가
7. reconnecting stream이 side effect를 중복하지 않는가
8. denied와 timed-out operation이 서로 다른 audit state를 갖는가

작은 서비스라면 read-only ToolLoopAgent로 시작하세요. 다음으로 policy-controlled write tool을 추가합니다. durable recovery가 필요한 흐름만 WorkflowAgent로 옮기고 코딩 하네스가 실제로 필요한 작업에만 HarnessAgent를 도입하세요.

권고

세 런타임을 feature checklist처럼 모두 도입하지 마세요. 제한된 작업은 단순하게 유지하고, 지연된 상태는 durable하게 만들며, 저장소를 바꾸는 하네스는 격리하세요. 그런 다음 approval, timeout, idempotency, observability 규칙을 명시된 경계에 배치합니다.

가장 좋은 AI SDK 7 아키텍처는 agent feature가 가장 많은 구조가 아닙니다. restart, denial, timeout, replay가 각각 하나의 예측 가능한 결과를 만드는 구조입니다.

Primary sources

• AI SDK 7 발표
• AI SDK 7 changelog
• AI SDK ToolLoopAgent reference
• What is WorkflowAgent?
• AI SDK로 agent harness 실행하기