View a markdown version of this page

Übergeben Sie benutzerdefinierte Header an Amazon Bedrock Runtime AgentCore - Amazon Grundgestein AgentCore
Eingeschränkte HeaderSchritt 1: Erstellen Sie Ihren AgentenSchritt 2: Konfigurieren und implementieren Sie Ihren Agenten mit benutzerdefinierten HeadernSchritt 3: Rufen Sie Ihren Agenten mit benutzerdefinierten Headern aufSchritt 4: (Optional) Konfigurieren Sie die eingehende JWT-Authentifizierung

Übergeben Sie benutzerdefinierte Header an Amazon Bedrock Runtime AgentCore

Mit benutzerdefinierten Headern können Sie Kontextinformationen aus Ihrer Anwendung direkt an Ihren Agentencode übergeben, ohne die Hauptnutzlast der Anfrage zu überladen. Sie können jeden gültigen HTTP-Header übergeben, der nicht in der Liste mit eingeschränkten Headern enthalten ist, einschließlich Webhook-Signaturen wie, API-Schlüsseln wie X-Custom-SignatureX-Api-Key, Trace-Kontext oder Sitzungskennungen. Sie können den Authorization Header auch zur JWT-based Authentifizierung übergeben, wenn Ihr Agent mit einem benutzerdefinierten JWT-Autorisierer konfiguriert ist. Header mit einem Präfix werden aus Gründen der X-Amzn-Bedrock-AgentCore-Runtime-Custom- Abwärtskompatibilität weiterhin unterstützt. Pro Laufzeit können bis zu 20 Header konfiguriert werden, und jeder Header-Wert ist auf 4 KB begrenzt.

Mit Amazon Bedrock AgentCore Runtime können Sie Header in einer Anfrage an Ihren Agentencode übergeben, sofern die Header die folgenden Kriterien erfüllen:

  • Der Header-Name ist ein gültiger HTTP-Header (alphanumerische Zeichen, Bindestriche und Unterstriche) und steht nicht in der Liste der eingeschränkten Header.

  • Header, die mit beginnen, x-amz- sind nicht erlaubt (diese sind für die Sigv4-Signatur reserviert). AWS

  • Header, die mit beginnen, x-amzn- sind nicht erlaubt, mit Ausnahme von Headern mit dem Präfix. X-Amzn-Bedrock-AgentCore-Runtime-Custom-

  • Für den Authorization Header muss die Agenten-Laufzeit mit einem customJWTAuthorizer für OAuth-based eingehenden Zugriff konfiguriert sein.

  • Der Header-Wert ist nicht größer als 4 KB.

  • Pro Laufzeit können bis zu 20 Header konfiguriert werden.

  • Bei Header-Namen wird nicht zwischen Groß- und Kleinschreibung unterschieden und Duplikate (bei Vergleich ohne Berücksichtigung der Groß- und Kleinschreibung) sind nicht zulässig.

Eingeschränkte Header

Um die Sicherheit zu gewährleisten und die Offenlegung vertraulicher Informationen zu verhindern, sind die folgenden Header eingeschränkt und können nicht für die Weitergabe konfiguriert werden:

Kategorie Kopfzeilen

Authentifizierung und Autorisierung

Proxy-Authorization, WWW-Authenticate

Content Negotiation (Inhaltsvereinbarung)

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

Caching

Cache-Control, ETag, Expires, If-Match, If-Modified-Since, If-None-Match,, If-Range, If-Unmodified-Since Last-Modified, Pragma, Vary

Verbindungsverwaltung

Verbindung, Keep-Alive Proxy-Connection, Upgrade

Kontext anfordern

Host User-Agent, Referer, Von

Bereich/Übertragung

Reichweite, Accept-Ranges Transfer-Encoding, TE, Anhänger

Informationen zum Server

Server, Datum, Ort, Retry-After

Cookies

Set-Cookie, Keks

Sicherheit

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

KERNE

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

Hinweise für Kunden

Accept-CH Accept-CH-Lifetime, DPR, Breite, Downlink Viewport-Width, ECT, RTT, Save-Data

Experimentell//Vorgeschlagen

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

Proxy

Über, Weitergeleitet X-Forwarded-For, X-Forwarded-Host, X-Forwarded-Proto, X-Real-IP, X-Requested-With, X-CSRF-Token

