Bedrock AgentCore

Bedrock AgentCore

OpenAI 요청/응답 형식으로 Bedrock AgentCore를 호출해요.

출처: 문서

본문

개요 (Overview)

속성	설명
설명	Amazon Bedrock AgentCore는 호스팅된 agent runtimes에 직접 접근해 기반 모델로 에이전트 워크플로를 실행할 수 있게 해요
LiteLLM 라우트	bedrock/agentcore/{AGENT_RUNTIME_ARN}
공급자 문서	AWS Bedrock AgentCore

이 문서는 AgentCore Agents(agent runtimes)에 대한 설명이에요. LiteLLM에서 AgentCore MCP 서버를 사용하려면 MCP AWS SigV4 Auth 가이드를 참고하세요.

빠른 시작 (Quick Start)

LiteLLM용 모델 형식

LiteLLM으로 bedrock agent runtime을 호출하려면 다음 모델 형식을 사용해요. model=bedrock/agentcore/는 LiteLLM이 bedrock InvokeAgentRuntime API를 호출하도록 지시해요.

bedrock/agentcore/{AGENT_RUNTIME_ARN}

예시: bedrock/agentcore/arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent-runtime

Agent Runtime ARN은 AWS Bedrock 콘솔의 AgentCore에서 찾을 수 있어요.

LiteLLM Python SDK

기본 AgentCore Completion:

import litellm

# Make a completion request to your AgentCore runtime
response = litellm.completion(
    model="bedrock/agentcore/arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent-runtime",
    messages=[
        {
            "role": "user",
            "content": "Explain machine learning in simple terms"
        }
    ],
)
print(response.choices[0].message.content)
print(f"Usage: {response.usage}")

AgentCore 응답 스트리밍:

import litellm

# Stream responses from your AgentCore runtime
response = litellm.completion(
    model="bedrock/agentcore/arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent-runtime",
    messages=[
        {
            "role": "user",
            "content": "What are the key principles of software architecture?"
        }
    ],
    stream=True,
)

for chunk in response:
    if chunk.choices[0].delta.content:
        print(chunk.choices[0].delta.content, end="")

LiteLLM Proxy

1. config.yaml에서 모델 설정:

model_list:
  - model_name: agentcore-runtime-1
    litellm_params:
      model: bedrock/agentcore/arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent-runtime
      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_region_name: us-west-2
  - model_name: agentcore-runtime-2
    litellm_params:
      model: bedrock/agentcore/arn:aws:bedrock-agentcore:us-east-1:987654321098:runtime/production-runtime
      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_region_name: us-east-1

2. LiteLLM Proxy 시작:

litellm --config config.yaml

3. AgentCore runtimes에 요청:

curl (기본 요청):

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "agentcore-runtime-1",
    "messages": [
      {
        "role": "user",
        "content": "Summarize the main benefits of cloud computing"
      }
    ]
  }'

curl (스트리밍 요청):

curl http://localhost:4000/v1/chat/completions \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer ***" \
  -d '{
    "model": "agentcore-runtime-2",
    "messages": [
      {
        "role": "user",
        "content": "Explain the differences between SQL and NoSQL databases"
      }
    ],
    "stream": true
  }'

OpenAI Python SDK:

from openai import OpenAI

# Initialize client with your LiteLLM proxy URL
client = OpenAI(
    base_url="http://localhost:4000",
    api_key="your-litellm-api-key",
)

# Make a completion request to your AgentCore runtime
response = client.chat.completions.create(
    model="agentcore-runtime-1",
    messages=[
        {
            "role": "user",
            "content": "What are best practices for API design?"
        }
    ],
)
print(response.choices[0].message.content)

OpenAI SDK로 스트리밍:

from openai import OpenAI

client = OpenAI(
    base_url="http://localhost:4000",
    api_key="your-litellm-api-key",
)

