기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

AG-UI 프로토콜 계약

AG-UI 프로토콜 계약은 Amazon Bedrock AgentCore 런타임에서 agent-to-user 인터페이스 통신을 구현하기 위한 요구 사항을 정의합니다. 이 계약은 AG-UI 에이전트가 구현해야 하는 기술 요구 사항, 엔드포인트 및 통신 패턴을 지정합니다.

예제 코드는 AgentCore 런타임에서 AG-UI 서버 배포를 참조하세요.

프로토콜 구현 요구 사항

AG-UI 에이전트는 다음과 같은 특정 프로토콜 요구 사항을 구현해야 합니다.

컨테이너 요구 사항

AG-UI 에이전트는 다음 사양을 충족하는 컨테이너화된 애플리케이션으로 배포되어야 합니다.

경로 요구 사항

/호출 - POST

용도

사용자 요청을 수신하고 응답을 SSE(Server-Sent Events)로 스트리밍합니다.

사용 사례

호출 엔드포인트는 다음과 같은 몇 가지 주요 용도로 사용됩니다.

요청 형식

Amazon Bedrock AgentCore는 검증 없이 요청 페이로드를 컨테이너에 직접 전달합니다. AG-UI-compliant하려면 요청이 RunAgentInput 형식을 따라야 합니다. 컨테이너 구현에 따라 필요한 필드와 검증 오류 처리 방법이 결정됩니다.

AG-UI-compliant 에이전트는 RunAgentInput JSON 페이로드를 예상합니다. 예제:

{
  "threadId": "thread-123",
  "runId": "run-456",
  "messages": [{"id": "msg-1", "role": "user", "content": "Hello, agent!"}],
  "tools": [],
  "context": [],
  "state": {},
  "forwardedProps": {}
}

전체 RunAgentInput 스키마 및 메시지 형식 세부 정보는 AG-UI 유형을 참조하세요.

응답 형식

AG-UI 에이전트는 SSE 형식의 이벤트 스트림으로 응답합니다.

Content-Type: text/event-stream

data: {"type":"RUN_STARTED","threadId":"thread-123","runId":"run-456"}

data: {"type":"TEXT_MESSAGE_START","messageId":"msg-789","role":"assistant"}

data: {"type":"TEXT_MESSAGE_CONTENT","messageId":"msg-789","delta":"Processing your request"}

data: {"type":"TOOL_CALL_START","toolCallId":"tool-001","toolCallName":"search","parentMessageId":"msg-789"}

data: {"type":"TOOL_CALL_RESULT","messageId":"msg-789","toolCallId":"tool-001","content":"Search completed"}

data: {"type":"TEXT_MESSAGE_END","messageId":"msg-789"}

data: {"type":"RUN_FINISHED","threadId":"thread-123","runId":"run-456"}

/ws - WebSocket

용도

클라이언트와 에이전트 간의 양방향 실시간 통신 제공

사용 사례

WebSocket 엔드포인트는 다음과 같은 몇 가지 주요 용도로 사용됩니다.

/ping - GET

용도

AG-UI 에이전트가 작동하고 요청을 처리할 준비가 되었는지 확인합니다.

응답 형식

에이전트의 상태를 나타내는 상태 코드를 반환합니다.

{
  "status": "Healthy"
}

status는 필수이며 Healthy 또는 중 하나입니다HealthyBusy. 상태가 인 동안 HealthyBusy런타임 세션은 활성 상태로 유지됩니다.

선택적 time_of_last_update 필드(초 단위의 Unix 타임스탬프)를 포함하여가 status 마지막으로 변경된 시기를 보고할 수 있습니다.

인증 요구 사항

AG-UI 에이전트는 여러 인증 메커니즘을 지원합니다.

OAuth 2.0 베어러 토큰

AG-UI 클라이언트 인증의 경우 요청 헤더에 베어러 토큰을 포함합니다.

Authorization: Bearer <oauth-token>
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id: <session-id>

SigV4 인증

Standard AWS SigV4 인증은 프로그래밍 방식 액세스에도 지원됩니다.

오류 처리

AG-UI는 스트리밍 전 또는 스트리밍 중에 오류가 발생하는지 여부에 관계없이 모든 오류를 SSE RUN_ERROR 이벤트(Content-Type: text/event-stream)로 직렬화합니다. 범주는 이벤트와 함께 제공되는 HTTP 상태 코드에서만 다릅니다.

다음 표는 각 런타임 예외를 AG-UI SSE 오류 코드, HTTP 상태 코드 및 메시지에 매핑합니다. 일부 예외는 SSE 오류 코드를 공유하지만 다른 메시지를 반환하므로 별도의 행으로 나열됩니다.

ConflictException 및는 RetryableConflictException 모두 SESSION_BUSY SSE 오류 코드(HTTP 409)를 사용하지만 메시지로 구분됩니다. 서비스가 세션을 프로비저닝하거나 해제하는 동안 두 번째 작업이 세션에 도달하면 서비스는 RetryableConflictException (Session operation in progress, please retry)를 반환합니다. 일시적이며 재시도할 수 있습니다. AG-UI 클라이언트는 자동으로 재시도하지 않으므로 짧은 지수 백오프로 재시도합니다.

런타임 오류(에이전트 실패) 예:

HTTP/1.1 200 OK
Content-Type: text/event-stream
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

data: {"type":"RUN_ERROR","code":"AGENT_ERROR","message":"Agent execution failed"}

세션 사용 중 오류(재시도 가능한 충돌) 예:

HTTP/1.1 409 Conflict
Content-Type: text/event-stream
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

data: {"type":"RUN_ERROR","code":"SESSION_BUSY","message":"Session operation in progress, please retry"}

OAuth 인증 응답

OAuth로 구성된 에이전트는 표준 HTTP 상태 코드와 함께 인증 오류를 반환합니다. 응답에는 GetRuntimeProtectedResourceMetadata API를 통한 OAuth 검색을 위한 WWW-Authenticate 헤더(RFC 7235 기준)가 포함됩니다.

OAuth 인증 오류 예:

HTTP/1.1 401 Unauthorized
Content-Type: text/event-stream
WWW-Authenticate: Bearer resource_metadata="https://bedrock-agentcore.{region}.amazonaws.com/runtimes/{ESCAPED_ARN}/invocations/.well-known/oauth-protected-resource?qualifier={QUALIFIER}"
x-amzn-requestid: 12345678-1234-1234-1234-123456789012

data: {"type":"RUN_ERROR","code":"UNAUTHORIZED","message":"Authentication required"}

SigV4-configured 에이전트는 ACCESS_DENIED 오류와 함께 HTTP 403을 반환하며 WWW-Authenticate 헤더를 포함하지 않습니다.