# Teruskan header khusus ke Amazon Bedrock AgentCore Runtime
<a name="runtime-header-allowlist"></a>

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](#runtime-header-restrictions), termasuk tanda tangan webhook seperti, kunci API seperti`X-Custom-Signature`, konteks jejak`X-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.](#runtime-header-restrictions)
+ 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-`
+ `Authorization`Header 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
<a name="runtime-header-restrictions"></a>

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-token``x-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
<a name="create-agent-headers"></a>

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
<a name="deploy-agentcore-runtime"></a>

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

**Example**  

1. Tambahkan `requestHeaderAllowlist` bidang ke konfigurasi agen Anda di`agentcore/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.

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_runtime`adalah operasi PUT penuh. Anda harus menyertakan semua bidang wajib (`roleArn``agentRuntimeArtifact`,,`networkConfiguration`) meskipun belum berubah.

   Anda dapat menemukan ID runtime Anda dengan menjalankan`agentcore status`.

## Langkah 3: Panggil agen Anda dengan header khusus
<a name="invoke-custom-headers"></a>

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

**Example**  

1. Gunakan `-H` bendera untuk meneruskan header kustom dengan`agentcore 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"
   ```

1. Gunakan boto3 dengan event handler untuk menambahkan header kustom ke pemanggilan agen Anda. Untuk detail selengkapnya tentang peristiwa botocore, lihat dokumentasi acara [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)))
   ```

## Langkah 4: (Opsional) Konfigurasikan otentikasi JWT masuk
<a name="pass-jwt-token"></a>

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

**Example**  

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

   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.

1. Untuk informasi tentang menyiapkan agen dengan akses masuk OAuth menggunakan AWS SDK, lihat [Mengautentikasi dan mengotorisasi dengan Auth Masuk dan Auth](runtime-oauth.md) Keluar.