Managed Agents엔터프라이즈 구성

추론 제공자

자체 호스팅 Claude Managed Agents 서버의 모델 호출을 Claude API 대신 Amazon Bedrock, Claude Models on Google Cloud (Google managed), Microsoft Foundry 또는 직접 운영하는 모델 게이트웨이로 보냅니다.

기본적으로 서버는 모델 호출을 Claude API로 보냅니다. 이 페이지에서는 모델 호출을 클라우드 제공자 또는 직접 운영하는 모델 게이트웨이로 보내는 방법을 설명합니다. 제공자를 변경하려면 다음을 수행하세요.

이 페이지에서 사용하는 제공자 섹션의 샘플을 서버의 설정 파일에 넣으세요.
같은 섹션에 나와 있는 대로 서버에 제공자의 자격 증명을 제공하세요.
설정 위치에 나와 있는 대로 서버를 다시 시작하세요. Docker Compose에서 2단계로 .env 또는 docker-compose.yml을 변경했다면, 다시 시작해도 해당 파일을 다시 읽지 않으므로 대신 docker compose up -d를 실행하세요.
제공자를 확인하세요.

inference.provider 설정은 다음 값을 가집니다.

`inference.provider`	모델 호출 대상	서버 인증 수단
`anthropic` (기본값)	Claude API	`ANTHROPIC_API_KEY`
`bedrock`	Amazon Bedrock	AWS 자격 증명
`vertex`	Claude Models on Google Cloud (Google managed)	Google Application Default Credentials
`foundry`	Microsoft Foundry	Foundry API 키 또는 Microsoft Entra ID
`gateway`	직접 운영하는 모델 게이트웨이	게이트웨이가 허용하는 키 또는 토큰

anthropic을 제외한 모든 값에서 서버는 Claude API 키가 필요하지 않습니다. 서버는 ANTHROPIC_API_KEY, ANTHROPIC_AUTH_TOKEN, ANTHROPIC_BASE_URL을 무시합니다. 단, 서버가 이 변수 중 하나에서 키를 읽도록 지정한 모델 게이트웨이는 예외입니다.

에이전트는 claude-opus-5-5와 같은 Claude API ID로 모델을 지정합니다. 서버가 ID를 변환하므로, 에이전트 정의는 해당 모델을 제공하는 어떤 제공자에서도 변경 없이 동작합니다.

일부 도구와 에이전트 설정은 제공자에 따라 달라집니다. 추론 제공자에 따라 달라지는 차이점을 참조하세요.

서버에 클라우드 자격 증명 제공하기

클라우드 제공자의 자격 증명이 서버에 전달되는 방식은 설치 방식에 따라 다릅니다.

Docker Compose: 각 변수와 파일을 서버에 전달하세요.
Kubernetes: 서버 차트는 AWS, Google Cloud 또는 Azure 변수를 전달하지 않으므로 클라우드의 workload identity를 사용하세요. 클라우드의 workload identity 어노테이션이 지정된 서비스 계정을 생성하고, server.serviceAccountName을 해당 서비스 계정 이름으로 설정하세요. 해당 어노테이션은 차트의 values.yaml에 명시되어 있습니다. Azure Kubernetes Service에서는 server.azureWorkloadIdentity: true도 설정하세요.

Amazon Bedrock

inference:
  provider: bedrock
  region: us-east-1
  #model_id_prefix: global.anthropic.
  #model_id_overrides:
  #  claude-opus-5-5: us.anthropic.claude-opus-5-5

서버는 AWS SDK의 기본 자격 증명 체인이 호스트에서 찾은 자격 증명으로 호출에 서명합니다. 이는 태스크 역할이나 pod identity일 수 있습니다. 워크스테이션에서는 AWS_PROFILE 또는 AWS_ACCESS_KEY_ID일 수 있습니다.

계정에서 사용하는 모델을 활성화하세요. 서버가 서명에 사용하는 AWS ID에는 다음 권한이 필요합니다.

사용하는 모델과 추론 프로필에 대한 bedrock:InvokeModel 및 bedrock:InvokeModelWithResponseStream.
리소스 *에 대한 bedrock:ListFoundationModels 및 bedrock:ListInferenceProfiles. 서버는 에이전트가 서버 릴리스보다 최신인 모델을 사용할 수 있도록 Amazon Bedrock의 모델 목록을 읽습니다. 이를 생략하려면 inference.list_models: false를 설정하세요.

기본적으로 서버는 각 모델 ID 앞에 us.anthropic.을 붙이며, 이는 교차 리전 추론 프로필을 지정합니다. 다른 프로필 계열을 사용하려면 model_id_prefix의 주석을 해제하세요.