IP-Spoofing//URL-Manipulation

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

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

HTTP/2 Pseudo-Header

:Methode, :Pfad, :Schema, :Autorität, :Status

Server-Push

Link

WebSocket

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

Zusätzlich zu den oben aufgeführten eingeschränkten Headern:

  • Alle Header, die mit beginnen, x-amz- sind eingeschränkt (z. B., x-amz-security-tokenx-amz-date,x-amz-content-sha256). Diese sind für das Signieren von AWS Anfragen reserviert.

  • Alle Header, die mit beginnen, x-amzn- sind eingeschränkt, mit Ausnahme von Headern mit dem Präfix. X-Amzn-Bedrock-AgentCore-Runtime-Custom-

Schritt 1: Erstellen Sie Ihren Agenten

Erstellen Sie ein AgentCore Projekt mit der AgentCore CLI:

agentcore create --name MyHeaderAgent
cd MyHeaderAgent

Aktualisieren Sie die Einstiegspunktdatei Ihres Agenten, um über den Anforderungskontext auf die benutzerdefinierten Header zuzugreifen:

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

Schritt 2: Konfigurieren und implementieren Sie Ihren Agenten mit benutzerdefinierten Headern

Konfigurieren Sie die Zulassungsliste für Anforderungsheader in Ihrer Agenten-Laufzeit so, dass benutzerdefinierte Header zum Zeitpunkt des Aufrufs an Ihren Agentencode weitergeleitet werden.

Beispiel
AgentCore CLI

  1. Fügen Sie das requestHeaderAllowlist Feld zu Ihrer Agentenkonfiguration hinzu in: agentcore/agentcore.json

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

    Stellen Sie Ihren Agenten bereit:

    agentcore deploy

    Notieren Sie sich den Runtime-ARN des Agenten aus der Ausgabe. Sie benötigen ihn, wenn Sie mit dem AWS SDK aufrufen möchten.

AWS SDK

  1. Aktualisieren Sie nach der Bereitstellung Ihres Agenten die Laufzeitkonfiguration mithilfe des 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'
        ]
    }
)
    Anmerkung

    update_agent_runtimeist ein vollständiger PUT-Vorgang. Sie müssen alle erforderlichen Felder (roleArn,,networkConfiguration) agentRuntimeArtifact angeben, auch wenn sie sich nicht geändert haben.

    Sie können Ihre Runtime-ID finden, indem Sie Folgendes ausführenagentcore status.

Schritt 3: Rufen Sie Ihren Agenten mit benutzerdefinierten Headern auf

Übergeben Sie benutzerdefinierte Header, wenn Sie Ihren Agenten aufrufen, damit Ihr Agentencode über den Anforderungskontext darauf zugreifen kann.

Beispiel
AgentCore CLI

  1. Verwenden Sie das -H Flag, um benutzerdefinierte Header zu übergeben mit: agentcore invoke

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

    Sie können mehrere Header übergeben, indem Sie das -H Flag wiederholen:

    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. Verwenden Sie boto3 mit Event-Handlern, um Ihrem Agentenaufruf benutzerdefinierte Header hinzuzufügen. Weitere Informationen zu Botocore-Ereignissen finden Sie in der Dokumentation zu Botocore-Ereignissen.

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

Schritt 4: (Optional) Konfigurieren Sie die eingehende JWT-Authentifizierung

Um das für den OAuth-based eingehenden Zugriff verwendete JWT-Token an Ihren Agenten zu übergeben, konfigurieren Sie authorizerType und authorizerConfiguration in Ihrer Agentenkonfiguration.

Beispiel
AgentCore CLI

  1. Fügen Sie Ihrem Agenten die Authorizer-Konfiguration hinzu in: 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"
      ]
    }
  ]
}

    Bereitstellen, um die Konfiguration anzuwenden:

    agentcore deploy

    Bei dieser Konfiguration wird der Authorization Header eingehender Anfragen anhand Ihres OIDC-Anbieters validiert und an Ihren Agentencode weitergeleitet.

AWS SDK

  1. Informationen zum Einrichten eines Agenten mit eingehendem OAuth-Zugriff mithilfe des AWS SDK finden Sie unter Authentifizieren und autorisieren mit Inbound Auth und Outbound Auth.