View a markdown version of this page

向亚马逊 Bedrock R AgentCore untime 传递自定义标 - 亚马逊基岩 AgentCore
受限标题第 1 步：创建您的代理第 2 步：使用自定义标头配置和部署代理第 3 步：使用自定义标头调用您的代理第 4 步：（可选）配置入站 JWT 身份验证

本文属于机器翻译版本。若本译文内容与英语原文存在差异，则一律以英文原文为准。

向亚马逊 Bedrock R AgentCore untime 传递自定义标

自定义标头使您可以将上下文信息从应用程序直接传递到代理代码，而不会使主请求负载混乱。您可以传递任何不在受限标头列表中的有效 HTTP 标头，包括 webhook 签名X-Custom-Signature，例如 API 密钥X-Api-Key，跟踪上下文或会话标识符。当您的代理配置为自定义 JWT 授权器时，您也可以传递Authorization标头进行 JWT-based 身份验证。为了向后兼容，X-Amzn-Bedrock-AgentCore-Runtime-Custom-将继续支持前缀为的标头。每个运行时最多可以配置 20 个标头，并且每个标头值限制为 4KB。

Amazon Bedrock AgentCore Runtime 允许您在请求中将标头传递给代理代码，前提是标头符合以下标准：

  • 标头名称是有效的 HTTP 标头（字母数字字符、连字符和下划线），不在受限标头列表中。受限标题

  • 不允许使用以x-amz-开头的标头（这些标头保留给 S AWS igV4 签名）。

  • 不允许使用以开头x-amzn-的标头，前缀为的标题除外。X-Amzn-Bedrock-AgentCore-Runtime-Custom-

  • 标Authorization头要求将代理运行时配置为customJWTAuthorizer用于 OAuth-based 入站访问。

  • 标头值的大小不超过 4KB。

  • 每个运行时最多可以配置 20 个标头。

  • 标头名称不区分大小写，不允许重复（通过不区分大小写的比较）。

受限标题

为了维护安全并防止敏感信息泄露，以下标头受到限制，无法配置为传播：

类别 标头

身份验证和授权

Proxy-Authorization, WWW-Authenticate

内容协商

接受, Accept-Charset, Accept-Encoding, Accept-Language, Content-Type, Content-Length,, Content-Encoding, Content-Language, Content-Location, Content-Range

缓存

Cache-Control, ETag, Expires,, If-Match,, If-Modified-Since,, If-None-Match, If-Range, Pragma If-Unmodified-Since Last-Modified, Vary

连接管理

连接、 Keep-Alive Proxy-Connection、升级

请求上下文

主持人、推荐人 User-Agent、发件人

范围/传输

Range, Accept-Ranges, Transfer-Encoding, TE, 预告片

服务器信息

服务器，日期，位置， Retry-After

Cookie

Set-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, 起源

客户提示

Accept-CH, Accept-CH-Lifetime, DPR, 宽度,, 下行链路 Viewport-Width, ECT, RTT, Save-Data

实验/已提议

Clear-Site-Data, Feature-Policy, Expect-CT, Public-Key-Pins, Public-Key-Pins-Report-Only

代理

通过、转发 X-Forwarded-For、 X-Forwarded-Host、 X-Forwarded-Proto、 X-Real-IP、 X-Requested-With、 X-CSRF-Token

IP 欺骗/网址操纵

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 伪标头

:方法、:路径、:方案、:权限、:状态

服务器推送

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-都受到限制，前缀X-Amzn-Bedrock-AgentCore-Runtime-Custom-为的标题除外。

第 1 步：创建您的代理

创建一个空 AgentCore 项目，然后使用请求标头许可列表添加代理：

agentcore create --project-name MyHeaderProject --no-agent
cd MyHeaderProject
agentcore add agent \
  --name MyHeaderAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --request-header-allowlist X-Custom-Signature,X-Api-Key,X-Amzn-Bedrock-AgentCore-Runtime-Custom-UserId

更新代理的入口点文件以访问请求上下文中的自定义标头：

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", "")
    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
    request_headers = context.request_headers
    app.logger.info("Headers: %s", json.dumps(request_headers))
    return response

app.run()

第 2 步：使用自定义标头配置和部署代理

在代理运行时配置请求标头允许列表，以便在调用时将自定义标头转发到您的代理代码。

例
AgentCore CLI

  1. 步骤 1 中的agentcore add agent命令将允许列表存储在中的运行时配置runtimes中agentcore/agentcore.json。

    部署您的代理：

    agentcore deploy

    记下输出中的代理运行时 ARN。如果您计划使用 AWS SDK 进行调用，则需要它。

AWS SDK

  1. 部署代理后，使用 AWS SDK 更新运行时配置：

    import boto3

client = boto3.client('bedrock-agentcore-control', region_name='us-west-2')

client.update_agent_runtime(
    agentRuntimeId='your-runtime-id',
    roleArn='arn:aws:iam::123456789012:role/YourAgentRole',
    agentRuntimeArtifact={'containerConfiguration': {'containerUri': 'your-container-uri'}},
    networkConfiguration={'networkMode': 'PUBLIC'},
    requestHeaderConfiguration={
        'requestHeaderAllowlist': [
            'X-Custom-Signature',
            'X-Api-Key'
        ]
    }
)
    注意

    update_agent_runtime是一个完整的 PUT 操作。您必须包括所有必填字段 (roleArnagentRuntimeArtifact,,networkConfiguration)，即使它们没有更改。

    你可以通过运行来找到你的运行时ID agentcore status。

第 3 步：使用自定义标头调用您的代理

调用代理时传递自定义标头，以便您的代理代码可以通过请求上下文访问它们。

例
AgentCore CLI

  1. 使用该-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

  1. 使用带有事件处理程序的 boto3 向代理调用添加自定义标头。有关 botocore 事件的更多详细信息，请参阅 b otocore 事件文档。

    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-based 入站访问的 JWT 令牌传递给代理，请在代理配置authorizerConfiguration中配置authorizerType和。

例
AgentCore CLI

  1. 要使用 JWT 身份验证，请运行以下命令而不是步骤 1 中的agentcore add agent命令：

    agentcore add agent \
  --name MyHeaderAgent \
  --language Python \
  --framework Strands \
  --model-provider Bedrock \
  --memory none \
  --authorizer-type CUSTOM_JWT \
  --discovery-url "https://cognito-idp.us-east-1.amazonaws.com/user-pool-id/.well-known/openid-configuration" \
  --allowed-audience "your-client-id" \
  --allowed-clients "your-client-id" \
  --request-header-allowlist Authorization

    部署以应用配置：

    agentcore deploy

    使用此配置，传入请求的Authorization标头会根据您的 OIDC 提供商进行验证，然后转发到您的代理代码。

AWS SDK

  1. 有关使用 AWS SDK 设置具有 OAuth 入站访问权限的代理的信息，请参阅使用入站身份验证和出站身份验证进行身份验证和授权。