Claude Models on Google Cloud (Google managed)

inference:
  provider: vertex
  region: us-east5
  project_id: my-project
  #model_id_overrides:
  #  claude-haiku-4-5: claude-haiku-4-5@20251001

region은 필수입니다. 사용하는 모델을 제공하는 Google Cloud’s Agent Platform의 위치이거나 global입니다. project_id는 호출이 이루어지고 비용이 청구되는 프로젝트입니다.

서버는 Google Application Default Credentials를 사용합니다. 즉, GOOGLE_APPLICATION_CREDENTIALS가 가리키는 파일이나 Compute Engine, Cloud Run 또는 GKE가 연결하는 서비스 계정입니다. 해당 ID에는 프로젝트에 대한 roles/aiplatform.user 역할이 필요합니다. 프로젝트에서는 aiplatform.googleapis.com API와 사용하는 Claude 모델이 활성화되어 있어야 합니다.

Microsoft Foundry

inference:
  provider: foundry
  foundry:
    resource: my-resource
  #model_id_overrides:
  #  claude-opus-5-5: team-a-opus

resource는 Foundry 리소스의 이름으로, 호스트 이름의 첫 부분인 <resource>.services.ai.azure.com에 해당합니다.

자격 증명은 서버의 환경에서 가져옵니다.

Foundry API 키: ANTHROPIC_FOUNDRY_API_KEY를 설정하세요. Compose 스택에서는 변수를 서버에 전달하세요. Kubernetes에서는 cma-server-upstream Secret에 넣으세요. 서버 values 파일에 earlierNames: true가 있으면 해당 Secret의 이름이 다릅니다. Kubernetes: 객체의 이름에서 확인하세요.
Microsoft Entra ID: ANTHROPIC_FOUNDRY_API_KEY를 설정하지 않은 상태로 두세요. 그러면 서버는 서비스 주체, Azure Kubernetes Service의 workload identity 또는 managed identity에 대한 토큰을 가져옵니다. 해당 ID에는 Foundry 리소스에서 모델 배포 호출을 허용하는 Azure 역할이 필요합니다. 서비스 주체의 경우 AZURE_TENANT_ID, AZURE_CLIENT_ID, AZURE_CLIENT_SECRET을 설정하세요.

Foundry에 대한 요청은 배포를 지정하며, 서버는 모델 ID를 배포 이름으로 보냅니다. 배포의 이름이 다르다면 model_id_overrides로 매핑하세요.

다른 모델 ID 매핑하기

클라우드 계정에는 서버가 보내는 ID와 다른 ID로 모델이 있을 수 있습니다. 이 경우 해당 제공자 샘플에서 model_id_overrides 줄의 주석을 해제하고, Claude API ID를 계정의 ID에 매핑하세요. 서버는 에이전트가 지정한 모델에 맞게 각 요청을 구성하므로, 두 ID는 같은 모델을 지정해야 합니다.

모델 게이트웨이

먼저 게이트웨이가 어떤 요청을 허용하는지 확인하세요.

하나의 장기 자격 증명을 사용하는, Claude API와 동일한 요청: 기본 제공자를 유지하세요. ANTHROPIC_BASE_URL을 게이트웨이 주소로 설정하고, ANTHROPIC_API_KEY 또는 ANTHROPIC_AUTH_TOKEN을 게이트웨이가 요구하는 자격 증명으로 설정하세요.
Claude API와 동일하지만 단기 토큰, 다른 헤더의 자격 증명 또는 자체 모델 ID를 사용하는 요청: format: anthropic-messages와 함께 inference.provider: gateway를 설정하세요.
Amazon Bedrock의 InvokeModel 형식: format: bedrock-invoke와 함께 inference.provider: gateway를 설정하세요.
Claude Models on Google Cloud (Google managed)의 rawPredict 형식: format: vertex-raw-predict와 함께 inference.provider: gateway를 설정하세요.

이 샘플은 하나의 장기 키를 받는 게이트웨이용으로, format: bedrock-invoke와 함께 inference.provider: gateway를 설정합니다. 키를 환경 변수에 넣고, 값이 아닌 변수 이름을 지정하세요.

inference:
  provider: gateway
  gateway:
    url: "https://llm-gateway.example.com/v1/model/{model}/invoke"
    format: bedrock-invoke
    # Quote every model_map value.
    model_map:
      claude-opus-5-5: "us.anthropic.claude-opus-5-5"
      claude-sonnet-5: "us.anthropic.claude-sonnet-5"
  credentials:
    supplier: env
    env: { var: LLM_GATEWAY_KEY }
    send_as: { header: x-api-key }

