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 프로젝트를 생성한 다음 요청 헤더 허용 목록이 있는 에이전트를 추가합니다.

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

에이전트의 진입점 파일을 업데이트하여 요청 컨텍스트에서 사용자 지정 헤더에 액세스합니다.

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

2단계: 사용자 지정 헤더를 사용하여 에이전트 구성 및 배포

호출 시 사용자 지정 헤더가 에이전트 코드로 전달되도록 에이전트 런타임에서 요청 헤더 허용 목록을 구성합니다.

예
AgentCore CLI

  1. 1단계의 agentcore add agent 명령은의에 있는 런타임 구성runtimes에 허용 목록을 저장합니다agentcore/agentcore.json.

    에이전트를 배포합니다.

    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. JWT 인증을 사용하려면 1단계의 명령 대신 다음 agentcore add agent 명령을 실행합니다.

    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

    를 배포하여 구성을 적용합니다.

    agentcore deploy

    이 구성을 사용하면 수신 요청의 Authorization 헤더가 OIDC 공급자에 대해 검증되고 에이전트 코드로 전달됩니다.

AWS SDK

  1. AWS SDK를 사용하여 OAuth 인바운드 액세스로 에이전트를 설정하는 방법에 대한 자세한 내용은 인바운드 인증 및 아웃바운드 인증을 사용하여 인증 및 권한 부여를 참조하세요.