View a markdown version of this page

Berikan header khusus ke Amazon Bedrock Runtime AgentCore - Batu 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

Terjemahan disediakan oleh mesin penerjemah. Jika konten terjemahan yang diberikan bertentangan dengan versi bahasa Inggris aslinya, utamakan versi bahasa Inggris.

Berikan header khusus ke Amazon Bedrock Runtime AgentCore

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 valid yang tidak ada dalam daftar header terbatas, termasuk tanda tangan webhook seperti, kunci API sepertiX-Custom-Signature, konteks pelacakanX-Api-Key, atau pengidentifikasi sesi. Anda juga dapat meneruskan Authorization header untuk JWT-based otentikasi ketika agen Anda dikonfigurasi dengan otorizer JWT khusus. Header yang 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 terbatas

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

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

  • AuthorizationHeader membutuhkan runtime agen untuk dikonfigurasi dengan akses OAuth-based masuk customJWTAuthorizer untuk.

  • Nilai header tidak lebih besar dari ukuran 4KB.

  • Hingga 20 header dapat dikonfigurasi per runtime.

  • Nama header tidak peka huruf besar/kecil dan duplikat (dengan perbandingan yang tidak peka huruf besar/kecil) 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

Terima, 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 If-Unmodified-Since, Pragma Last-Modified, Bervariasi

Manajemen Koneksi

Koneksi, Keep-Alive, Proxy-Connection, Tingkatkan

Permintaan Konteks

Tuan rumah User-Agent,, Referer, Dari

Rentang/Transfer

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

Informasi Server

Server, Tanggal, Lokasi, Retry-After

Cookie

Set-Cookie, Kue

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,, Downlink Viewport-Width, ECT, 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

Penyalahgunaan IP/Manipulasi 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/Proksi

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

HTTP/2 Header semu

:metode, :jalur, :skema, :otoritas, :status

Dorongan 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 disediakan untuk penandatanganan AWS permintaan.

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

Langkah 1: Buat agen Anda

Buat AgentCore proyek kosong, lalu tambahkan agen dengan header permintaan allowlist:

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

Perbarui file titik masuk agen Anda untuk mengakses header khusus 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", "")
    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()

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. Per agentcore add agent intah di Langkah 1 menyimpan allowlist dalam konfigurasi runtime di bawah runtimes inagentcore/agentcore.json.

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

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

    Anda dapat menemukan ID runtime Anda dengan menjalankanagentcore status.

Langkah 3: Panggil agen Anda dengan header khusus

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

contoh
AgentCore CLI

  1. Gunakan ben -H dera untuk meneruskan header kustom dengan: agentcore invoke

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

    Anda dapat meneruskan beberapa header dengan mengulangi -H bendera:

    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 khusus ke pemanggilan agen Anda. Untuk detail selengkapnya tentang acara 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 OAuth-based akses masuk ke agen Anda, konfigurasikan authorizerType dan authorizerConfiguration dalam konfigurasi agen Anda.

contoh
AgentCore CLI

  1. Untuk menggunakan otentikasi JWT, jalankan perintah berikut alih-alih agentcore add agent perintah di Langkah 1:

    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

    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 Meng autentikasi dan mengotorisasi dengan Auth Masuk dan Auth Keluar.