制限付きヘッダーステップ 1: エージェントを作成するステップ 2: カスタムヘッダーを使用してエージェントを設定およびデプロイするステップ 3: カスタムヘッダーを使用してエージェントを呼び出すステップ 4: (オプション) インバウンド JWT 認証を設定する

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

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

Amazon Bedrock AgentCore Runtime では、ヘッダーが次の基準を満たしていれば、リクエスト内のヘッダーをエージェントコードに渡すことができます。

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

制限付きヘッダー

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

Category	ヘッダー
認証と認可	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: エージェントを作成する

AgentCore CLI を使用して AgentCore プロジェクトを作成します。


agentcore create --name MyHeaderAgent
cd MyHeaderAgent

エージェントのエントリポイントファイルを更新して、リクエストコンテキストからカスタムヘッダーにアクセスします。


import json
from bedrock_agentcore 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", "No prompt found in input, please guide customer to create a json payload with prompt key"
    )
    app.logger.info("invoking agent with user message: %s", payload)
    response = agent(user_message)

    # access request headers here
    request_headers = context.request_headers
    app.logger.info("Headers: %s", json.dumps(request_headers))
    return response

app.run()

ステップ 2: カスタムヘッダーを使用してエージェントを設定およびデプロイする

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

例

ステップ 3: カスタムヘッダーを使用してエージェントを呼び出す

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

例

AgentCore CLI

-H フラグを使用して、 agentcore invoke でカスタムヘッダーを渡します。


agentcore invoke "Tell me a joke" \
  -H "X-Custom-Signature: sha256=abc123def456"

-H フラグを繰り返すことで、複数のヘッダーを渡すことができます。


agentcore invoke "Tell me a joke" \
  -H "X-Custom-Signature: sha256=abc123def456" \
  -H "X-Api-Key: my-api-key" \
  -H "X-Amzn-Bedrock-AgentCore-Runtime-Custom-UserId: user-123"

AWS SDK

boto3 とイベントハンドラーを使用して、エージェントの呼び出しにカスタムヘッダーを追加します。botocore イベントの詳細については、botocore イベントのドキュメントを参照してください。


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 認証を設定する

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

例

ブラウザで JavaScript が無効になっているか、使用できません。

AWS ドキュメントを使用するには、JavaScript を有効にする必要があります。手順については、使用するブラウザのヘルプページを参照してください。

ドキュメントの表記規則

コードの例

インバウンド認証とアウトバウンド認証による認証と認可