url은 게이트웨이의 모델 경로입니다. {model}은 모델 ID가 들어갈 위치를 나타냅니다. URL은 https://여야 하며 /invoke로 끝나야 합니다.
model_map은 에이전트가 지정할 수 있는 각 모델 ID를 게이트웨이가 요구하는 ID에 매핑합니다. 서버는 항목이 없는 모델을 거부합니다.
send_as는 키를 전달하는 헤더의 이름을 지정합니다. 이를 지정하지 않으면 서버는 Authorization: Bearer <key>를 보냅니다.
Compose 스택에서는 서버에 변수를 전달하세요.
Kubernetes에서는 서버 차트가 사용자 정의 변수를 전달할 수 없습니다. 하지만 cma-server-upstream Secret에서 읽는 ANTHROPIC_AUTH_TOKEN은 전달하므로, 해당 이름을 사용하세요.
1. env: { var: ANTHROPIC_AUTH_TOKEN }을 설정하세요.
2. 게이트웨이의 키를 cma-server-upstream Secret에 ANTHROPIC_AUTH_TOKEN이라는 이름으로 넣으세요. 서버 values 파일에 earlierNames: true가 있으면 해당 Secret의 이름이 다릅니다. Kubernetes: 객체의 이름에서 확인하세요.

format: anthropic-messages의 경우 gateway 블록을 다음으로 교체하세요.

inference:
  gateway:
    url: "https://llm-gateway.example.com/v1/messages"
    format: anthropic-messages
    # Quote every model_map value.
    model_map:
      claude-opus-5-5: "corp-claude-opus"
      claude-sonnet-5: "corp-claude-sonnet"

여기서 url은 {model}이 없는, 게이트웨이 Messages 경로의 전체 URL입니다.

format: vertex-raw-predict의 경우 gateway 블록을 다음으로 교체하세요.

inference:
  gateway:
    url: "https://llm-gateway.example.com/v1/projects/my-project/locations/global/publishers/anthropic/models/{model}:rawPredict"
    format: vertex-raw-predict
    # Quote every model_map value.
    model_map:
      claude-opus-5-5: "claude-opus-5-5"
      claude-sonnet-5: "claude-sonnet-5"

여기서 url은 게이트웨이의 rawPredict 경로이며, /{model}:rawPredict로 끝나야 합니다. model_map 값에는 콜론을 포함할 수 없습니다. credentials 블록은 그대로 유지됩니다. 서버는 게이트웨이 자체의 자격 증명을 보내며 Google 자격 증명은 가져오지 않습니다.

구성 레퍼런스에는 streaming, inference.headers 설정 등 게이트웨이의 기타 설정이 나열되어 있습니다.

단기 토큰

게이트웨이가 단기 토큰을 받는다면 credentials 블록을 다음으로 교체하세요.

inference:
  credentials:
    supplier: oauth_exchange
    assertion:
      url: "https://app.example.com/assertion"
      auth: { type: mtls, cert_file: /etc/callback/client.pem, key_file: /etc/callback/client.key }
    exchange:
      token_url: "https://login.example.com/oauth2/token"
      grant_type: "urn:ietf:params:oauth:grant-type:jwt-bearer"

그러면 서버는 두 단계로 각 토큰을 가져옵니다. 먼저 여러분이 구축한 HTTP 콜백을 호출합니다. 콜백은 assertion, 즉 일반적으로 JSON Web Token(JWT)인 서명된 진술을 반환합니다. 그런 다음 서버는 OAuth 토큰 엔드포인트에서 assertion을 게이트웨이에 보낼 액세스 토큰으로 교환합니다.

auth는 서버가 콜백에 인증하는 방식입니다. 샘플은 클라이언트 인증서를 사용합니다. 서버가 파일에서 읽는 bearer 토큰을 사용하려면 auth: { type: bearer_file, token_file: /etc/callback/token }을 설정하세요.
exchange는 OAuth 토큰 엔드포인트를 지정합니다. 서버는 클라이언트 ID나 시크릿 없이 grant_type과 assertion만 해당 엔드포인트에 보냅니다.
토큰 엔드포인트에 그 이상의 정보가 필요하다면 exchange를 생략하세요. 콜백이 액세스 토큰 자체를 가져와 assertion 필드에 반환하도록 하세요. 그러면 서버가 해당 값을 게이트웨이에 보냅니다.
Kubernetes에서는 인증서 파일을 Secret에 넣고, 차트의 server.extensionFiles.secretName에 해당 Secret 이름을 지정한 다음, cert_file과 key_file이 /run/cma-server/extension-files/를 가리키도록 하세요.

서버는 콜백에 다음 본문으로 POST 요청을 보냅니다.