# Stream AgentCore responses
stream = client.chat.completions.create(
    model="agentcore-runtime-2",
    messages=[
        {
            "role": "user",
            "content": "Describe the microservices architecture pattern"
        }
    ],
    stream=True,
)

for chunk in stream:
    if chunk.choices[0].delta.content is not None:
        print(chunk.choices[0].delta.content, end="")

공급자별 파라미터 (Provider-specific Parameters)

AgentCore는 런타임 호출을 커스터마이즈하는 추가 파라미터를 지원해요.

SDK:

from litellm import completion

response = litellm.completion(
    model="bedrock/agentcore/arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent-runtime",
    messages=[
        {
            "role": "user",
            "content": "Analyze this data and provide insights",
        }
    ],
    qualifier="production",  # PROVIDER-SPECIFIC: Runtime qualifier/version
    runtimeSessionId="session-abc-123",  # PROVIDER-SPECIFIC: Custom session ID
)

Proxy 설정:

model_list:
  - model_name: agentcore-runtime-prod
    litellm_params:
      model: bedrock/agentcore/arn:aws:bedrock-agentcore:us-west-2:123456789012:runtime/my-agent-runtime
      aws_access_key_id: os.environ/AWS_ACCESS_KEY_ID
      aws_secret_access_key: os.environ/AWS_SECRET_ACCESS_KEY
      aws_region_name: us-west-2
      qualifier: production

사용 가능한 파라미터

파라미터	타입	설명
qualifier	string	agent runtime의 특정 버전을 호출할 선택적 런타임 qualifier/version
runtimeSessionId	string	선택적 사용자 지정 세션 ID (33자 이상이어야 함). 제공하지 않으면 LiteLLM이 자동 생성

LiteLLM A2A Gateway

Bedrock AgentCore runtime을 LiteLLM Agent Gateway의 일급 A2A 에이전트로 등록해요. 이를 통해 에이전트별 RBAC, 접근 그룹, trace-ID 강제, x-a2a-{agent_name_or_id}-{header} 사용자별 패스스루 규칙을 다른 A2A 공급자와 동일한 표면으로 제공해요.

이 경로는 위의 chat-completions 호출과는 별개예요. 클라이언트에 따라 하나를 선택하세요:

AgentCore 호출 방식	사용 경로
model: bedrock/agentcore/<ARN>로 /v1/chat/completions	Chat completions (위에서 설명)
A2A JSON-RPC 2.0으로 POST /a2a/{agent_id} (message/send 또는 message/stream)	A2A Gateway (이 섹션)

1. 에이전트 등록

REST API:

curl -X POST http://localhost:4000/v1/agents \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "my-agentcore-runtime",
    "agent_card_params": {
      "name": "my-agentcore-runtime",
      "description": "Internal research agent",
      "url": "bedrock/agentcore/arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/my-runtime"
    },
    "litellm_params": {
      "custom_llm_provider": "bedrock",
      "aws_role_name": "arn:aws:iam::123456789012:role/LiteLLMAgentCoreInvoker",
      "aws_region_name": "us-east-1"
    }
  }'

UI: Agents → Add Agent로 이동 → 공급자로 Bedrock AgentCore 선택 → AgentCore Runtime ARN을 agent URL로 붙여넣기 → AWS 자격 증명 구성(또는 비워두면 proxy의 ambient credential chain 사용).

자격 증명 갱신/교체

litellm_params의 자격 증명 포함 필드(aws_access_key_id, aws_secret_access_key, aws_session_token, api_key 등)는 write-only예요. GET/POST/PUT/PATCH /v1/agents 응답과 Admin UI의 에이전트 편집 폼은 항상 이 필드들을 저장된 값 대신 redacted placeholder로 표시해요.

