Vercel AI SDK 가이드: ToolLoopAgent·루프 제어와 승인

InYourLeague 리서치 · 2026-08-27

Answer in brief

ToolLoopAgent는 타입 안전 도구를 사용하는 다단계 모델·도구 루프를 재사용할 수 있게 해 주는 Vercel AI SDK 추상화로, 완료형 생성, 스트리밍, 종료 조건, 단계 준비, 수명 주기 콜백을 지원합니다. 공식 API에는 toolApproval도 있지만, 제공된 근거만으로는 승인 정책의 평가 방식이나 승인 상태 저장 및 재개 절차까지 확인할 수 없습니다.

Key facts at a glance

Failure modes and verification

FAQ

AI SDK 에이전트는 ToolLoopAgent로 시작하는 것이 권장됩니까?

예. 공식 Agents 개요는 루프와 메시지 배열 관리, 구성의 중앙화, 재사용성을 이유로 대부분의 에이전트 용도에서 ToolLoopAgent로 시작할 것을 권장합니다. 명시적인 워크플로 제어가 필요할 때는 코어 함수가 더 적합합니다.

도구의 타입과 컨텍스트 범위는 어떻게 정의합니까?

각 도구를 tool(), inputSchema, execute로 정의합니다. 도구별 타입 컨텍스트에는 contextSchema를 사용할 수 있으며, toolsContext는 각 도구에 해당 도구용 값만 전달합니다.

stopWhen은 무엇을 제어합니까?

stopWhen은 다단계 루프의 종료 조건을 정의합니다. 공식 ToolLoopAgent 레퍼런스에 따르면 하나의 StopCondition 또는 조건 배열을 받을 수 있지만, 제공된 근거는 기본 조건이나 배열의 결합 규칙을 설명하지 않습니다.

prepareStep에 관해 확인된 기능은 무엇입니까?

prepareStep은 생성자 훅이며 그 안에서 runtimeContext를 사용할 수 있습니다. 공식 Agents 개요는 단계 사이에서 runtimeContext를 갱신할 수 있다는 점도 확인하지만, 제공된 발췌문에는 이 훅의 완전한 반환 계약이 없습니다.

generate()와 stream()은 언제 각각 사용합니까?

최종 텍스트와 단계 정보처럼 완료된 에이전트 결과가 필요하면 generate()를 사용합니다. 응답을 점진적으로 전달해야 하면 stream()을 사용합니다.

도구 출력과 실행 시간은 어느 콜백에서 제공됩니까?

공식 ToolLoopAgent 레퍼런스에 따르면 toolOutput과 toolExecutionMs는 onToolExecutionEnd 이벤트에 포함됩니다. 이 필드를 onEnd나 onFinish에 공통으로 제공되는 값처럼 표현해서는 안 됩니다.

제공된 근거로 확인되는 승인 기능의 범위는 어디까지입니까?

생성자는 toolApproval을 제공하며, 문서는 사용자 승인이 필요한 상태를 에이전트 실행의 한 경계로 다룹니다. 승인 정책 판정, 승인 상태 저장, 사용자 인터페이스, 재개 절차, 종단 간 실행 방지 보장은 제공된 발췌문으로 확인되지 않습니다.

Sources and freshness

• Official source
• Official source
• Last verified: 2026-08-27

Extended guide

확인된 범위

공식 Agents 개요는 에이전트를 모델이 도구를 반복해서 사용하는 구조로 설명합니다. 이 루프에서는 컨텍스트 관리가 각 단계에서 모델에 보여 줄 내용을 결정하고, 종료 조건이 작업을 언제 끝낼지 결정합니다. ToolLoopAgent는 이 구조를 재사용 가능한 클래스로 제공합니다. generate()는 여러 단계에 걸쳐 도구를 호출한 뒤 완료된 결과를 반환할 수 있습니다. 개요의 예제는 최종 답변을 result.text에서, 실행 단계들을 result.steps에서 읽습니다. 같은 클래스의 stream()은 응답을 스트리밍하는 호출 경로입니다.

Vercel은 대부분의 에이전트 용도에서 ToolLoopAgent로 시작할 것을 권장합니다. 루프와 메시지 배열을 클래스가 관리하고, 구성을 한곳에 모을 수 있으며, 같은 에이전트 정의를 여러 호출에서 재사용하기 쉽기 때문입니다. 반면 조건 분기, 오류 처리, 단계별 진행을 개발자가 명시적으로 제어해야 하는 구조화된 워크플로에는 generateText와 streamText 같은 코어 함수를 사용하도록 안내합니다.

구성 항목

실무 적용 순서

1. 공급자 모델을 가리키는 model, 일관된 instructions, 이름이 지정된 tools 레코드로 하나의 ToolLoopAgent를 구성합니다. 여러 요청에서 공통으로 사용할 동작은 에이전트 정의에 두고, 요청마다 달라지는 값은 호출 옵션이나 런타임 컨텍스트로 전달합니다.
2. 각 도구에 필요한 입력만 받는 inputSchema와 execute 함수를 정의합니다. 특정 도구가 API 키나 제한된 권한을 필요로 한다면 해당 도구의 contextSchema를 선언하고, toolsContext에는 그 도구에 필요한 값만 제공합니다.
3. 애플리케이션의 의도에 맞는 stopWhen 종료 조건을 추가하고, 실제로 여러 도구 호출이 이어지는 대표 경로를 시험합니다. 공식 자료에 없는 기본 조건이나 조건 배열의 결합 방식을 추측해서 구현하면 안 됩니다.
4. prepareStep은 전체 API 계약을 확인한 범위에서 사용합니다. 제공된 근거는 이 훅에서 runtimeContext를 사용할 수 있다는 점을 확인하지만, 가능한 모든 반환값이나 단계 변경 방식까지 규정하지는 않습니다.
5. 전달 방식에 따라 generate() 또는 stream()을 선택합니다. 실행 관찰에는 수명 주기 콜백을 사용하되, 도구 실행 전후 콜백과 에이전트 수준의 onEnd 및 onFinish를 구분해야 합니다. 특히 도구 출력과 실행 시간은 onToolExecutionEnd에서 다룹니다.
6. 사용자의 허가가 필요한 작업에는 toolApproval을 구성합니다. 다만 승인 대상을 판정하는 정책, 승인 상태의 저장 위치, 사용자 인터페이스, 승인 이후 실행을 이어 가는 방식은 제공된 근거로 확인되지 않았으므로 별도의 애플리케이션 계약으로 설계하고 검증해야 합니다.

근거의 한계

제공된 두 공식 문서는 위 구성 항목을 뒷받침하지만, 승인 상태의 영속성, 중단 후 재개 방식, 모든 우회 실행을 막는 종단 간 보장, 스트리밍 결과의 전체 형태, prepareStep의 완전한 반환 계약은 설명하지 않습니다. 따라서 이러한 동작을 SDK가 자동으로 보장한다고 표현해서는 안 됩니다. 또한 공식 자료는 vercel-ai-sdk 제품에 속하는 선택 가능한 모델 ID를 게시하지 않습니다. 예제의 xai/grok-4.6은 공급자 모델을 지정하는 설정값이며, SDK 제품 자체의 모델 ID가 아닙니다.

모델 제공 범위 안내: 공식 출처는 선택 가능한 모델 ID를 지정하지 않습니다.