{
  "version": 1,
  "purpose": "inference",
  "session": {
    "id": "sesn_011CZkZAtmR3yMPDzynEDxu7",
    "agent_id": "agent_011CYm1BLqPXpQRk5khsSXrs",
    "environment_id": "env_01595EKxaaTTGwwY3kyXdtbs"
  },
  "principal": {
    "issuer": "https://login.example.com/oauth2/default",
    "subject": "00u1a2b3c4d5e6f7g8h9"
  },
  "request_id": "req_011CSHoEeqs5C35K2UUqR7Fy"
}

principal은 세션을 생성한 호출자입니다. 싱글 사인온 호출자의 경우 issuer는 해당 호출자의 issuer_url이고, subject는 호출자의 subject입니다. 서버 API 키의 경우 principal은 {"issuer": "cma", "subject": "server"}입니다. 콜백이 알지 못하는 필드는 무시하도록 하세요.

콜백은 상태 200과 다음 본문으로 응답합니다.

{ "assertion": "<signed JWT>", "reuse": "session" }

reuse는 어떤 세션이 토큰을 사용할 수 있는지를 나타냅니다. 기본값인 session을 사용하면 요청에 포함된 세션만 사용할 수 있으며, 이는 한 사용자를 지정하는 토큰에 적합합니다. deployment를 사용하면 세션들이 토큰을 공유하므로, 개인이 아닌 조직을 지정하는 토큰에 대해서만 deployment를 반환하세요.

콜백이나 토큰 엔드포인트가 실패하면, 해당 턴은 model_request_failed_error 유형의 session.error 이벤트로 종료되며 세션은 계속 사용할 수 있습니다. 원인은 서버 로그에서 credential supplier failed가 포함된 줄에 있습니다.

토큰 엔드포인트의 응답에 expires_in이 없고 토큰에 exp 클레임이 없으면, 서버는 토큰을 보내지만 저장하지는 않습니다. 그러면 서버는 모델을 호출할 때마다 다른 토큰을 요청합니다.

renew_before, ca_file 등 기타 설정은 구성 레퍼런스의 모델 게이트웨이 설정 및 단기 토큰 설정 표를 참조하세요.

Microsoft Entra ID 토큰

게이트웨이가 자체 앱 등록을 기준으로 Microsoft Entra ID 토큰을 확인한다면 credentials 블록을 다음으로 교체하세요.

inference:
  credentials:
    supplier: azure
    azure: { scope: "api://11111111-2222-3333-4444-555555555555/.default" }

scope는 게이트웨이 앱 등록의 애플리케이션 ID URI 또는 애플리케이션 ID 뒤에 /.default를 붙인 값입니다. 게이트웨이 자체의 등록만 지정하세요. 다른 리소스용 토큰을 지정하면 게이트웨이를 운영하는 누구든 해당 리소스에서 서버로 행세할 수 있게 됩니다.

토큰은 Microsoft Foundry에서 Microsoft Entra ID용으로 설정한 것과 같은 방식으로 설정된 서버 자체의 Azure ID에 발급됩니다. 등록에 앱 역할이 필요하다면 서버를 시작하기 전에 해당 역할을 ID에 할당하세요. 나중에 할당한 역할은 서버가 다른 토큰을 가져올 때에만 적용됩니다.

토큰은 해당 ID를 지정할 뿐 어떤 개인도 지정하지 않으므로, 어떤 사람이 호출하는지 알아야 하는 게이트웨이에는 oauth_exchange가 필요합니다. 이 공급자에 의존하기 전에, 서버가 사용할 ID로 여러분의 게이트웨이를 통해 한 턴을 실행해 보세요.

제공자 확인

설정을 변경하고 서버를 다시 시작한 후, 서버 로그에서 다음 줄을 찾으세요. 이 줄은 서버가 제공자에 대한 자격 증명을 찾았다는 의미입니다.

level=INFO msg="upstream credential resolved" provider=bedrock

이 줄이 계정에서 모델이 활성화되어 있음을 보장하지는 않습니다. 모델이 없으면 해당 모델을 사용하는 첫 번째 턴에서 session.error로 나타납니다.

ANTHROPIC_BASE_URL에 지정한 게이트웨이는 서버 측 폴백 필드나 헤더를 거부할 수 있습니다. 이 때문에 모든 턴이 실패한다면 설정 파일에서 inference.model_fallback: false를 설정하세요.

서버에 클라우드 자격 증명 제공하기

Amazon Bedrock

Claude Models on Google Cloud (Google managed)

Microsoft Foundry

다른 모델 ID 매핑하기

모델 게이트웨이

단기 토큰

Microsoft Entra ID 토큰

제공자 확인