翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。
# 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 エージェントは、以下の特定のプロトコル要件を実装する必要があります。
+ **トランスポート** : サーバー送信イベント (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) としてレスポンスをストリーミングします
#### ユースケース
呼び出しエンドポイントには、いくつかの重要な目的があります。
+ チャットレスポンスのストリーミング
+ エージェントのステータスと思考ステップ
+ ツールの呼び出しと結果
#### リクエストの形式
Amazon Bedrock AgentCore は、検証なしでリクエストペイロードをコンテナに直接渡します。AG-UI-compliantするには、リクエストが `RunAgentInput`形式に従う必要があります。コンテナの実装によって、必須のフィールドと検証エラーの処理方法が決まります。
AG-UI-compliantのエージェントは JSON `RunAgentInput` ペイロードを想定しています。例:
```
{
"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) を使用しますが、メッセージによって区別されます。サービスがそのセッションをプロビジョニングまたは破棄している間に 2 番目のオペレーションがセッションに達すると、サービスは `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"}
```
session-busy エラーの例 (再試行可能な競合):
```
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`ヘッダーは含まれません。