무관한 필드(이름, 설명, rate limits)를 편집하고 저장해도, 폼이 건드리지 않은 자격 증명 필드마다 placeholder를 왕복하더라도 저장된 자격 증명은 그대로 남아요. 자격 증명을 교체하려면 해당 필드에 새 값을 제출하면 즉시 적용되고 다시 에코되지 않아요. 필드를 빈 문자열로 제출하면 저장된 자격 증명이 지워져요 (예: proxy의 ambient AWS 자격 증명 체인으로 폴백).

2. A2A로 호출

curl -X POST http://localhost:4000/a2a/my-agentcore-runtime/message/send \
  -H "x-litellm-api-key: ***" \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": "1",
    "method": "message/send",
    "params": {
      "message": {
        "role": "user",
        "parts": [{"kind": "text", "text": "Summarize the latest clinical trial results"}],
        "messageId": "msg-1"
      }
    }
  }'

세션 격리

각 AgentCore runtime 세션은 고유한 microVM이에요. 같은 X-Amzn-Bedrock-AgentCore-Runtime-Session-Id를 재사용하면 대화 컨텍스트가 유지되고, 두 호출자를 한 세션에 섞으면 호출자 간 컨텍스트가 유출돼요. LiteLLM은 이 순서로 세션 id를 선택해요:

1. A2A 요청의 params.message.contextId — 호출 API 키로 범위가 지정되어 두 키가 같은 contextId에서 절대 충돌하지 않아요. 대화별 세션 격리에 권장되는 방식.
2. 에이전트 litellm_params의 runtimeSessionId(사용 가능한 파라미터 참고) — 요청에 contextId가 없을 때만 사용. contextId를 생략하는 모든 호출자가 이 하나의 세션을 공유해요.
3. 위 둘 다 없을 때 새로 생성된 id — 모든 요청이 각자 세션을 가지므로 다중 턴 컨텍스트가 보존되지 않아요.

대화를 여러 턴에 걸쳐 유지하려면 그 대화의 모든 message/send·message/stream 호출에 같은 contextId를 보내고, 새 대화나 최종 사용자마다 다른 contextId를 쓰세요.

AWS는 런타임 세션 id가 33-256자이길 요구해요. LiteLLM은 이를 확인하기 전에 contextId 앞에 호출 키의 16자 해시를 붙이므로, contextId 자체는 최소 16자여야 해요. UUID(36자)는 충분히 여유가 있어요. 그 범위를 벗어난 contextId(또는 설정된 runtimeSessionId)는 요청이 AWS에 도달하기 전에 HTTP 400과 JSON-RPC -32602 에러로 거부되며, 공유 세션으로 조용히 폴백되지 않아요.

인증 (Authentication)

AgentCore A2A 경로는 litellm_params의 내용에 따라 자동으로 선택되는 두 가지 outbound 인증 모드를 지원해요:

모드	발동 조건	AgentCore로 보내는 것
Bearer / JWT	litellm_params.api_key 설정 (어떤 값이든)	Authorization: Bearer *** — SigV4는 완전히 건너뜀
SigV4	litellm_params.api_key 미설정	전체 AWS 자격 증명 체인을 사용한 요청별 SigV4 서명

SigV4 자격 증명 해석

SigV4 모드가 활성화되면 자격 증명은 이 우선순위로 해석돼요:

• aws_web_identity_token + aws_role_name + aws_session_name → sts:AssumeRoleWithWebIdentity. 교차 계정 IRSA 경로.
• aws_role_name 단독 → sts:AssumeRole. proxy의 ambient 자격 증명(instance profile, IRSA, env vars)이 소스 신원. 세션 이름은 생략 시 자동 생성.
• aws_profile_name → boto3 프로필 로더(~/.aws/credentials)로 해석.
• aws_access_key_id + aws_secret_access_key + aws_session_token → 명시적 임시 자격 증명.
• aws_access_key_id + aws_secret_access_key + aws_region_name → 명시적 장기 자격 증명. 세 개 모두 설정되어야 함. aws_region_name이 없으면 이 분기는 건너뜀.
• 자격 증명 미설정 → boto3 기본 체인 (env vars, AWS_WEB_IDENTITY_TOKEN_FILE + AWS_ROLE_ARN으로 IRSA, instance metadata).

