기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.
# AG-UI 프로토콜 계약
AG-UI 프로토콜 계약은 Amazon Bedrock AgentCore 런타임에서 agent-to-user 인터페이스 통신을 구현하기 위한 요구 사항을 정의합니다. 이 계약은 AG-UI 에이전트가 구현해야 하는 기술 요구 사항, 엔드포인트 및 통신 패턴을 지정합니다.
예제 코드는 [ AgentCore 런타임에서 AG-UI 서버 배포를 참조하세요](runtime-agui.md).
**Topics**
+ [프로토콜 구현 요구 사항](#agui-protocol-implementation-requirements)
+ [컨테이너 요구 사항](#agui-container-requirements)
+ [경로 요구 사항](#agui-path-requirements)
+ [인증 요구 사항](#agui-authentication-requirements)
+ [오류 처리](#agui-error-handling)
+ [OAuth 인증 응답](#agui-oauth-authentication-responses)
## 프로토콜 구현 요구 사항
AG-UI 에이전트는 다음과 같은 특정 프로토콜 요구 사항을 구현해야 합니다.
+ **전송**: Server-Sent Events(SSE) 또는 WebSocket - SSE는 서버에서 클라이언트로의 단방향 스트리밍을 제공하는 반면, WebSocket은 양방향 실시간 통신을 지원합니다.
+ **세션 관리**: 플랫폼은 세션 격리를 위한 `X-Amzn-Bedrock-AgentCore-Runtime-Session-Id` 헤더를 자동으로 추가합니다.
## 컨테이너 요구 사항
AG-UI 에이전트는 다음 사양을 충족하는 컨테이너화된 애플리케이션으로 배포되어야 합니다.
+ **호스트: ** `0.0.0.0`
+ **포트**: `8080` - AG-UI 에이전트 통신을 위한 표준 포트(HTTP 프로토콜과 동일)
+ **플랫폼**: ARM64 컨테이너 - AWS Amazon Bedrock AgentCore 런타임 환경과의 호환성에 필요합니다.
## 경로 요구 사항
### /호출 - 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 유형을 참조하세요](https://docs.ag-ui.com/sdk/js/core/types).
#### 응답 형식
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 에이전트가 작동하고 요청을 처리할 준비가 되었는지 확인합니다.
#### 응답 형식
에이전트의 상태를 나타내는 상태 코드를 반환합니다.
+ **Content-Type:** `application/json`
+ **HTTP 상태 코드**: 비정상 상태에 `200` 대한 정상적이고 적절한 오류 코드
```
{
"status": "Healthy"
}
```
`status`는 필수이며 `Healthy` 또는 중 하나입니다`HealthyBusy`. 상태가 인 동안 `HealthyBusy`런타임 세션은 활성 상태로 유지됩니다.
선택적 `time_of_last_update` 필드(초 단위의 Unix 타임스탬프)를 포함하여가 `status` 마지막으로 변경된 시기를 보고할 수 있습니다.
**주의**
모든 ping`time_of_last_update`에서 현재 시간으로 설정하지 마십시오. 모든 ping에서 진행되는 타임스탬프는 지속적인 상태 변경 신호를 보내 유휴 세션 제한 시간이 실행되지 않도록 합니다. 그러면 세션은 `MaxLifetime`가 세션 할당량을 소진할 수 있을 때까지 지속됩니다. 필드를 생략하면 플랫폼이 자체적으로 상태 변경을 추적합니다. Bedrock AgentCore SDK를 사용하는 경우 ping 응답이 처리됩니다.
## 인증 요구 사항
AG-UI 에이전트는 여러 인증 메커니즘을 지원합니다.
### OAuth 2.0 베어러 토큰
AG-UI 클라이언트 인증의 경우 요청 헤더에 베어러 토큰을 포함합니다.
```
Authorization: Bearer
X-Amzn-Bedrock-AgentCore-Runtime-Session-Id:
```
### SigV4 인증
Standard AWS SigV4 인증은 프로그래밍 방식 액세스에도 지원됩니다.
## 오류 처리
AG-UI는 스트리밍 전 또는 스트리밍 중에 오류가 발생하는지 여부에 관계없이 모든 오류를 SSE `RUN_ERROR` 이벤트(`Content-Type: text/event-stream`)로 직렬화합니다. 범주는 이벤트와 함께 제공되는 HTTP 상태 코드에서만 다릅니다.
+ **연결 수준 오류**: 요청이 컨테이너에 도달하기 전에 발생합니다(인증, 권한 부여, 검증, 제한, 세션 충돌). `RUN_ERROR` 이벤트는 오류의 실제 HTTP 상태 코드(예: 401, 403 또는 409)와 함께 반환됩니다.
+ **런타임 오류**: 스트림이 시작된 후 에이전트 실행 중에 발생합니다. 만이 범주에 `AGENT_ERROR` 속합니다. 스트림이 이미 시작되었으므로 `RUN_ERROR` 이벤트는 HTTP 200을 반환합니다.
다음 표는 각 런타임 예외를 AG-UI SSE 오류 코드, HTTP 상태 코드 및 메시지에 매핑합니다. 일부 예외는 SSE 오류 코드를 공유하지만 다른 메시지를 반환하므로 별도의 행으로 나열됩니다.
| SSE 오류 코드 | 런타임 예외 | HTTP 오류 코드 | 오류 메시지 |
| --- | --- | --- | --- |
| `UNAUTHORIZED` | UnauthorizedException | 401 | 인증 필요 또는 잘못된 자격 증명 |
| `ACCESS_DENIED` | AccessDeniedException | 403 | 요청된 작업에 대한 권한 부족 |
| `VALIDATION_ERROR` | ValidationException | 400 | 잘못된 요청 데이터 또는 파라미터 |
| `RATE_LIMIT_EXCEEDED` | ThrottlingException | 429 | 클라이언트의 요청이 너무 많음 |
| `SESSION_BUSY` | ConflictException | 409 | 리소스 충돌 - 리소스가 이미 있음 |
| `SESSION_BUSY` | RetryableConflictException | 409 | 세션 작업이 진행 중입니다. 다시 시도하세요. |
| `SERVICE_QUOTA_EXCEEDED` | ServiceQuotaExceededException | 429 | 서비스 할당량 초과 |
| `AGENT_ERROR` | RuntimeClientError | 200 | 실행 중 에이전트 코드 실패 - CloudWatch 로그 확인 |
| `INTERNAL_ERROR` | 기타 예외 | 500 | 요청을 처리하는 동안 내부 오류가 발생했습니다. |
`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](https://datatracker.ietf.org/doc/html/rfc7235) 기준)가 포함됩니다.
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` 헤더를 포함하지 않습니다.