AI SDK 연동
Agents SDK는 기본적으로 Responses API 또는 Chat Completions API를 통해 OpenAI 모델과 함께 작동합니다. 다른 모델을 사용하려면 Vercel AI SDK가 지원하는 다양한 모델을 이 어댑터를 통해 Agents SDK에서 사용할 수 있습니다.
-
확장 패키지를 설치하여 AI SDK 어댑터를 설치합니다:
터미널 창 npm install @openai/agents-extensions -
Vercel AI SDK에서 원하는 모델 패키지를 선택하고 설치합니다:
터미널 창 npm install @ai-sdk/openai -
에이전트에 연결할 어댑터와 모델을 가져옵니다:
어댑터 가져오기 import { openai } from '@ai-sdk/openai';import { aisdk } from '@openai/agents-extensions/ai-sdk'; -
에이전트에서 사용할 모델 인스턴스를 초기화합니다:
모델 생성 import { openai } from '@ai-sdk/openai';import { aisdk } from '@openai/agents-extensions/ai-sdk';const model = aisdk(openai('gpt-5.4'));
코드 예제
섹션 제목: “코드 예제”import { Agent, run } from '@openai/agents';
// Import the model package you installedimport { openai } from '@ai-sdk/openai';
// Import the adapterimport { aisdk } from '@openai/agents-extensions/ai-sdk';
// Create a model instance to be used by the agentconst model = aisdk(openai('gpt-5.4'));
// Create an agent with the modelconst agent = new Agent({ name: 'My Agent', instructions: 'You are a helpful assistant.', model,});
// Run the agent with the new modelrun(agent, 'What is the capital of Germany?');제공자 메타데이터 전달
섹션 제목: “제공자 메타데이터 전달”메시지와 함께 제공자별 옵션을 보내야 한다면 providerMetadata를 통해 전달합니다. 이 값은 기반 AI SDK 모델에 직접 전달됩니다. 예를 들어, Agents SDK의 다음 providerData는
const providerData = { anthropic: { cacheControl: { type: 'ephemeral', }, },};AI SDK 연동을 사용할 때 다음과 같이 변환됩니다:
const providerMetadata = { anthropic: { cacheControl: { type: 'ephemeral', }, },};프롬프트 캐시 보존
섹션 제목: “프롬프트 캐시 보존”제공자가 openai.responses인 AI SDK 모델이 AI SDK 사양 버전 v3 또는 v4를 사용하는 경우, 어댑터는 스트리밍 및 비스트리밍 요청에 modelSettings.promptCacheRetention을 전달합니다. Agents SDK 값인 'in-memory'는 AI SDK 제공자 값인 'in_memory'로 매핑되며, '24h'와 null은 그대로 전달됩니다.
AI SDK v2 모델은 이 옵션을 지원하지 않으므로, 이 옵션이 설정되어 있으면 어댑터는 모델 요청을 보내기 전에 UserError를 발생시킵니다. 명시적으로 지정한 modelSettings.providerData.providerOptions.openai.promptCacheRetention 값은 modelSettings.promptCacheRetention보다 우선하며, 어댑터는 이 설정을 다른 AI SDK 제공자에게 전달하지 않습니다.
이 설정은 기존 최대 보존 정책을 제어하며 일부 모델에서만 지원됩니다. 현재 모델 호환성과 새로운 캐시 수명 제어 기능은 프롬프트 캐시 보존을 참고하세요.
PDF 파일 입력
섹션 제목: “PDF 파일 입력”AI SDK 어댑터는 Agents SDK의 input_file 콘텐츠를 AI SDK v2, v3, v4 모델이 요구하는 파일 파트 형식으로 변환합니다. PDF는 다음과 같은 형태로 제공할 수 있습니다:
data:application/pdf;base64,...와 같은 base64 데이터 URL.pdf파일 이름 또는providerData.mediaType이 함께 제공되는 비어 있지 않은 원문 base64 데이터.pdf경로 또는providerData.mediaType이 있는 공개 HTTP(S) URL
파일 이름이나 URL 경로가 .pdf로 끝나면 어댑터는 미디어 유형을 application/pdf로 추론합니다. 그렇지 않으면 providerData: { mediaType: 'application/pdf' }를 명시적으로 설정하세요. 어댑터는 공개 URL의 파일을 다운로드하지 않고 URL을 AI SDK 모델에 직접 전달하므로, 선택한 제공자와 모델이 URL 기반 PDF 파일 파트를 지원해야 합니다. 지원하지 않는 경우에는 base64 표현을 사용하세요. AI SDK 어댑터는 OpenAI 파일 ID를 지원하지 않습니다. 파일 데이터나 공개 URL을 전달하거나 OpenAI Responses 모델을 직접 사용하세요.
최종 출력 텍스트 정규화
섹션 제목: “최종 출력 텍스트 정규화”일부 제공자는 구조화된 출력을 JSON 코드 펜스와 같은 추가 래핑이 포함된 일반 텍스트로 반환합니다. 에이전트 런타임이 최종 출력을 검증하기 전에 제공자별로 텍스트를 정리해야 한다면, 어댑터를 생성할 때 transformOutputText를 전달하세요:
import { openai } from '@ai-sdk/openai';import { aisdk } from '@openai/agents-extensions/ai-sdk';
const model = aisdk(openai('gpt-5.4'), { transformOutputText(text) { return text.match(/```(?:json)?\s*([\s\S]*?)\s*```/)?.[1]?.trim() ?? text; },});transformOutputText는 비스트리밍 응답에서는 최종 확정된 어시스턴트 텍스트에 대해 실행되고, 스트리밍 응답에서는 마지막 response_done 이벤트에서 실행됩니다. 점진적으로 전달되는 output_text_delta 이벤트는 수정하지 않습니다.
재시도
섹션 제목: “재시도”재시도는 기본 OpenAI 제공자에만 구현된 것이 아니라 에이전트 런타임에서 구현되므로, modelSettings.retry는 AI SDK 기반 모델에서도 작동합니다.
따라서 다른 곳에서 사용하는 것과 동일한 재시도 설정을 적용할 수 있습니다:
Agent,Runner또는 둘 다에modelSettings.retry를 설정합니다.networkError(),httpStatus([...]),providerSuggested()등의retryPolicies를 조합합니다.providerSuggested()는 래핑된 AI SDK 모델이 어댑터를 통해 재시도 권고를 전달할 수 있을 때만 도움이 된다는 점에 유의하세요.
aisdk(openai(...))를 사용하는 전체 코드 예제는 examples/ai-sdk/retry.ts를 참고하세요. 스트리밍과 상태를 유지하는 후속 요청의 안전성 제약을 포함한 재시도 API 자체에 대한 내용은 모델 가이드를 참고하세요.
적절한 연동 선택
섹션 제목: “적절한 연동 선택”@openai/agents-extensions에는 두 가지 관련 연동이 있습니다:
@openai/agents-extensions/ai-sdk는Agent가 AI SDK 모델에서 실행될 수 있도록 모델을 변환합니다.@openai/agents-extensions/ai-sdk-ui는 AI SDK UI 라우트가 표준 스트리밍Response를 반환할 수 있도록 Agents SDK의 스트리밍 실행을 변환합니다.
AI SDK 모델 관련 참고 사항
섹션 제목: “AI SDK 모델 관련 참고 사항”@openai/agents-extensions/ai-sdk어댑터는 아직 베타 버전이므로, 선택한 제공자, 특히 소규모 제공자와 함께 사용할 때는 신중하게 테스트하는 것이 좋습니다.- OpenAI 모델을 사용한다면 이 어댑터 대신 기본 OpenAI 모델 제공자를 사용하는 것이 좋습니다.
- 지원되는 AI SDK 제공자는
specificationVersion으로v2,v3또는v4를 노출해야 합니다. 기존 v1 제공자 코드 예제는 더 이상 제공되지 않습니다. 지원되는 제공자 인터페이스를 사용하는 코드 예제는 examples/ai-sdk를 참고하세요. - 컴퓨터 도구를 이 어댑터를 통해 사용하려면 디스플레이 메타데이터가 필요합니다. 도구에
environment와dimensions메타데이터가 모두 포함되어 있는지 확인하세요. - Responses의 지연 도구 로딩 흐름은 여기서 지원되지 않습니다. 여기에는
toolNamespace(),deferLoading: true가 설정된 함수 도구,toolSearchTool()이 포함됩니다. 도구 검색이 필요하면 OpenAI Responses 모델을 직접 사용하세요. 도구 및 모델 가이드를 참고하세요. - AI SDK 모델 어댑터는 프로그래밍 방식 도구 호출을 지원하지 않습니다.
programmaticToolCallingTool(),allowedCallers에'programmatic'이 포함된 도구, 프로그래밍 방식 도구 호출 이력 항목, Responses의outputSchema를 거부합니다. 이러한 기능을 사용하려면 OpenAI Responses 모델을 직접 사용하세요.
이미지 도구 출력
섹션 제목: “이미지 도구 출력”어댑터는 원격 URL, base64 데이터, OpenAI 파일 ID를 포함하여 함수 도구가 반환하는 ToolOutputImage 값을 보존합니다. AI SDK v2 모델은 media 파트를 받습니다. AI SDK v3 모델은 image-url, image-data 또는 image-file-id 파트를 받습니다. AI SDK v4 모델은 데이터가 URL, 인라인 데이터 또는 파일 ID에 대한 제공자 참조로 표현되는 file 파트를 받습니다. 이를 통해 지원되는 각 모델 버전이 원래 이미지 표현을 사용할 수 있습니다.
전체 코드 예제는 examples/ai-sdk/image-tool-output.ts를 참고하세요.
AI SDK UI 스트림 헬퍼
섹션 제목: “AI SDK UI 스트림 헬퍼”@openai/agents-extensions/ai-sdk-ui는 Agents SDK 스트림을 AI SDK UI 라우트에 연결하기 위한 응답 헬퍼를 제공합니다:
createAiSdkTextStreamResponse(source, options?): 일반 텍스트 스트리밍 응답용createAiSdkUiMessageStream(source): 저수준ReadableStream<UIMessageChunk>용createAiSdkUiMessageStreamResponse(source, options?):UIMessageChunk스트리밍 응답용
이 헬퍼는 StreamedRunResult, 스트림과 유사한 소스 또는 호환되는 래퍼 객체를 받습니다. 응답 헬퍼는 스트리밍에 적합한 헤더가 포함된 Response를 반환합니다.
라우트에서 AI SDK 응답을 직접 반환해야 한다면 createAiSdkUiMessageStreamResponse(...)를 사용하세요. 유지 관리되는 Agents SDK에서 AI SDK UIMessageChunk로의 변환 기능을 활용하면서 응답 또는 렌더링 계층을 직접 제어하려면 createAiSdkUiMessageStream(...)를 사용하세요. 일반 텍스트만 필요하다면 createAiSdkTextStreamResponse(...)를 사용하세요.
AI SDK 모델 어댑터는 프로그래밍 방식 도구 호출 흐름을 시작할 수 없지만, UI 스트림 헬퍼는 이 기능을 사용하는 OpenAI Responses 스트리밍 실행을 래핑할 수 있습니다. 프로그램 항목은 programmatic_tool_calling 도구 입력으로 출력되며, 해당 프로그램 결과는 program_output 도구 출력으로 출력됩니다.
응답 헬퍼는 options를 통해 선택적 응답 설정도 받습니다:
headers: 스트리밍 응답에 병합할 추가 응답 헤더status: 반환되는Response의 HTTP 상태 코드statusText: 반환되는Response의 HTTP 상태 텍스트
저수준 UI 메시지 스트림 예제:
import { Agent, run } from '@openai/agents';import { createAiSdkUiMessageStream } from '@openai/agents-extensions/ai-sdk-ui';
const agent = new Agent({ name: 'Assistant', instructions: 'Reply with a short answer.',});
export async function createStream(): Promise< ReturnType<typeof createAiSdkUiMessageStream>> { const stream = await run(agent, 'Hello there.', { stream: true }); return createAiSdkUiMessageStream(stream);}UI 메시지 스트리밍을 위한 Next.js 라우트 예제:
import { Agent, run } from '@openai/agents';import { createAiSdkUiMessageStreamResponse } from '@openai/agents-extensions/ai-sdk-ui';
const agent = new Agent({ name: 'Assistant', instructions: 'Reply with a short answer.',});
export async function POST() { const stream = await run(agent, 'Hello there.', { stream: true }); return createAiSdkUiMessageStreamResponse(stream);}텍스트 전용 스트리밍을 위한 Next.js 라우트 예제:
import { Agent, run } from '@openai/agents';import { createAiSdkTextStreamResponse } from '@openai/agents-extensions/ai-sdk-ui';
const agent = new Agent({ name: 'Assistant', instructions: 'Reply with a short answer.',});
export async function POST() { const stream = await run(agent, 'Hello there.', { stream: true }); return createAiSdkTextStreamResponse(stream);}전체 사용 흐름은 이 저장소의 examples/ai-sdk-ui 앱을 참고하세요.