View a markdown version of this page

Teruskan header khusus ke Amazon Bedrock AgentCore Runtime - Batuan Dasar Amazon AgentCore
Header terbatasLangkah 1: Buat agen AndaLangkah 2: Konfigurasikan dan terapkan agen Anda dengan header khususLangkah 3: Panggil agen Anda dengan header khususLangkah 4: (Opsional) Konfigurasikan otentikasi JWT masuk

Teruskan header khusus ke Amazon Bedrock AgentCore Runtime

Header khusus memungkinkan Anda meneruskan informasi kontekstual dari aplikasi Anda langsung ke kode agen Anda tanpa mengacaukan payload permintaan utama. Anda dapat meneruskan header HTTP yang valid yang tidak ada dalam daftar header terbatas, termasuk tanda tangan webhook seperti, kunci API sepertiX-Custom-Signature, konteks jejakX-Api-Key, atau pengidentifikasi sesi. Anda juga dapat meneruskan Authorization header untuk JWT-based otentikasi ketika agen Anda dikonfigurasi dengan otorisasi JWT kustom. Header diawali dengan X-Amzn-Bedrock-AgentCore-Runtime-Custom- terus didukung untuk kompatibilitas mundur. Hingga 20 header dapat dikonfigurasi per runtime, dan setiap nilai header dibatasi hingga 4KB.

Amazon Bedrock AgentCore Runtime memungkinkan Anda meneruskan header dalam permintaan ke kode agen Anda asalkan header memenuhi kriteria berikut:

  • Nama header adalah header HTTP yang valid (karakter alfanumerik, tanda hubung, dan garis bawah) dan tidak ada dalam daftar header terbatas.

  • Header yang dimulai dengan tidak x-amz- diizinkan (ini dicadangkan untuk AWS penandatanganan SigV4).

  • Header yang dimulai dengan tidak x-amzn- diperbolehkan, kecuali untuk header yang diawali dengan. X-Amzn-Bedrock-AgentCore-Runtime-Custom-

  • AuthorizationHeader mengharuskan runtime agen untuk dikonfigurasi dengan a customJWTAuthorizer for OAuth-based inbound access.

  • Nilai header tidak lebih besar dari 4KB dalam ukuran.

  • Hingga 20 header dapat dikonfigurasi per runtime.

  • Nama header tidak peka huruf besar/kecil dan duplikat (dengan perbandingan case-insensitive) tidak diperbolehkan.

Header terbatas

Untuk menjaga keamanan dan mencegah paparan informasi sensitif, header berikut dibatasi dan tidak dapat dikonfigurasi untuk propagasi:

Kategori Header

Otentikasi & Otorisasi

Proxy-Authorization, WWW-Authenticate

Negosiasi Konten

Menerima Accept-Charset, Accept-Encoding, Accept-Language, Content-Type, Content-Length,, Content-Encoding, Content-Language, Content-Location, Content-Range

Pembuatan cache

Cache-Control, ETag, Kedaluwarsa,,, If-Match, If-Modified-Since,, If-None-Match If-Range, Pragma If-Unmodified-Since Last-Modified, Bervariasi

Manajemen Koneksi

Koneksi, Keep-Alive, Proxy-Connection, Tingkatkan

Permintaan Konteks

Tuan rumah, User-Agent, Referer, Dari

Jangkauan/Transfer

Rentang, Accept-Ranges, Transfer-Encoding, TE, Trailer

Informasi Server

Server, Tanggal, Lokasi, Retry-After

Cookie

Set-Cookie, Cookie

Keamanan

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, Asal

Petunjuk Klien

Accept-CH, Accept-CH-Lifetime, DPR, Lebar, Viewport-Width, Downlink, DLL, RTT, Save-Data

Eksperimental/Diusulkan

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

Proksi

Melalui, Diteruskan,, X-Forwarded-For,, X-Forwarded-Host, X-Forwarded-Proto, X-Real-IP X-Requested-With X-CSRF-Token

