`pipeAgentUIStreamToResponse`
pipeAgentUIStreamToResponse
pipeAgentUIStreamToResponse 함수는 Agent를 실행하고 결과적인 UI 메시지 출력을 Node.js ServerResponse 객체로 직접 스트리밍합니다. Express, Hono 또는 커스텀 Node 서버 같은 Node.js 기반 프레임워크에서 실시간 스트리밍 API 엔드포인트(채팅, 툴 사용 등)를 구축하는 데 이상적입니다.
출처: 문서
본문
Import
import { pipeAgentUIStreamToResponse } from "ai"
Usage (사용법)
import { pipeAgentUIStreamToResponse } from 'ai';
import { MyAgent } from './agent';
export async function handler(req, res) {
const { messages } = JSON.parse(req.body);
await pipeAgentUIStreamToResponse({
response: res, // Node.js ServerResponse
agent: MyAgent,
uiMessages: messages, // Required: array of input UI messages
// abortSignal: optional AbortSignal for cancellation
// experimental_sandbox: optional experimental sandbox passed through to tool execution
// status: 200,
// headers: { ... },
// ...other optional UI message stream options
});
}
Parameters (파라미터)
response:ServerResponse(필수) — UI 메시지 스트림 출력을 파이프할 Node.jsServerResponse객체입니다.agent:Agent(필수) —.stream({ prompt, ... })을 구현하고tools속성을 정의하는 에이전트 인스턴스입니다.uiMessages:unknown[](필수) — 에이전트로 보낸 입력 UI 메시지 배열입니다 (user/assistant 메시지 객체 등).abortSignal:AbortSignal(선택) — 스트리밍을 취소하는 선택적 abort 신호입니다 (예: 클라이언트 연결 해제 시). 예를 들어AbortController에서 가져온AbortSignal을 제공하세요.timeout:number | { totalMs?: number }(선택) — 밀리초 단위 타임아웃입니다. 숫자 또는totalMs속성을 가진 객체로 지정할 수 있습니다. 지정된 타임아웃보다 오래 걸리면 호출이 중단됩니다.abortSignal과 함께 사용할 수 있습니다.experimental_sandbox:Experimental_SandboxSession(선택) — 툴 실행에 전달되는 선택적 실험적 샌드박스 환경입니다. 툴은 실행 컨텍스트에서 접근할 수 있습니다.options:CALL_OPTIONS(선택) —CALL_OPTIONS제네릭 파라미터로 구성된 에이전트를 위한 선택적 에이전트 호출 옵션입니다.experimental_transform:StreamTextTransform | StreamTextTransform[](선택) — 에이전트 출력에 적용되는 선택적 스트림 텍스트 변환입니다.onStepEnd:GenerateTextOnStepEndCallback(선택) — 각 에이전트 스텝(LLM/툴 호출)이 완료된 후 호출되는 콜백입니다. 토큰 사용량, 스텝별 성능 추적, 중간 스텝 로깅에 유용합니다.onStepFinish:GenerateTextOnStepFinishCallback(선택) — deprecated 되었습니다.onStepEnd를 사용하세요. 이 별칭은onStepEnd가 제공되지 않을 때의 폴백으로만 사용됩니다....UIMessageStreamResponseInit & UIMessageStreamOptions:object(선택) — 스트리밍 헤더, 상태, SSE 스트림 구성 및 추가 UI 메시지 스트림 제어 옵션입니다.
Returns (반환값)
Promise<void>를 반환합니다. UI 메시지 스트림이 제공된 ServerResponse로 완전히 전송되면 함수가 완료됩니다.
Example: Express Route Handler (Express 라우트 핸들러 예제)
import { pipeAgentUIStreamToResponse } from 'ai';
import { openaiWebSearchAgent } from './openai-web-search-agent';
app.post('/chat', async (req, res) => {
// Use req.body.messages as input UI messages
await pipeAgentUIStreamToResponse({
response: res,
agent: openaiWebSearchAgent,
uiMessages: req.body.messages,
// experimental_sandbox, // optional
// abortSignal: yourController.signal
// status: 200,
// headers: { ... },
// ...more options
});
});
How It Works (동작 방식)
- 에이전트 실행: 제공된 UI 메시지와 옵션으로 에이전트의
.stream메서드를 호출합니다. 필요하면 모델 메시지로 변환하고experimental_sandbox같은 옵션을 전달합니다. - UI 메시지 출력 스트리밍: 에이전트 출력을 UI 메시지 스트림으로
ServerResponse에 파이프하며 스트리밍 HTTP 응답(적절한 헤더 포함)으로 데이터를 보냅니다. - Abort 신호 처리:
abortSignal이 제공되면 신호가 트리거되는 즉시(예: 클라이언트 연결 해제) 스트리밍이 취소됩니다. - 응답 없음:
Response를 반환하는 Edge/serverless API와 달리 이 함수는 바이트를ServerResponse에 직접 쓰며 응답 객체를 반환하지 않습니다.
Notes (참고)
- Abort 처리: 최상의 견고성을 위해
AbortSignal(예: Express/Hono 클라이언트 연결 해제에 연결)을 사용하여 에이전트 계산과 스트리밍을 빠르게 취소하세요. - Node.js 전용: Node.js
ServerResponse객체에서만 동작합니다 (예: Express, Hono의 node 어댑터). Edge/serverless/webResponseAPI에서는 동작하지 않습니다. - 스트리밍 지원: 전체 효과를 보려면 클라이언트(및 모든 프록시)가 스트리밍 HTTP 응답을 올바르게 지원하는지 확인하세요.
- 파라미터 이름: 입력 메시지 속성은 SDK 에이전트 유틸리티와 일관성을 위해
uiMessages입니다(messages아님). - 에이전트 툴이 실행 중 실험적 샌드박스 환경이 필요할 때
experimental_sandbox를 전달하세요.