--- title: 추론 제공자 url: https://platform.claude.com/docs/ko/managed-agents/self-hosted/inference-provider description: 자체 호스팅 Claude Managed Agents 서버의 모델 호출을 Claude API 대신 Amazon Bedrock, Claude Models on Google Cloud (Google managed), Microsoft Foundry 또는 직접 운영하는 모델 게이트웨이로 보냅니다. --- 자체 호스팅 Claude Managed Agents에 대한 접근 권한을 요청하려면 Anthropic 계정 팀에 문의하세요. 기본적으로 서버는 모델 호출을 Claude API로 보냅니다. 이 페이지에서는 모델 호출을 클라우드 제공자 또는 직접 운영하는 모델 게이트웨이로 보내는 방법을 설명합니다. 제공자를 변경하려면 다음을 수행하세요. 1. 이 페이지에서 사용하는 제공자 섹션의 샘플을 서버의 [설정 파일](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configuration-reference#where-settings-go)에 넣으세요. 2. 같은 섹션에 나와 있는 대로 서버에 제공자의 자격 증명을 제공하세요. 3. [설정 위치](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configuration-reference#where-settings-go)에 나와 있는 대로 서버를 다시 시작하세요. Docker Compose에서 2단계로 `.env` 또는 `docker-compose.yml`을 변경했다면, 다시 시작해도 해당 파일을 다시 읽지 않으므로 대신 `docker compose up -d`를 실행하세요. 4. [제공자를 확인하세요](https://platform.claude.com/docs/ko/managed-agents/self-hosted/inference-provider#check-the-provider). `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`을 무시합니다. 단, 서버가 이 변수 중 하나에서 키를 읽도록 지정한 [모델 게이트웨이](https://platform.claude.com/docs/ko/managed-agents/self-hosted/inference-provider#model-gateway)는 예외입니다. 에이전트는 `claude-opus-5-5`와 같은 Claude API ID로 모델을 지정합니다. 서버가 ID를 변환하므로, 에이전트 정의는 해당 모델을 제공하는 어떤 제공자에서도 변경 없이 동작합니다. 일부 도구와 에이전트 설정은 제공자에 따라 달라집니다. [추론 제공자에 따라 달라지는 차이점](https://platform.claude.com/docs/ko/managed-agents/self-hosted/differences#differences-that-depend-on-your-inference-provider)을 참조하세요. ## 서버에 클라우드 자격 증명 제공하기 클라우드 제공자의 자격 증명이 서버에 전달되는 방식은 설치 방식에 따라 다릅니다. * **Docker Compose:** [각 변수와 파일을 서버에 전달하세요](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configuration-reference#pass-a-credential-to-the-compose-stack). * **Kubernetes:** 서버 차트는 AWS, Google Cloud 또는 Azure 변수를 전달하지 않으므로 클라우드의 workload identity를 사용하세요. 클라우드의 workload identity 어노테이션이 지정된 서비스 계정을 생성하고, `server.serviceAccountName`을 해당 서비스 계정 이름으로 설정하세요. 해당 어노테이션은 차트의 `values.yaml`에 명시되어 있습니다. Azure Kubernetes Service에서는 `server.azureWorkloadIdentity: true`도 설정하세요. ## Amazon Bedrock ```yaml 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) ```yaml 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 ```yaml inference: provider: foundry foundry: resource: my-resource #model_id_overrides: # claude-opus-5-5: team-a-opus ``` `resource`는 Foundry 리소스의 이름으로, 호스트 이름의 첫 부분인 `.services.ai.azure.com`에 해당합니다. 자격 증명은 서버의 환경에서 가져옵니다. * **Foundry API 키:** `ANTHROPIC_FOUNDRY_API_KEY`를 설정하세요. Compose 스택에서는 [변수를 서버에 전달하세요](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configuration-reference#pass-a-credential-to-the-compose-stack). Kubernetes에서는 `cma-server-upstream` Secret에 넣으세요. 서버 values 파일에 `earlierNames: true`가 있으면 해당 Secret의 이름이 다릅니다. [Kubernetes: 객체의 이름](https://platform.claude.com/docs/ko/managed-agents/self-hosted/upgrade#object-names)에서 확인하세요. * **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`](https://platform.claude.com/docs/ko/managed-agents/self-hosted/inference-provider#map-a-model-id-that-differs)로 매핑하세요. ## 다른 모델 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`를 설정합니다. 키를 환경 변수에 넣고, 값이 아닌 변수 이름을 지정하세요. ```yaml 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 `를 보냅니다. * Compose 스택에서는 서버에 [변수를 전달하세요](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configuration-reference#pass-a-credential-to-the-compose-stack). * 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: 객체의 이름](https://platform.claude.com/docs/ko/managed-agents/self-hosted/upgrade#object-names)에서 확인하세요. `format: anthropic-messages`의 경우 `gateway` 블록을 다음으로 교체하세요. ```yaml 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` 블록을 다음으로 교체하세요. ```yaml 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 자격 증명은 가져오지 않습니다. [구성 레퍼런스](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configuration-reference#model-gateway)에는 `streaming`, `inference.headers` 설정 등 게이트웨이의 기타 설정이 나열되어 있습니다. ### 단기 토큰 게이트웨이가 단기 토큰을 받는다면 `credentials` 블록을 다음으로 교체하세요. ```yaml 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` 요청을 보냅니다. ```json { "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`은 세션을 생성한 호출자입니다. [싱글 사인온](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configure#single-sign-on) 호출자의 경우 `issuer`는 해당 호출자의 `issuer_url`이고, `subject`는 호출자의 subject입니다. 서버 API 키의 경우 `principal`은 `{"issuer": "cma", "subject": "server"}`입니다. 콜백이 알지 못하는 필드는 무시하도록 하세요. 콜백은 상태 `200`과 다음 본문으로 응답합니다. ```json { "assertion": "", "reuse": "session" } ``` `reuse`는 어떤 세션이 토큰을 사용할 수 있는지를 나타냅니다. 기본값인 `session`을 사용하면 요청에 포함된 세션만 사용할 수 있으며, 이는 한 사용자를 지정하는 토큰에 적합합니다. `deployment`를 사용하면 세션들이 토큰을 공유하므로, 개인이 아닌 조직을 지정하는 토큰에 대해서만 `deployment`를 반환하세요. 콜백이나 토큰 엔드포인트가 실패하면, 해당 턴은 `model_request_failed_error` 유형의 `session.error` 이벤트로 종료되며 세션은 계속 사용할 수 있습니다. 원인은 서버 로그에서 `credential supplier failed`가 포함된 줄에 있습니다. 토큰 엔드포인트의 응답에 `expires_in`이 없고 토큰에 `exp` 클레임이 없으면, 서버는 토큰을 보내지만 저장하지는 않습니다. 그러면 서버는 모델을 호출할 때마다 다른 토큰을 요청합니다. `renew_before`, `ca_file` 등 기타 설정은 구성 레퍼런스의 [모델 게이트웨이 설정](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configuration-reference#model-gateway) 및 [단기 토큰 설정](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configuration-reference#short-lived-gateway-tokens) 표를 참조하세요. ### Microsoft Entra ID 토큰 게이트웨이가 자체 앱 등록을 기준으로 Microsoft Entra ID 토큰을 확인한다면 `credentials` 블록을 다음으로 교체하세요. ```yaml inference: credentials: supplier: azure azure: { scope: "api://11111111-2222-3333-4444-555555555555/.default" } ``` `scope`는 게이트웨이 앱 등록의 애플리케이션 ID URI 또는 애플리케이션 ID 뒤에 `/.default`를 붙인 값입니다. 게이트웨이 자체의 등록만 지정하세요. 다른 리소스용 토큰을 지정하면 게이트웨이를 운영하는 누구든 해당 리소스에서 서버로 행세할 수 있게 됩니다. 토큰은 [Microsoft Foundry](https://platform.claude.com/docs/ko/managed-agents/self-hosted/inference-provider#microsoft-foundry)에서 Microsoft Entra ID용으로 설정한 것과 같은 방식으로 설정된 서버 자체의 Azure ID에 발급됩니다. 등록에 앱 역할이 필요하다면 서버를 시작하기 전에 해당 역할을 ID에 할당하세요. 나중에 할당한 역할은 서버가 다른 토큰을 가져올 때에만 적용됩니다. 토큰은 해당 ID를 지정할 뿐 어떤 개인도 지정하지 않으므로, 어떤 사람이 호출하는지 알아야 하는 게이트웨이에는 `oauth_exchange`가 필요합니다. 이 공급자에 의존하기 전에, 서버가 사용할 ID로 여러분의 게이트웨이를 통해 한 턴을 실행해 보세요. ## 제공자 확인 설정을 변경하고 서버를 다시 시작한 후, 서버 로그에서 다음 줄을 찾으세요. 이 줄은 서버가 제공자에 대한 자격 증명을 찾았다는 의미입니다. ```text wrap level=INFO msg="upstream credential resolved" provider=bedrock ``` 이 줄이 계정에서 모델이 활성화되어 있음을 보장하지는 않습니다. 모델이 없으면 해당 모델을 사용하는 첫 번째 턴에서 `session.error`로 나타납니다. `ANTHROPIC_BASE_URL`에 지정한 게이트웨이는 [서버 측 폴백](https://platform.claude.com/docs/ko/build-with-claude/refusals-and-fallback#server-side-fallback) 필드나 헤더를 거부할 수 있습니다. 이 때문에 모든 턴이 실패한다면 [설정 파일](https://platform.claude.com/docs/ko/managed-agents/self-hosted/configuration-reference#where-settings-go)에서 `inference.model_fallback: false`를 설정하세요.