# 將自訂標頭傳遞至 Amazon Bedrock AgentCore 執行期
<a name="runtime-header-allowlist"></a>

自訂標頭可讓您直接從應用程式將內容資訊傳遞至代理程式程式碼，而不會混淆主要請求承載。您可以傳遞不在[限制標頭清單中的任何有效 HTTP 標頭](#runtime-header-restrictions)，包括 Webhook 簽章，例如 `X-Custom-Signature`、API 金鑰，例如 `X-Api-Key`、追蹤內容或工作階段識別符。當您的代理程式設定為自訂 JWT 授權方時，您也可以傳遞 JWT 型身分驗證的 `Authorization`標頭。繼續`X-Amzn-Bedrock-AgentCore-Runtime-Custom-`支援字首為 的標頭，以實現回溯相容性。每個執行時間最多可設定 20 個標頭，每個標頭值限制為 4KB。

Amazon Bedrock AgentCore 執行期可讓您將請求中的標頭傳遞給代理程式程式碼，前提是標頭符合下列條件：
+ 標頭名稱是有效的 HTTP 標頭 （英數字元、連字號和底線），且不在[限制標頭](#runtime-header-restrictions)清單中。
+ `x-amz-` 不允許以 開頭的標頭 （這些標頭會保留給 AWS SigV4 簽署）。
+ `x-amzn-` 不允許使用開頭為 的標頭，但字首為 `X-Amzn-Bedrock-AgentCore-Runtime-Custom-` 的標頭除外。
+ `Authorization` 標頭要求使用 設定代理程式執行期`customJWTAuthorizer`，以進行以 OAuth 為基礎的傳入存取。
+ 標頭值的大小不大於 4KB。
+ 每個執行時間最多可設定 20 個標頭。
+ 標頭名稱不區分大小寫，不允許重複 （依不區分大小寫比較）。

## 限制標頭
<a name="runtime-header-restrictions"></a>

為了維護安全性並防止暴露敏感資訊，下列標頭受到限制，且無法設定為傳播：


| Category | 標頭 | 
| --- | --- | 
| 身分驗證與授權 | Proxy-Authorization、WWW-Authenticate | 
| 內容議價 | Accept、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、If-Unmodified-Since、Last-Modified、Pragma、Vary | 
| 連線管理 | 連線、保持運作、代理連線、升級 | 
| 請求內容 | 主機、使用者代理程式、參考者、寄件人 | 
| 範圍/傳輸 | 範圍、接受範圍、傳輸編碼、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、Refrer-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、寬度、Viewport-Width、下行、ECT、RTT、Sav-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 虛擬標頭 | ：方法、：路徑、：結構描述、：授權、：狀態 | 
| 伺服器推送 | 連結 | 
| WebSocket | Sec-WebSocket-Key、Sec-WebSocket-Accept、Sec-WebSocket-Version、Sec-WebSocket-Protocol、Sec-WebSocket-Extensions | 

除了上述的限制標頭之外：
+ 所有以 `x-amz-security-token` 開頭的標頭`x-amz-`都會受到限制 `x-amz-date` （例如，、、`x-amz-content-sha256`)。這些會保留給 AWS 請求簽署。
+ 所有以 開頭的標頭`x-amzn-`都會受到限制，但字首為 `X-Amzn-Bedrock-AgentCore-Runtime-Custom-` 的標頭除外。

## 步驟 1：建立您的代理程式
<a name="create-agent-headers"></a>

使用 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：使用自訂標頭設定和部署您的代理程式
<a name="deploy-agentcore-runtime"></a>

在代理程式執行時間上設定請求標頭允許清單，以便在調用時將自訂標頭轉送到您的代理程式程式碼。

**Example**  

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 叫用 ，則需要它。

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 操作。您必須包含所有必要欄位 (`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 事件的詳細資訊，請參閱 [botocore 事件文件](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 型傳入存取的 JWT 字符傳遞至您的代理程式，請在您的代理程式組態`authorizerConfiguration`中設定 `authorizerType`和 。

**Example**  

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 提供者進行驗證，並轉送到您的代理程式程式碼。

1. 如需有關使用 AWS SDK 設定具有 OAuth 傳入存取的代理程式的資訊，請參閱[使用傳入身分驗證和傳出身分驗證進行身分驗證和授權](runtime-oauth.md)。