IP Spoofing /URL Manipulasi

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/ Proksi

CF-Ray, CF-Connecting-IP, X-Amz-Cf-Id, X-Cache, X-Served-By

HTTP/2 Pseudo Header

:metode, :path, :scheme, :authority, :status

Dorong Server

Tautan

WebSocket

Sec-WebSocket-Key, Sec-WebSocket-Accept, Sec-WebSocket-Version, Sec-WebSocket-Protocol, Sec-WebSocket-Extensions

Selain header terbatas yang tercantum di atas:

  • Semua header yang dimulai dengan x-amz- dibatasi (misalnya,, x-amz-security-tokenx-amz-date,x-amz-content-sha256). Ini dicadangkan untuk penandatanganan AWS permintaan.

  • Semua header yang dimulai dengan x-amzn- dibatasi, kecuali untuk header yang diawali dengan. X-Amzn-Bedrock-AgentCore-Runtime-Custom-

Langkah 1: Buat agen Anda

Buat AgentCore proyek menggunakan AgentCore CLI:

agentcore create --name MyHeaderAgent
cd MyHeaderAgent

Perbarui file entrypoint agen Anda untuk mengakses header kustom dari konteks permintaan:

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()

Langkah 2: Konfigurasikan dan terapkan agen Anda dengan header khusus

Konfigurasikan daftar izin header permintaan pada runtime agen Anda sehingga header khusus diteruskan ke kode agen Anda pada waktu pemanggilan.

contoh
AgentCore CLI

  1. Tambahkan requestHeaderAllowlist bidang ke konfigurasi agen Anda diagentcore/agentcore.json:

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

    Menyebarkan agen Anda:

    agentcore deploy

    Perhatikan ARN runtime agen dari output. Anda membutuhkannya jika Anda berencana untuk memanggil menggunakan AWS SDK.

AWS SDK

  1. Setelah menerapkan agen Anda, perbarui konfigurasi runtime menggunakan SDK AWS :

    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'
        ]
    }
)
    catatan

    update_agent_runtimeadalah operasi PUT penuh. Anda harus menyertakan semua bidang wajib (roleArnagentRuntimeArtifact,,networkConfiguration) meskipun belum berubah.

    Anda dapat menemukan ID runtime Anda dengan menjalankanagentcore status.

Langkah 3: Panggil agen Anda dengan header khusus

Lewati header khusus saat memanggil agen Anda sehingga kode agen Anda dapat mengaksesnya melalui konteks permintaan.

contoh
AgentCore CLI

  1. Gunakan -H bendera untuk meneruskan header kustom denganagentcore invoke:

    agentcore invoke "Tell me a joke" \
  -H "X-Custom-Signature: sha256=abc123def456"

    Anda dapat melewati beberapa header dengan mengulangi bendera: -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. Gunakan boto3 dengan event handler untuk menambahkan header kustom ke pemanggilan agen Anda. Untuk detail selengkapnya tentang peristiwa botocore, lihat dokumentasi acara 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)))

Langkah 4: (Opsional) Konfigurasikan otentikasi JWT masuk

Untuk meneruskan token JWT yang digunakan untuk akses OAuth-based masuk ke agen Anda, konfigurasikan authorizerType dan authorizerConfiguration dalam konfigurasi agen Anda.

contoh
AgentCore CLI

  1. Tambahkan konfigurasi otorisasi ke agen Anda diagentcore/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"
      ]
    }
  ]
}

    Terapkan untuk menerapkan konfigurasi:

    agentcore deploy

    Dengan konfigurasi ini, Authorization header dari permintaan masuk divalidasi terhadap penyedia OIDC Anda dan diteruskan ke kode agen Anda.

AWS SDK

  1. Untuk informasi tentang menyiapkan agen dengan akses masuk OAuth menggunakan AWS SDK, lihat Mengautentikasi dan mengotorisasi dengan Auth Masuk dan Auth Keluar.