`createAgentUIStreamResponse`

createAgentUIStreamResponse

createAgentUIStreamResponse 함수는 Agent를 실행하고, 그 스트리밍 출력을 UI 메시지 스트림으로 돌린 뒤, 본문이 실시간 스트리밍 UI 메시지 출력인 HTTP Response 객체를 반환해요. 채팅 엔드포인트나 스트리밍 도구 사용 작업처럼 실시간 에이전트 결과를 전달하는 API 라우트를 위해 설계되었어요.

출처: 문서

본문

createAgentUIStreamResponse 함수는 Agent를 실행하고, 그 스트리밍 출력을 UI 메시지 스트림으로 실행시키며, 본문이 실시간 스트리밍 UI 메시지 출력인 HTTP Response 객체를 반환합니다. 이것은 채팅 엔드포인트나 스트리밍 도구 사용 작업과 같은 실시간 에이전트 결과를 전달하는 API 라우트를 위해 설계되었습니다.

Import

import { createAgentUIStreamResponse } from "ai"

사용법 (Usage)

import { ToolLoopAgent, createAgentUIStreamResponse } from 'ai';
__PROVIDER_IMPORT__;

const agent = new ToolLoopAgent({
  model: __MODEL__,
  instructions: 'You are a helpful assistant.',
  tools: { weather: weatherTool, calculator: calculatorTool },
});

export async function POST(request: Request) {
  const { messages } = await request.json();

  // Optional: support cancellation (aborts on disconnect, etc.)
  const abortController = new AbortController();

  return createAgentUIStreamResponse({
    agent,
    uiMessages: messages,
    abortSignal: abortController.signal, // optional
    // experimental_sandbox, // optional: passed through to tool execution
    // ...other UIMessageStreamOptions like sendSources, experimental_transform, etc.
  });
}

Parameters (매개변수)

<PropertiesTable content={[ { name: 'agent', type: 'Agent', isRequired: true, description: '응답을 스트리밍할 에이전트 인스턴스. .stream({ prompt, ... })을 구현하고 tools 속성을 정의해야 합니다.', }, { name: 'uiMessages', type: 'unknown[]', isRequired: true, description: '에이전트에 제공되는 입력 UI 메시지 배열 (예: 사용자 및 assistant 메시지).', }, { name: 'abortSignal', type: 'AbortSignal', isRequired: false, description: '클라이언트 연결 해제 시 등 스트리밍을 취소할 선택적 abort signal. AbortSignal 인스턴스여야 합니다.', }, { name: 'timeout', type: 'number | { totalMs?: number }', isRequired: false, description: '밀리초 단위 타임아웃. 숫자 또는 totalMs 속성을 가진 객체로 지정할 수 있습니다. 지정된 타임아웃보다 길어지면 호출이 중단됩니다. abortSignal과 함께 사용할 수 있습니다.', }, { name: 'experimental_sandbox', type: 'Experimental_SandboxSession', isRequired: false, description: '도구 실행에 전달되는 선택적 실험적 샌드박스 환경. 도구는 실행 컨텍스트에서 접근할 수 있습니다.', }, { name: 'options', type: 'CALL_OPTIONS', isRequired: false, description: '제네릭 매개변수 CALL_OPTIONS가 있는 에이전트를 위한 선택적 에이전트 호출 옵션.', }, { name: 'experimental_transform', type: 'StreamTextTransform | StreamTextTransform[]', isRequired: false, description: '텍스트 출력을 후처리할 선택적 스트림 변환 — 하위 수준 스트리밍 API와 동일합니다.', }, { name: 'onStepEnd', type: 'GenerateTextOnStepEndCallback', isRequired: false, description: '각 에이전트 스텝(LLM/도구 호출)이 완료된 후 호출되는 콜백. 토큰 사용량 추적 또는 중간 스텝 로깅에 유용합니다.', }, { name: 'onStepFinish', type: 'GenerateTextOnStepFinishCallback', isRequired: false, description: '지원 중단됨. onStepEnd를 대신 사용하세요. 이 별칭은 onStepEnd가 제공되지 않을 때의 폴백으로만 사용됩니다.', }, { name: '...UIMessageStreamOptions', type: 'UIMessageStreamOptions', isRequired: false, description: 'sendSources 등과 같은 기타 UI 메시지 출력 옵션.', }, { name: 'headers', type: 'HeadersInit', isRequired: false, description: 'Response 객체에 포함할 선택적 HTTP 헤더.', }, { name: 'status', type: 'number', isRequired: false, description: '선택적 HTTP 상태 코드.', }, { name: 'statusText', type: 'string', isRequired: false, description: '선택적 HTTP 상태 텍스트.', }, { name: 'consumeSseStream', type: '(options: { stream: ReadableStream }) => PromiseLike | void', isRequired: false, description: 'SSE 스트림을 소비할 선택적 함수. 제공되면 이 함수가 SSE 스트림으로 호출되어 소비를 처리합니다.', }, ]} />

Returns (반환값)

본문이 에이전트의 스트리밍 UI 메시지 출력인 Promise<Response>. serverless, Next.js, Express, Hono 또는 edge 런타임 컨텍스트에서 API/서버 핸들러의 반환 값으로 사용하세요.

예제: Next.js API 라우트 핸들러 (Example: Next.js API Route Handler)

import { createAgentUIStreamResponse } from 'ai';
import { MyCustomAgent } from '@/agent/my-custom-agent';

export async function POST(request: Request) {
  const { messages } = await request.json();

  return createAgentUIStreamResponse({
    agent: MyCustomAgent,
    uiMessages: messages,
    // experimental_sandbox, // optional
    sendSources: true, // (optional)
    // headers, status, abortSignal, and other UIMessageStreamOptions also supported
  });
}

작동 방식 (How It Works)

    1. UI 메시지 검증 (UI Message Validation): 에이전트가 지정한 도구와 요구 사항에 따라 들어오는 uiMessages 배열을 검증합니다.
    1. 모델 메시지 변환 (Model Message Conversion): 검증된 UI 메시지를 에이전트용 내부 모델 메시지 형식으로 변환합니다.
    1. 에이전트 출력 스트리밍 (Streaming Agent Output): 에이전트의 .stream({ prompt, ... })을 호출해 청크(스텝/UI 메시지) 스트림을 얻고, experimental_sandbox 같은 옵션을 전달합니다.
    1. HTTP Response 생성 (HTTP Response Creation): 출력 스트림을 클라이언트에 UI 메시지 청크를 스트리밍하는 읽기 가능한 HTTP Response 객체로 감쌉니다.

참고 사항 (Notes)

  • 에이전트는 이 함수와 함께 작동하려면 .stream({ prompt, ... })을 구현하고 tools 속성(비어 있더라도 {})을 정의해야 합니다.
  • 서버 전용 (Server Only): 이 API는 백엔드/서버 측 컨텍스트(API 라우트, edge/serverless/서버 라우트 핸들러 등)에서만 호출해야 합니다. 브라우저용이 아닙니다.
  • 에이전트 도구가 실행 중 실험적 샌드박스 환경이 필요하면 experimental_sandbox를 전달하세요.
  • 고급 시나리오를 위해 추가 옵션(headers, status, UI 스트림 옵션, 변환 등)을 사용할 수 있습니다.
  • 이것은 ReadableStream을 활용하므로, 플랫폼/클라이언트가 HTTP 스트리밍 소비를 지원해야 합니다.

함께 보기 (See Also)

더 알아보기 (Learn more)

전체 사이트맵