

翻訳は機械翻訳により提供されています。提供された翻訳内容と英語版の間で齟齬、不一致または矛盾がある場合、英語版が優先します。

# Amazon Bedrock AgentCore ランタイムにカスタムヘッダーを渡す

カスタムヘッダーを使用すると、メインリクエストペイロードを整理することなく、アプリケーションからエージェントコードにコンテキスト情報を直接渡すことができます。などのウェブフック署名、、 などの API キー、トレースコンテキスト、セッション識別子など`X-Custom-Signature`、[制限付きヘッダーリストに含まれていない有効な HTTP ヘッダー](#runtime-header-restrictions)を渡すことができます。 `X-Api-Key`エージェントがカスタム JWT オーソライザーで設定されている場合、JWT ベースの認証の `Authorization`ヘッダーを渡すこともできます。プレフィックスが のヘッダーは、下位互換性のために`X-Amzn-Bedrock-AgentCore-Runtime-Custom-`引き続きサポートされます。ランタイムごとに最大 20 個のヘッダーを設定できます。各ヘッダー値は 4KB に制限されています。

Amazon Bedrock AgentCore Runtime では、ヘッダーが次の基準を満たしていれば、リクエスト内のヘッダーをエージェントコードに渡すことができます。
+ ヘッダー名は有効な HTTP ヘッダー (英数字、ハイフン、アンダースコア) であり、[制限付きヘッダー](#runtime-header-restrictions)リストにはありません。
+ で始まるヘッダー`x-amz-`は使用できません (これらは AWS SigV4 署名用に予約されています）。
+ で始まるヘッダー`x-amzn-`は、プレフィックスが のヘッダーを除き、許可されません`X-Amzn-Bedrock-AgentCore-Runtime-Custom-`。
+ `Authorization` ヘッダーでは、OAuth ベースのインバウンドアクセス`customJWTAuthorizer`用の でエージェントのランタイムを設定する必要があります。
+ ヘッダー値は 4KB 以下です。
+ ランタイムごとに最大 20 個のヘッダーを設定できます。
+ ヘッダー名では大文字と小文字が区別されず、重複 (大文字と小文字が区別されない比較) は許可されません。

## 制限付きヘッダー
<a name="runtime-header-restrictions"></a>

セキュリティを維持し、機密情報の漏洩を防ぐために、以下のヘッダーは制限されており、伝播用に設定することはできません。


| カテゴリ | ヘッダー | 
| --- | --- | 
| 認証と認可 | Proxy-Authorization、WWW-Authenticate | 
| コンテンツネゴシエーション | Accept、Accept-Charset、Accept-Encoding、Accept-Language、Content-Type、Content-Length、Content-Encoding、Content-Language、Content-Location、Content-Range | 
| キャッシュ | キャッシュコントロール、ETag、期限切れ、If-Match、If-Modified-Since、If-None-Match、If-Range、If-Unmodified-Since、Last-Modified、Pragma、Vary | 
| 接続管理 | 接続、キープアライブ、プロキシ接続、アップグレード | 
| リクエストコンテキスト | Host、User-Agent、Referer、From | 
| 範囲/転送 | 範囲、Accept-Ranges、Transfer-Encoding、TE、トレーラー | 
| サーバー情報 | サーバー、日付、場所、再試行後 | 
| cookie | Set-Cookie、Cookie | 
| セキュリティ | Content-Security-Policy、Content-Security-Policy-Report-Only、Strict-Transport-Security、X-Content-Type-Options、X-Frame-Options、X-XSS-Protection、Referrer-Policy、Permissions-Policy、Cross-Origin-Embedder-Policy、Cross-Origin-Opener-Policy、Cross-Origin-Resource-Policy | 
| CORS | Access-Control-Allow-Origin、Access-Control-Allow-Methods、Access-Control-Allow-Headers、Access-Control-Allow-Credentials、Access-Control-Expose-Headers、Access-Control-Max-Age、Access-Control-Request-Method、Access-Control-Request-Headers、Origin | 
| クライアントヒント | Accept-CH、Accept-CH-Lifetime、DPR、Width、Viewport-Width、Downlink、ECT、RTT、Save-Data | 
| 実験的/提案 | Clear-Site-Data、Feature-Policy、Expect-CT、Public-Key-Pins、Public-Key-Pins-Report-Only | 
| プロキシ | Via、Forwarded、X-Forwarded-For、X-Forwarded-Host、X-Forwarded-Proto、X-Real-IP、X-Requested-With、X-CSRF-Token | 
| IP スプーフィング/URL 操作 | True-Client-IP、X-Client-IP、X-Cluster-Client-IP、X-Originating-IP、X-Source-IP、X-Original-URL、X-Original-Host、X-Rewrite-URL | 
| CDN / プロキシ | CF-Ray、CF-Connecting-IP、X-Amz-Cf-Id、X-Cache、X-Served-By | 
| HTTP/2 擬似ヘッダー | :method、:path、:scheme、:authority、:status | 
| サーバープッシュ | Link | 
| WebSocket | Sec-WebSocket-Key、Sec-WebSocket-Accept、Sec-WebSocket-Version、Sec-WebSocket-Protocol、Sec-WebSocket-Extensions | 

上記の制限付きヘッダーに加えて:
+ で始まるすべてのヘッダー`x-amz-`が制限されます (例: `x-amz-security-token` 、`x-amz-date`、`x-amz-content-sha256`)。これらは AWS リクエスト署名用に予約されています。
+ プレフィックスが のヘッダーを除き、 `X-Amzn-Bedrock-AgentCore-Runtime-Custom-` で始まるすべてのヘッダー`x-amzn-`は制限されます。

## ステップ 1: エージェントを作成する
<a name="create-agent-headers"></a>

空の AgentCore プロジェクトを作成し、リクエストヘッダーの許可リストを持つエージェントを追加します。

```bash
agentcore create --name MyHeaderProject --template empty
cd MyHeaderProject
agentcore add runtime \
  --name MyHeaderAgent \
  --language python \
  --protocol HTTP \
  --request-header-allowlist \
    X-Custom-Signature \
    X-Api-Key \
    X-Amzn-Bedrock-AgentCore-Runtime-Custom-UserId
```

Python プロジェクトを初期化し、その依存関係を追加します。

```bash
cd app/MyHeaderAgent
uv init --bare
uv add \
  "aws-opentelemetry-distro~=0.21.0" \
  "bedrock-agentcore[strands-agents]>=1.18.1,<2" \
  "botocore[crt]~=1.43.0" \
  "strands-agents>=1.15,<2"
cd ../..
```

リクエストコンテキストからカスタムヘッダーにアクセスするには、 `app/MyHeaderAgent/main.py`を作成します。

```python
import json
from bedrock_agentcore.runtime import BedrockAgentCoreApp, RequestContext
from strands import Agent

app = BedrockAgentCoreApp()
agent = Agent()

@app.entrypoint
def agent_invocation(payload, context: RequestContext):
    """Handler for agent invocation"""
    user_message = payload.get("prompt", "")
    if not isinstance(user_message, str) or not user_message.strip():
        return {"error": "Invalid input: 'prompt' must be a non-empty string"}
    app.logger.info("invoking agent with user message: %s", payload)
    response = agent(user_message)

    # access request headers here
    header_names = ["X-Custom-Signature", "X-Api-Key", "X-Amzn-Bedrock-AgentCore-Runtime-Custom-UserId"]
    request_headers = {name: context.request.headers.get(name) for name in header_names}
    app.logger.info("Headers: %s", json.dumps(request_headers))
    return response

app.run()
```

`context.request_headers` プロパティには、 というプレフィックスが付いた `Authorization` ヘッダーと ヘッダーのみが含まれます`X-Amzn-Bedrock-AgentCore-Runtime-Custom-`。など、許可リストに登録されている他のヘッダーを読み取るには`X-Custom-Signature`、基盤となるリクエストのヘッダー を使用します`context.request.headers`。

## ステップ 2: カスタムヘッダーを使用してエージェントを設定およびデプロイする
<a name="deploy-agentcore-runtime"></a>

カスタムヘッダーが呼び出し時にエージェントコードに転送されるように、エージェントのランタイムでリクエストヘッダーの許可リストを設定します。

ステップ 1 の `agentcore add runtime` コマンドは、 のランタイムの `requestHeaderAllowlist`フィールドに許可リストを保存します`agentcore/agentcore.json`。後で許可リストを変更するには、そのフィールドを編集して再度デプロイします。

エージェントをデプロイします。

```bash
agentcore deploy
```

必要に応じて、`agentcore build`最初に を実行して、デプロイせずにプロジェクトを合成して確認します。

`agentcore status --json` を実行します。ランタイムリソースの `arn`フィールドには、その ARN が含まれます。

AgentCore CLI ではなく AWS SDK を使用してランタイムを管理する場合は、 `CreateAgentRuntime`または を呼び出す`requestHeaderConfiguration`ときに を設定します`UpdateAgentRuntime`。詳細については、「[RequestHeaderConfiguration](https://docs.aws.amazon.com/bedrock-agentcore-control/latest/APIReference/API_RequestHeaderConfiguration.html)」を参照してください。

## ステップ 3: カスタムヘッダーを使用してエージェントを呼び出す
<a name="invoke-custom-headers"></a>

エージェントを呼び出すときにカスタムヘッダーを渡して、エージェントコードがリクエストコンテキストを介してアクセスできるようにします。

**Example**  

1. `--header` を使用して でカスタムヘッダーを渡します`agentcore invoke`。

   ```bash
   agentcore invoke --runtime MyHeaderAgent \
     --payload '{"prompt":"Tell me a joke"}' \
     --header "X-Custom-Signature: sha256=abc123def456"
   ```

   を繰り返して複数のヘッダーを渡すことができます`--header`。

   ```bash
   agentcore invoke --runtime MyHeaderAgent \
     --payload '{"prompt":"Tell me a joke"}' \
     --header "X-Custom-Signature: sha256=abc123def456" \
     --header "X-Api-Key: my-api-key" \
     --header "X-Amzn-Bedrock-AgentCore-Runtime-Custom-UserId: user-123"
   ```

1. boto3 とイベントハンドラーを使用して、エージェントの呼び出しにカスタムヘッダーを追加します。botocore イベントの詳細については、[botocore イベントのドキュメント](https://botocore.amazonaws.com/v1/documentation/api/latest/topics/events.html)を参照してください。

   ```python
   import json
   import boto3
   
   agent_arn = 'YOUR_AGENT_ARN_HERE'
   prompt = "Tell me a joke"
   
   agent_core_client = boto3.client('bedrock-agentcore', region_name='us-west-2')
   event_system = agent_core_client.meta.events
   
   EVENT_NAME = 'before-sign.bedrock-agentcore.InvokeAgentRuntime'
   CUSTOM_HEADER_NAME = 'X-Custom-Signature'
   CUSTOM_HEADER_VALUE = 'sha256=abc123def456'
   
   def add_custom_runtime_header(request, **kwargs):
       request.headers.add_header(CUSTOM_HEADER_NAME, CUSTOM_HEADER_VALUE)
   
   handler = event_system.register_first(EVENT_NAME, add_custom_runtime_header)
   
   payload = json.dumps({"prompt": prompt}).encode()
   response = agent_core_client.invoke_agent_runtime(
       agentRuntimeArn=agent_arn,
       payload=payload
   )
   
   event_system.unregister(EVENT_NAME, handler)
   
   content = []
   for chunk in response.get("response", []):
       content.append(chunk.decode('utf-8'))
   print(json.loads(''.join(content)))
   ```

## ステップ 4: (オプション) インバウンド JWT 認証を設定する
<a name="pass-jwt-token"></a>

エージェントへの OAuth ベースのインバウンドアクセスに使用される JWT トークンを渡すには、エージェント設定`authorizerConfiguration`で `authorizerType`と を設定します。

**Example**  

1. JWT 認証を使用するには、ステップ 1 の コマンドの代わりに次の`agentcore add runtime`コマンドを実行します。

   ```bash
   agentcore add runtime \
     --name MyHeaderAgent \
     --language python \
     --protocol HTTP \
     --authorizer-type CUSTOM_JWT \
     --authorizer-configuration \
     '{"customJwtAuthorizer":{"discoveryUrl":"https://cognito-idp.us-east-1.amazonaws.com/user-pool-id/.well-known/openid-configuration","allowedAudience":["your-client-id"],"allowedClients":["your-client-id"]}}' \
     --request-header-allowlist \
       Authorization \
       X-Custom-Signature \
       X-Api-Key \
       X-Amzn-Bedrock-AgentCore-Runtime-Custom-UserId
   ```

   デプロイして設定を適用します。

   ```bash
   agentcore deploy
   ```

   この設定では、受信リクエストの`Authorization`ヘッダーが ID プロバイダーに対して検証され、カスタムヘッダーとともにエージェントコードに転送されます。

   ステップ 3 でエージェントを呼び出すときは、 を使用して ID プロバイダーから JWT も渡します`--bearer-token`。をトークン`<access-token>`に置き換えます。

   ```bash
   agentcore invoke --runtime MyHeaderAgent \
     --bearer-token "<access-token>" \
     --payload '{"prompt":"Tell me a joke"}' \
     --header "X-Custom-Signature: sha256=abc123def456"
   ```

1.  AWS SDK を使用して OAuth インバウンドアクセスを持つエージェントを設定する方法については、[「インバウンド認証とアウトバウンド認証による認証と認可](runtime-oauth.md)」を参照してください。