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 授權方時，您也可以傳遞 JWT 型身分驗證的 Authorization標頭。繼續X-Amzn-Bedrock-AgentCore-Runtime-Custom-支援字首為 的標頭，以實現回溯相容性。每個執行時間最多可設定 20 個標頭，每個標頭值限制為 4KB。

Amazon Bedrock AgentCore 執行期可讓您將請求中的標頭傳遞給代理程式程式碼，前提是標頭符合下列條件：

  • 標頭名稱是有效的 HTTP 標頭 （英數字元、連字號和底線），且不在限制標頭清單中。

  • x-amz- 不允許以 開頭的標頭 （這些標頭會保留給 AWS SigV4 簽署）。

  • x-amzn- 不允許使用開頭為 的標頭，但字首為 X-Amzn-Bedrock-AgentCore-Runtime-Custom- 的標頭除外。

  • Authorization 標頭要求使用 設定代理程式執行期customJWTAuthorizer，以進行以 OAuth 為基礎的傳入存取。

  • 標頭值的大小不大於 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

快取

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：建立您的代理程式

使用 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 操作。您必須包含所有必要欄位 (roleArn、agentRuntimeArtifact、networkConfiguration)，即使尚未變更。

    您可以執行 來尋找執行時間 IDagentcore 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 事件的詳細資訊，請參閱 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和 。

範例
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 傳入存取的代理程式的資訊，請參閱使用傳入身分驗證和傳出身分驗證進行身分驗證和授權。