# Amazon Bedrock AgentCore 런타임에 사용자 지정 헤더 전달
<a name="runtime-header-allowlist"></a>

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

Amazon Bedrock AgentCore 런타임을 사용하면 헤더가 다음 기준을 충족하는 경우 요청의 헤더를 에이전트 코드에 전달할 수 있습니다.
+ 헤더 이름은 유효한 HTTP 헤더(영숫자, 하이픈 및 밑줄)이며 [제한된 헤더](#runtime-header-restrictions) 목록에 없습니다.
+ 로 시작하는 헤더`x-amz-`는 허용되지 않습니다( AWS SigV4 서명용으로 예약됨).
+ 접두사가 붙은 헤더를 제외하고 `X-Amzn-Bedrock-AgentCore-Runtime-Custom-` 로 시작하는 헤더`x-amzn-`는 허용되지 않습니다.
+ `Authorization` 헤더를 사용하려면 OAuth 기반 인바운드 액세스를 `customJWTAuthorizer` 위해 에이전트 런타임을 로 구성해야 합니다.
+ 헤더 값의 크기는 4KB 이하입니다.
+ 런타임당 최대 20개의 헤더를 구성할 수 있습니다.
+ 헤더 이름은 대/소문자를 구분하지 않으며 중복(대/소문자를 구분하지 않는 비교)은 허용되지 않습니다.

## 제한된 헤더
<a name="runtime-header-restrictions"></a>

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


| 카테고리 | 헤더 | 
| --- | --- | 
| 인증 및 권한 부여 | 프록시 권한 부여, 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단계: 에이전트 생성
<a name="create-agent-headers"></a>

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단계: 사용자 지정 헤더를 사용하여 에이전트 구성 및 배포
<a name="deploy-agentcore-runtime"></a>

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

**Example**  

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를 사용하여 호출하려는 경우 필요합니다.

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단계: 사용자 지정 헤더를 사용하여 에이전트 간접 호출
<a name="invoke-custom-headers"></a>

에이전트 코드가 요청 컨텍스트를 통해 액세스할 수 있도록 에이전트를 호출할 때 사용자 지정 헤더를 전달합니다.

**Example**  

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"
   ```

1. 이벤트 핸들러와 함께 boto3를 사용하여 에이전트 호출에 사용자 지정 헤더를 추가합니다. botocore 이벤트에 대한 자세한 내용은 [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)))
   ```

## 4단계: (선택 사항) 인바운드 JWT 인증 구성
<a name="pass-jwt-token"></a>

OAuth 기반 인바운드 액세스에 사용되는 JWT 토큰을 에이전트에 전달하려면 에이전트 구성`authorizerConfiguration`에서 `authorizerType` 및를 구성합니다.

**Example**  

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 공급자에 대해 검증되고 에이전트 코드로 전달됩니다.

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