AI SDK 연동

기본적으로 Agents SDK는 Responses API 또는 Chat Completions API를 통해 OpenAI 모델과 함께 작동합니다. 그러나 다른 모델을 사용하려는 경우 Vercel AI SDK에서 지원하는 다양한 모델을 이 어댑터를 통해 Agents SDK에 연동할 수 있습니다.

설정

확장 패키지를 설치하여 AI SDK 어댑터를 설치합니다.
Terminal window
```
npm install @openai/agents-extensions
```
Vercel의 AI SDK에서 원하는 모델 패키지를 선택하여 설치합니다.
Terminal window
```
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 installed
import { openai } from '@ai-sdk/openai';

// Import the adapter
import { aisdk } from '@openai/agents-extensions/ai-sdk';

// Create a model instance to be used by the agent
const model = aisdk(openai('gpt-5.4'));

// Create an agent with the model
const agent = new Agent({
  name: 'My Agent',
  instructions: 'You are a helpful assistant.',
  model,
});

// Run the agent with the new model
run(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',
    },
  },
};

최종 출력 텍스트 정규화

일부 공급자는 JSON 코드 펜스와 같은 추가 래핑이 포함된 일반 텍스트로 structured outputs을 반환합니다. Agents 런타임에서 최종 출력을 검증하기 전에 공급자별 정리가 필요하다면 어댑터를 생성할 때 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 이벤트는 수정하지 않습니다.

재시도

modelSettings.retry는 기본 OpenAI 공급자뿐만 아니라 Agents 런타임에서 재시도를 구현하므로 AI SDK 기반 모델에서도 작동합니다.

따라서 다른 곳에서 사용하는 것과 동일한 재시도 설정을 적용할 수 있습니다.

Agent, Runner 또는 둘 다에 modelSettings.retry를 설정합니다.
networkError(), httpStatus([...]), providerSuggested()와 같은 retryPolicies를 조합합니다.
래핑된 AI SDK 모델이 어댑터를 통해 재시도 권고를 제공할 수 있는 경우에만 providerSuggested()가 유용하다는 점에 유의하세요.

aisdk(openai(...))를 사용하는 전체 예제는 examples/ai-sdk/retry.ts를 참고하세요. 스트리밍 및 상태 유지 후속 요청의 안전 경계를 비롯한 재시도 API 자체에 관한 내용은 모델을 참고하세요.

적합한 연동 선택

@openai/agents-extensions에는 서로 관련된 두 가지 연동이 있습니다.

@openai/agents-extensions/ai-sdk는 AI SDK 모델을 조정하여 Agent가 해당 모델에서 실행될 수 있게 합니다.
@openai/agents-extensions/ai-sdk-ui는 스트리밍되는 Agents SDK 실행을 조정하여 AI SDK UI 라우트가 표준 스트리밍 Response를 반환할 수 있게 합니다.

AI SDK 모델 참고 사항

@openai/agents-extensions/ai-sdk 어댑터는 아직 베타이므로, 선택한 공급자와 함께 신중하게 테스트하는 것이 좋습니다. 특히 규모가 작은 공급자의 경우 더욱 중요합니다.
OpenAI 모델을 사용하는 경우 이 어댑터 대신 기본 OpenAI 모델 공급자를 사용하는 것이 좋습니다.
지원되는 AI SDK 공급자는 specificationVersion v2, v3 또는 v4를 노출해야 합니다. 이전 v1 공급자 방식이 필요하다면 examples/ai-sdk-v1의 모듈을 프로젝트에 복사하세요.
이 어댑터를 통해 컴퓨터 도구를 사용할 때는 디스플레이 메타데이터가 필요합니다. 도구에 environment 및 dimensions 메타데이터가 모두 포함되어 있는지 확인하세요.
지연된 Responses 도구 로딩 흐름은 여기에서 지원되지 않습니다. 여기에는 toolNamespace(), deferLoading: true가 설정된 함수 도구, toolSearchTool()이 포함됩니다. 도구 검색이 필요한 경우 OpenAI Responses 모델을 직접 사용하세요. 도구 및 모델을 참고하세요.
AI SDK 모델 어댑터는 프로그래매틱 도구 호출(Programmatic Tool Calling)을 지원하지 않습니다. programmaticToolCallingTool(), allowedCallers에 'programmatic'이 포함된 도구, Programmatic Tool Calling 기록 항목, 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 스트림 헬퍼

@openai/agents-extensions/ai-sdk-ui는 Agents SDK 스트림을 AI SDK UI 라우트에 연결하기 위한 응답 헬퍼를 제공합니다.

일반 텍스트 스트리밍 응답을 위한 createAiSdkTextStreamResponse(source, options?)
저수준 ReadableStream<UIMessageChunk>을 위한 createAiSdkUiMessageStream(source)
UIMessageChunk 스트리밍 응답을 위한 createAiSdkUiMessageStreamResponse(source, options?)

이러한 헬퍼는 StreamedRunResult, 스트림 유사 소스 또는 호환되는 래퍼 객체를 허용합니다. 응답 헬퍼는 스트리밍에 적합한 헤더가 포함된 Response를 반환합니다.

라우트에서 AI SDK 응답을 직접 반환해야 하는 경우 createAiSdkUiMessageStreamResponse(...)를 사용하세요. 유지 관리되는 Agents SDK에서 AI SDK UIMessageChunk로의 변환을 계속 사용하면서 응답 또는 렌더링 계층을 직접 제어하려면 createAiSdkUiMessageStream(...)을 사용하세요. 일반 텍스트만 필요한 경우 createAiSdkTextStreamResponse(...)를 사용하세요.

AI SDK 모델 어댑터가 해당 흐름을 시작할 수는 없지만, UI 스트림 헬퍼는 Programmatic Tool Calling을 사용하는 스트리밍 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() {
  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 앱을 참고하세요.