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

# 向亚马逊 Bedrock R AgentCore untime 传递自定义标
<a name="runtime-header-allowlist"></a>

自定义标头使您可以将上下文信息从应用程序直接传递到代理代码，而不会使主请求负载混乱。您可以传递任何不在[受限标头](#runtime-header-restrictions)列表中的有效 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 标头（字母数字字符、连字符和下划线），不在受限标头列表中。[受限标题](#runtime-header-restrictions)
+ 不允许使用以`x-amz-`开头的标头（这些标头保留给 S Amazon igV4 签名）。
+ 不允许使用以开头`x-amzn-`的标头，前缀为的标题除外。`X-Amzn-Bedrock-AgentCore-Runtime-Custom-`
+ 标`Authorization`头要求将代理运行时配置为`customJWTAuthorizer`用于 OAuth-based 入站访问。
+ 标头值的大小不超过 4KB。
+ 每个运行时最多可以配置 20 个标头。
+ 标头名称不区分大小写，不允许重复（通过不区分大小写的比较）。

## 受限标题
<a name="runtime-header-restrictions"></a>

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


| 类别 | 标头 | 
| --- | --- | 
| 身份验证和授权 | 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`）。它们是为 Amazon 请求签名保留的。
+ 所有以开头的标头`x-amzn-`都受到限制，前缀`X-Amzn-Bedrock-AgentCore-Runtime-Custom-`为的标题除外。

## 第 1 步：创建您的代理
<a name="create-agent-headers"></a>

创建一个空 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 步：使用自定义标头配置和部署代理
<a name="deploy-agentcore-runtime"></a>

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

**Example**  

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

   部署您的代理：

   ```
   agentcore deploy
   ```

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

1. 部署代理后，使用 Amazon 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 操作。您必须包括所有必填字段 (`roleArn``agentRuntimeArtifact`,,`networkConfiguration`)，即使它们没有更改。

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

## 第 3 步：使用自定义标头调用您的代理
<a name="invoke-custom-headers"></a>

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

**Example**  

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"
   ```

1. 使用带有事件处理程序的 boto3 向代理调用添加自定义标头。有关 botocore 事件的更多详细信息，请参阅 b [ otocore 事件文档。](https://botocore.amazonaws.com/v1/documentation/api/latest/topics/events.html)

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

**Example**  

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 提供商进行验证，然后转发到您的代理代码。

1. 有关使用 Amazon SDK 设置具有 OAuth 入站访问权限的代理的信息，请参阅使用入站[身份验证和出站身份验证进行身份验证和授权。](runtime-oauth.md)