View a markdown version of this page

将自定义标题传递给 Amazon Bedrock 运行 AgentCore 时 - Amazon Bedrock AgentCore
受限制的标题步骤 1：创建您的代理步骤 2：使用自定义标头配置和部署代理第 3 步：使用自定义标头调用您的代理步骤 4：（可选）配置入站 JWT 身份验证

将自定义标题传递给 Amazon Bedrock 运行 AgentCore 时

自定义标头允许您将上下文信息从应用程序直接传递到代理代码，而不会使主请求负载混乱。您可以传递任何不在受限制标头列表中的有效 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-开头的标头（这些标头保留给 AWS Sigv4 签名）。

  • 不允许使用以开头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、推荐人、发件人

射程/传输

续航里程、 Accept-Ranges、、TE Transfer-Encoding、TRailer

服务器信息

服务器、日期、地点、 Retry-After

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、、Downlink 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 伪标题

:method、:path、:scheme、:authority、:stat

服务器推送

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 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：使用自定义标头配置和部署代理

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

例
AgentCore CLI

  1. 在以下位置将该requestHeaderAllowlist字段添加到您的代理配置中agentcore/agentcore.json：

    {
  "agents": [
    {
      "name": "MyHeaderAgent",
      "requestHeaderAllowlist": [
        "X-Custom-Signature",
        "X-Api-Key",
        "X-Amzn-Bedrock-AgentCore-Runtime-Custom-UserId"
      ]
    }
  ]
}

    部署您的代理：

    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 事件的更多详细信息，请参阅 botoc ore 事件文档。

    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. 在以下位置将授权方配置添加到您的代理：agentcore/agentcore.json

    {
  "agents": [
    {
      "name": "MyHeaderAgent",
      "authorizerType": "CUSTOM_JWT",
      "authorizerConfiguration": {
        "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"]
        }
      },
      "requestHeaderAllowlist": [
        "Authorization"
      ]
    }
  ]
}

    部署以应用配置：

    agentcore deploy

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

AWS SDK

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