AI SDK 연동

Agents SDK는 기본적으로 Responses API 또는 Chat Completions API를 통해 OpenAI 모델과 함께 작동합니다. 하지만 다른 모델을 사용하고 싶다면, Vercel AI SDK가 지원하는 다양한 모델을 이 어댑터를 통해 Agents SDK에 연결할 수 있습니다.

설정

extensions 패키지를 설치하여 AI SDK 어댑터를 설치합니다
Terminal window
```
npm install @openai/agents-extensions
```
Vercel의 AI SDK에서 원하는 모델 패키지를 선택해 설치합니다
Terminal window
```
npm install @ai-sdk/openai
```

에이전트에 연결할 수 있도록 어댑터와 모델을 import합니다

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?');

provider 메타데이터 전달

메시지와 함께 provider 전용 옵션을 보내야 한다면 providerMetadata를 통해 전달하세요. 값은 기본 AI SDK 모델로 직접 전달됩니다. 예를 들어, Agents SDK에서 다음 providerData는

const providerData = {
  anthropic: {
    cacheControl: {
      type: 'ephemeral',
    },
  },
};

다음과 같이 변환됩니다

const providerMetadata = {
  anthropic: {
    cacheControl: {
      type: 'ephemeral',
    },
  },
};

AI SDK 연동을 사용할 때 위와 같이 적용됩니다.

최종 출력 텍스트 정규화

일부 provider는 JSON 코드 펜스 같은 추가 래핑이 포함된 일반 텍스트로 structured outputs를 반환합니다. Agents 런타임이 최종 출력을 검증하기 전에 provider별 정리가 필요하다면, 어댑터 생성 시 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는 비스트리밍 응답에서는 최종 assistant 텍스트에 대해 실행되고, 스트리밍 응답에서는 마지막 response_done 이벤트에서 실행됩니다. 증분 output_text_delta 이벤트는 수정하지 않습니다.

재시도

modelSettings.retry는 AI SDK 기반 모델에서도 동작합니다. 재시도는 기본 OpenAI provider에서만 처리되는 것이 아니라 Agents 런타임에서 구현되기 때문입니다.

즉, 다른 곳에서 사용하는 것과 동일한 재시도 설정을 붙일 수 있습니다.

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는 AI SDK 모델을 어댑트하여 Agent가 해당 모델에서 실행되게 합니다
@openai/agents-extensions/ai-sdk-ui는 스트리밍된 Agents SDK 실행을 어댑트하여 AI SDK UI 라우트가 표준 스트리밍 Response를 반환할 수 있게 합니다

AI SDK 모델 참고 사항

@openai/agents-extensions/ai-sdk 어댑터는 아직 베타이므로, 선택한 provider(특히 규모가 작은 provider)에서 신중히 테스트하는 것이 좋습니다
OpenAI 모델을 사용하는 경우 이 어댑터 대신 기본 OpenAI 모델 provider 사용을 권장합니다
지원되는 AI SDK provider는 specificationVersion v2 또는 v3를 노출해야 합니다. 이전 v1 provider 스타일이 필요하면 examples/ai-sdk-v1의 모듈을 프로젝트로 복사하세요
Deferred Responses 도구 로딩 플로우는 여기서 지원되지 않습니다. 여기에는 toolNamespace(), deferLoading: true가 설정된 함수 도구, toolSearchTool()이 포함됩니다. 도구 검색이 필요하면 OpenAI Responses 모델을 직접 사용하세요. 도구 가이드와 모델 가이드를 참고하세요

AI SDK UI 스트림 헬퍼

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

일반 텍스트 스트리밍 응답용 createAiSdkTextStreamResponse(source, options?)
UIMessageChunk 스트리밍 응답용 createAiSdkUiMessageStreamResponse(source, options?)

두 헬퍼 모두 StreamedRunResult, 스트림 유사 소스 또는 호환 래퍼 객체를 받아 스트리밍 친화 헤더가 포함된 Response를 반환합니다.

UI에서 도구 호출이나 reasoning 파트 같은 구조화된 청크가 필요하면 createAiSdkUiMessageStreamResponse(...)를 사용하세요. 일반 텍스트만 원하면 createAiSdkTextStreamResponse(...)를 사용하세요.

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 앱을 참고하세요.