View a markdown version of this page

Amazon Bedrock AgentCore 런타임에 사용자 지정 헤더 전달 - Amazon Bedrock AgentCore
제한된 헤더1단계: 에이전트 생성2단계: 사용자 지정 헤더를 사용하여 에이전트 구성 및 배포3단계: 사용자 지정 헤더를 사용하여 에이전트 간접 호출4단계: (선택 사항) 인바운드 JWT 인증 구성

Amazon Bedrock AgentCore 런타임에 사용자 지정 헤더 전달

사용자 지정 헤더를 사용하면 기본 요청 페이로드를 어수선하게 하지 않고도 애플리케이션의 컨텍스트 정보를 에이전트 코드에 직접 전달할 수 있습니다. 와 같은 웹후크 서명,와 같은 API 키X-Custom-Signature, X-Api-Key추적 컨텍스트 또는 세션 식별자를 포함하여 제한된 헤더 목록에 없는 유효한 HTTP 헤더를 전달할 수 있습니다. 에이전트가 사용자 지정 JWT 권한 부여자로 구성된 경우 JWT 기반 인증을 위해 Authorization 헤더를 전달할 수도 있습니다. 접두사가 인 헤더는 이전 버전과의 호환성을 위해 X-Amzn-Bedrock-AgentCore-Runtime-Custom- 계속 지원됩니다. 런타임당 최대 20개의 헤더를 구성할 수 있으며 각 헤더 값은 4KB로 제한됩니다.

Amazon Bedrock AgentCore 런타임을 사용하면 헤더가 다음 기준을 충족하는 경우 요청의 헤더를 에이전트 코드에 전달할 수 있습니다.

  • 헤더 이름은 유효한 HTTP 헤더(영숫자, 하이픈 및 밑줄)이며 제한된 헤더 목록에 없습니다.

  • 로 시작하는 헤더x-amz-는 허용되지 않습니다( AWS SigV4 서명용으로 예약됨).

  • 접두사가 붙은 헤더를 제외하고 X-Amzn-Bedrock-AgentCore-Runtime-Custom- 로 시작하는 헤더x-amzn-는 허용되지 않습니다.

  • Authorization 헤더를 사용하려면 OAuth 기반 인바운드 액세스를 customJWTAuthorizer 위해 에이전트 런타임을 로 구성해야 합니다.

  • 헤더 값의 크기는 4KB 이하입니다.

  • 런타임당 최대 20개의 헤더를 구성할 수 있습니다.

  • 헤더 이름은 대/소문자를 구분하지 않으며 중복(대/소문자를 구분하지 않는 비교)은 허용되지 않습니다.

제한된 헤더

보안을 유지하고 민감한 정보의 노출을 방지하기 위해 다음 헤더는 제한되며 전파를 위해 구성할 수 없습니다.

카테고리 헤더

인증 및 권한 부여

프록시 권한 부여, WWW 인증

콘텐츠 협상

수락, Accept-Charset, Accept-Encoding, Accept-Language, Content-Type, Content-Length, Content-Encoding, Content-Language, Content-Location, Content-Range

캐싱

캐시 제어, ETag, 만료, If-Match, If-Modified-Since, If-None-Match, If-Range, If-Unmodified-Since, Last-Modified, Pragma, Vary

연결 관리

연결, 연결 유지, 프록시 연결, 업그레이드

요청 컨텍스트

호스트, 사용자-에이전트, 참조자, 시작

범위/전송

범위, Accept-Ranges, Transfer-Encoding, TE, Trailer

서버 정보

서버, 날짜, 위치, 재시도 후

쿠키

Set-Cookie, 쿠키

보안

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

클라이언트 힌트

Accept-CH, Accept-CH-Lifetime, DPR, Width, Viewport-Width, Downlink, ECT, RTT, Save-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 가상 헤더

:method, :path, :scheme, :authority, :status

서버 푸시

링크

WebSocket

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

위에 나열된 제한된 헤더 외에도:

  • 로 시작하는 모든 헤더x-amz-는 제한됩니다(예: x-amz-security-token , 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)를 포함해야 합니다.

    를 실행하여 런타임 ID를 찾을 수 있습니다agentcore 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 인바운드 액세스로 에이전트를 설정하는 방법에 대한 자세한 내용은 인바운드 인증 및 아웃바운드 인증을 사용하여 인증 및 권한 부여를 참조하세요.