Provedor de inferência

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 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. 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.

A configuração inference.provider aceita estes valores:

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 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.

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.
• 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

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)

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

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: <resource>.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. 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.
• 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.

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:

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 <key>.
• Na stack do Compose, passe a variável 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.

Para format: anthropic-messages, substitua o bloco gateway por este:

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:

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 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:

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:

{
  "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, 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:

{ "assertion": "<signed JWT>", "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 e configurações de tokens de curta duração.

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:

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. 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:

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. Se todo turno falhar por esse motivo, defina inference.model_fallback: false no arquivo de configurações.