--- title: Provedor de inferência url: https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/inference-provider description: Envie chamadas de modelo do seu servidor Claude Managed Agents auto-hospedado para Amazon Bedrock, Claude Models on Google Cloud (Google managed), Microsoft Foundry ou um gateway de modelos que você executa, em vez da Claude API. --- Para solicitar acesso ao Claude Managed Agents auto-hospedado, entre em contato com a equipe da sua conta na Anthropic. Por padrão, seu servidor envia as chamadas de modelo para a Claude API. Esta página mostra como enviá-las para um provedor de nuvem ou para um gateway de modelos que você executa. Para alterar o provedor: 1. Coloque o exemplo da seção do seu provedor nesta página no [arquivo de configurações](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#where-settings-go) do servidor. 2. Forneça ao servidor a credencial do provedor, como a mesma seção mostra. 3. Reinicie o servidor, como mostra [Onde ficam as configurações](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#where-settings-go). No Docker Compose, se a etapa 2 alterou `.env` ou `docker-compose.yml`, execute `docker compose up -d` em vez disso, porque uma reinicialização não os relê. 4. [Verifique o provedor](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/inference-provider#check-the-provider). A configuração `inference.provider` aceita estes valores: | `inference.provider` | As chamadas de modelo vão para | O servidor se autentica com | | -------------------- | ---------------------------------------------- | ------------------------------------------------- | | `anthropic` (padrão) | A Claude API | `ANTHROPIC_API_KEY` | | `bedrock` | Amazon Bedrock | Sua credencial da AWS | | `vertex` | Claude Models on Google Cloud (Google managed) | Google Application Default Credentials | | `foundry` | Microsoft Foundry | Uma chave de API do Foundry ou Microsoft Entra ID | | `gateway` | Um gateway de modelos que você executa | Uma chave ou token que seu gateway aceita | Com qualquer valor exceto `anthropic`, o servidor não precisa de chave de API da Claude API. Ele ignora `ANTHROPIC_API_KEY`, `ANTHROPIC_AUTH_TOKEN` e `ANTHROPIC_BASE_URL`. A única exceção é um [gateway de modelos](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/inference-provider#model-gateway) cuja chave você instrui o servidor a ler de uma dessas variáveis. Os agentes nomeiam modelos pelos seus IDs da Claude API, como `claude-opus-5-5`. O servidor traduz o ID, então uma definição de agente funciona sem alterações com qualquer provedor que sirva esse modelo. Algumas ferramentas e configurações de agente dependem do provedor. Consulte [Diferenças que dependem do seu provedor de inferência](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/differences#differences-that-depend-on-your-inference-provider). ## Fornecer ao servidor uma credencial de nuvem A forma como a credencial de um provedor de nuvem chega ao servidor depende da sua instalação: * **Docker Compose:** [Passe cada variável e arquivo para o servidor](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#pass-a-credential-to-the-compose-stack). * **Kubernetes:** O chart do servidor não passa variáveis da AWS, do Google Cloud nem do Azure, então use a workload identity da sua nuvem. Crie uma service account com a anotação de workload identity da sua nuvem e defina `server.serviceAccountName` com o nome dela. O `values.yaml` do chart nomeia a anotação. No Azure Kubernetes Service, defina também `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 ``` O servidor assina suas chamadas com o que quer que a cadeia de credenciais padrão do AWS SDK encontre no host. Isso pode ser uma task role ou uma pod identity. Em uma estação de trabalho, pode ser `AWS_PROFILE` ou `AWS_ACCESS_KEY_ID`. Habilite na conta os modelos que você usa. A identidade da AWS com a qual o servidor assina precisa destas permissões: * `bedrock:InvokeModel` e `bedrock:InvokeModelWithResponseStream` nos modelos e perfis de inferência que você usa. * `bedrock:ListFoundationModels` e `bedrock:ListInferenceProfiles` no recurso `*`. O servidor lê as listas de modelos do Amazon Bedrock, para que os agentes possam usar um modelo mais recente que a versão do seu servidor. Para dispensar isso, defina `inference.list_models: false`. Por padrão, o servidor coloca `us.anthropic.` antes de cada ID de modelo, o que nomeia um perfil de inferência entre regiões. Para usar outra família de perfis, descomente `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` é obrigatório. É um local do Google Cloud’s Agent Platform que oferece os modelos que você usa, ou `global`. `project_id` é o projeto no qual as chamadas são feitas e cobradas. O servidor usa Google Application Default Credentials: o arquivo indicado por `GOOGLE_APPLICATION_CREDENTIALS`, ou a conta de serviço que o Compute Engine, o Cloud Run ou o GKE anexa. Essa identidade precisa da role `roles/aiplatform.user` no projeto. O projeto precisa ter a API `aiplatform.googleapis.com` e os modelos Claude que você usa habilitados. ## Microsoft Foundry ```yaml inference: provider: foundry foundry: resource: my-resource #model_id_overrides: # claude-opus-5-5: team-a-opus ``` `resource` é o nome do seu recurso do Foundry, a primeira parte do hostname dele: `.services.ai.azure.com`. A credencial vem do ambiente do servidor: * **Uma chave de API do Foundry:** Defina `ANTHROPIC_FOUNDRY_API_KEY`. Na stack do Compose, [passe a variável para o servidor](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#pass-a-credential-to-the-compose-stack). No Kubernetes, coloque-a no Secret `cma-server-upstream`. Com `earlierNames: true` no seu arquivo de valores do servidor, o Secret tem outro nome. Encontre-o em [Kubernetes: os nomes dos seus objetos](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/upgrade#object-names). * **Microsoft Entra ID:** Deixe `ANTHROPIC_FOUNDRY_API_KEY` sem definir. O servidor então obtém um token para um service principal, uma workload identity no Azure Kubernetes Service ou uma managed identity. A identidade precisa de uma role do Azure no recurso do Foundry que permita chamadas às suas implantações de modelo. Para um service principal, defina `AZURE_TENANT_ID`, `AZURE_CLIENT_ID` e `AZURE_CLIENT_SECRET`. Uma requisição ao Foundry nomeia uma implantação, e o servidor envia o ID do modelo como o nome da implantação. Se uma implantação tiver outro nome, mapeie-a com [`model_id_overrides`](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/inference-provider#map-a-model-id-that-differs). ## Mapear um ID de modelo diferente Sua conta de nuvem pode ter um modelo com um ID diferente daquele que o servidor envia. Nesse caso, descomente as linhas `model_id_overrides` no exemplo desse provedor e mapeie o ID da Claude API para o ID da sua conta. Ambos os IDs devem nomear o mesmo modelo, porque o servidor constrói cada requisição para o modelo que o agente nomeia. ## Gateway de modelos Primeiro verifique quais requisições seu gateway aceita: * **As mesmas requisições que a Claude API, com uma credencial de longa duração:** Mantenha o provedor padrão. Defina `ANTHROPIC_BASE_URL` com o endereço do gateway e defina `ANTHROPIC_API_KEY` ou `ANTHROPIC_AUTH_TOKEN` com a credencial que o gateway espera. * **As mesmas requisições que a Claude API, mas com tokens de curta duração, uma credencial em outro cabeçalho ou seus próprios IDs de modelo:** Defina `inference.provider: gateway` com `format: anthropic-messages`. * **O formato InvokeModel do Amazon Bedrock:** Defina `inference.provider: gateway` com `format: bedrock-invoke`. * **O formato `rawPredict` do Claude Models on Google Cloud (Google managed):** Defina `inference.provider: gateway` com `format: vertex-raw-predict`. Este exemplo define `inference.provider: gateway` com `format: bedrock-invoke`, para um gateway que recebe uma chave de longa duração. Coloque a chave em uma variável de ambiente e informe o nome da variável, nunca o valor: ```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` é a rota de modelo do gateway. `{model}` marca onde o ID do modelo entra. A URL deve ser `https://` e terminar em `/invoke`. * `model_map` mapeia cada ID de modelo que um agente pode nomear para o ID que o gateway espera. O servidor recusa um modelo que não tenha entrada. * `send_as` nomeia o cabeçalho que carrega a chave. Sem ele, o servidor envia `Authorization: Bearer `. * Na stack do Compose, [passe a variável](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#pass-a-credential-to-the-compose-stack) para o servidor. * No Kubernetes, o chart do servidor não pode passar uma variável sua. Ele passa `ANTHROPIC_AUTH_TOKEN`, que lê do Secret `cma-server-upstream`, então use esse nome: 1. Defina `env: { var: ANTHROPIC_AUTH_TOKEN }`. 2. Coloque a chave do gateway no Secret `cma-server-upstream`, com o nome `ANTHROPIC_AUTH_TOKEN`. Com `earlierNames: true` no seu arquivo de valores do servidor, o Secret tem outro nome. Encontre-o em [Kubernetes: os nomes dos seus objetos](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/upgrade#object-names). Para `format: anthropic-messages`, substitua o bloco `gateway` por este: ```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" ``` Aqui, `url` é a URL completa da rota Messages do gateway, sem `{model}`. Para `format: vertex-raw-predict`, substitua o bloco `gateway` por este: ```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" ``` Aqui, `url` é a rota `rawPredict` do gateway, e ela deve terminar em `/{model}:rawPredict`. Um valor de `model_map` não pode conter dois-pontos. O bloco `credentials` permanece como está. O servidor envia a credencial do próprio gateway e não obtém nenhuma credencial do Google. A [referência de configuração](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#model-gateway) lista as outras configurações do gateway, como `streaming`, e a configuração `inference.headers`. ### Tokens de curta duração Se seu gateway recebe tokens de curta duração, substitua o bloco `credentials` por este: ```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" ``` O servidor então obtém cada token em duas etapas. Primeiro, ele chama um callback HTTP que você constrói. O callback retorna uma asserção, uma declaração assinada que geralmente é um “JSON Web Token” (token web JSON), ou JWT. Em seguida, o servidor troca a asserção no seu endpoint de token OAuth pelo token de acesso que ele envia ao gateway. * `auth` é como o servidor se autentica no callback. O exemplo usa um certificado de cliente. Para usar um bearer token que o servidor lê de um arquivo, defina `auth: { type: bearer_file, token_file: /etc/callback/token }`. * `exchange` nomeia seu endpoint de token OAuth. O servidor envia a esse endpoint apenas `grant_type` e a asserção, sem client ID nem secret. * Se seu endpoint de token precisar de mais do que isso, omita `exchange`. Faça seu callback obter o próprio token de acesso e retorná-lo no campo `assertion`, que o servidor então envia ao gateway. * No Kubernetes, coloque os arquivos de certificado em um Secret, informe-o em `server.extensionFiles.secretName` do chart e aponte `cert_file` e `key_file` para `/run/cma-server/extension-files/`. O servidor envia ao callback uma requisição `POST` com este corpo: ```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` é o chamador que criou a sessão. Para um chamador de [single sign-on](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configure#single-sign-on), `issuer` é o `issuer_url` desse chamador, e `subject` é o subject do chamador. Para a chave de API do servidor, `principal` é `{"issuer": "cma", "subject": "server"}`. Faça o callback ignorar campos que ele não conhece. O callback responde com status `200` e este corpo: ```json { "assertion": "", "reuse": "session" } ``` `reuse` diz quais sessões podem usar o token. Com `session`, o padrão, apenas a sessão da requisição pode, o que é adequado para um token que identifica um usuário. Com `deployment`, as sessões compartilham o token, então retorne `deployment` apenas para um token que identifica sua organização e nenhuma pessoa. Se o callback ou o endpoint de token falhar, o turno termina com um evento `session.error` do tipo `model_request_failed_error`, e a sessão continua utilizável. O motivo está no log do servidor, em uma linha que contém `credential supplier failed`. Se a resposta do endpoint de token não tiver `expires_in` e o token não tiver uma claim `exp`, o servidor envia o token, mas não o armazena. Ele então solicita outro token em cada chamada de modelo. Para as outras configurações, como `renew_before` e `ca_file`, consulte as tabelas da Referência de configuração de [configurações do gateway de modelos](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#model-gateway) e [configurações de tokens de curta duração](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#short-lived-gateway-tokens). ### Tokens do Microsoft Entra ID Se seu gateway verifica tokens do Microsoft Entra ID com base no próprio registro de aplicativo, substitua o bloco `credentials` por este: ```yaml inference: credentials: supplier: azure azure: { scope: "api://11111111-2222-3333-4444-555555555555/.default" } ``` `scope` é o URI do ID do aplicativo ou o ID do aplicativo do registro de aplicativo do gateway, seguido de `/.default`. Informe apenas o próprio registro do gateway. Um token para outro recurso permitiria que quem executa o gateway agisse como o servidor nesse recurso. O token é emitido para a própria identidade do Azure do servidor, configurada como para o Microsoft Entra ID em [Microsoft Foundry](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/inference-provider#microsoft-foundry). Se o registro exigir uma função de aplicativo, atribua essa função à identidade antes de iniciar o servidor. Uma atribuição posterior só tem efeito quando o servidor obtém outro token. O token nomeia essa identidade e nenhuma pessoa, então um gateway que precisa saber qual pessoa está chamando precisa de `oauth_exchange`. Execute um turno pelo seu gateway, sob a identidade que seus servidores usarão, antes de depender deste fornecedor. ## Verificar o provedor Depois de alterar as configurações e reiniciar o servidor, procure esta linha no log do servidor. Ela indica que o servidor encontrou uma credencial para o provedor: ```text wrap level=INFO msg="upstream credential resolved" provider=bedrock ``` A linha não prova que sua conta tem um modelo habilitado. Um modelo ausente aparece como um `session.error` no primeiro turno que o utiliza. Um gateway que você informa em `ANTHROPIC_BASE_URL` pode rejeitar o campo ou o cabeçalho de [fallback do lado do servidor](https://platform.claude.com/docs/pt-BR/build-with-claude/refusals-and-fallback#server-side-fallback). Se todo turno falhar por esse motivo, defina `inference.model_fallback: false` no [arquivo de configurações](https://platform.claude.com/docs/pt-BR/managed-agents/self-hosted/configuration-reference#where-settings-go).