SigV4용 litellm_params의 인식 필드:

필드	설명
aws_role_name	STS로 assume할 IAM 역할 ARN
aws_session_name	AssumeRole 호출용 세션 이름 (생략 시 자동 생성)
aws_external_id	교차 계정 신뢰 정책용 sts:AssumeRole에 전달되는 ExternalId
aws_web_identity_token	AssumeRoleWithWebIdentity용 OIDC 토큰 (명시적 또는 AWS_WEB_IDENTITY_TOKEN_FILE env로 설정)
aws_profile_name	AWS CLI 프로필 이름
aws_sts_endpoint	사용자 지정 STS 엔드포인트 (VPC 엔드포인트, FIPS 엔드포인트)
aws_access_key_id / aws_secret_access_key / aws_session_token	명시적 자격 증명
aws_region_name	AWS 지역. 생략 시 agent_card_params.url의 runtime ARN에서 감지

EKS에서 IRSA

IAM Roles for Service Accounts를 쓰는 Kubernetes 배포에서는 명시적 자격 증명 구성이 필요 없어요. boto3 기본 체인이 pod 환경에서 AWS_WEB_IDENTITY_TOKEN_FILE과 AWS_ROLE_ARN을 자동으로 가져와요.

호출이 두 번째 역할을 assume하길 원하면(예: CloudTrail 귀속을 위해 pod 신원과 agent-invocation 신원 분리) IRSA를 aws_role_name과 결합해요. proxy pod의 IRSA 역할이 AssumeRole 호출의 소스 신원이 되고, assumed role의 CloudTrail 항목이 agent invocation을 반영해요.

curl -X POST http://localhost:4000/v1/agents \
  -H "Authorization: Bearer ***" \
  -H "Content-Type: application/json" \
  -d '{
    "agent_name": "production-runtime",
    "agent_card_params": {
      "name": "production-runtime",
      "url": "bedrock/agentcore/arn:aws:bedrock-agentcore:us-east-1:123456789012:runtime/prod"
    },
    "litellm_params": {
      "custom_llm_provider": "bedrock",
      "aws_role_name": "arn:aws:iam::123456789012:role/AgentCoreInvocationRole",
      "aws_session_name": "litellm-prod"
    }
  }'

사용자별 헤더 패스스루

표준 A2A 헤더 전달 메커니즘이 적용돼요. 세 가지 방법 모두 AgentCore와 동작해요:

• static_headers — 항상 AgentCore로 전송 (예: 사용자 지정 X-Tenant-Id)
• extra_headers — 관리자 구성의 클라이언트 헤더 허용 목록 전달
• x-a2a-{agent_name_or_id}-{header} 규칙 — 관리자 구성 없이 호출자 주도 전달

litellm_params가 처리하는 SigV4/Bearer 인증은 위의 에이전트 수준 헤더 전달과 별개예요. 인증 헤더는 AWS signer가 요청별로 계산하고, 사용자 패스스루 헤더는 서명 후 요청에 병합돼요.

RBAC 및 trace ID

모든 표준 A2A 컨트롤이 적용돼요:

• 에이전트별 RBAC — Agent Permission Management. 호출 키/팀이 AgentCore 에이전트에 권한이 없으면 HTTP 403 반환.
• 접근 그룹 — LiteLLM 대시보드에서 에이전트를 하나 이상의 접근 그룹으로 태그한 뒤 object_permission.agent_access_groups로 그룹을 팀이나 키에 부여.
• Trace ID 강제 — litellm_params에 require_trace_id_on_calls_to_agent: true를 설정해 모든 인바운드 호출에 x-litellm-trace-id를 요구.

더 알아보기 (Learn more)

• LiteLLM 개요
• LiteLLM Python SDK 사용법
• LiteLLM Proxy Server 설정
• 지원되는 공급업체 전체 목록