Pular para o conteúdo principal

​
Pré-requisitos

Antes de configurar Claude Code com Microsoft Foundry, certifique-se de que você tem:
  • Uma assinatura do Azure com acesso ao Microsoft Foundry
  • Permissões RBAC para criar recursos e implantações do Microsoft Foundry
  • Azure CLI instalado e configurado (opcional - necessário apenas se você não tiver outro mecanismo para obter credenciais)
Se você está implantando Claude Code para vários usuários, fixe suas versões de modelo antes de fazer o lançamento.

​
Configuração

​
  1. Provisionar recurso do Microsoft Foundry

Primeiro, crie um recurso Claude no Azure:
  1. Navegue até o portal do Microsoft Foundry
  2. Crie um novo recurso, anotando o nome do seu recurso
  3. Crie implantações para os modelos Claude, anotando o nome de implantação que você atribui a cada um; você definirá esses nomes como as variáveis de modelo na etapa 4:
    • Claude Opus
    • Claude Sonnet
    • Claude Haiku
    Quando você configura uma implantação, você também escolhe sua opção de hospedagem, que determina se a inferência é executada no Azure ou na infraestrutura da Anthropic.

​
  1. Configurar credenciais do Azure

Claude Code suporta três métodos de autenticação para Microsoft Foundry. Escolha o método que melhor se adequa aos seus requisitos de segurança:
  • Chave de API: você copia uma chave do portal do Microsoft Foundry e a define como ANTHROPIC_FOUNDRY_API_KEY
  • Microsoft Entra ID: Claude Code obtém tokens através da cadeia de credenciais padrão do Azure SDK, por exemplo de uma sessão az login, portanto não há chave de API para armazenar
  • Token de portador: outro processo obtém um token de acesso do Microsoft Entra ID e você o passa em ANTHROPIC_FOUNDRY_AUTH_TOKEN
Ao usar Microsoft Foundry, o comando /logout não está disponível, pois a autenticação é tratada através de credenciais do Azure.

​
Usar uma chave de API

Copie uma chave do portal do Microsoft Foundry e, em seguida, defina-a como uma variável de ambiente:
  1. Navegue até seu recurso no portal do Microsoft Foundry
  2. Abra a seção Endpoints e chaves
  3. Copie a Chave de API
  4. Defina a variável de ambiente, substituindo your-azure-api-key pela chave que você copiou:

​
Usar o Microsoft Entra ID

Deixe ANTHROPIC_FOUNDRY_API_KEY e ANTHROPIC_FOUNDRY_AUTH_TOKEN sem definir. Claude Code então usa a cadeia de credenciais padrão do Azure SDK. Isso suporta uma variedade de métodos para autenticar cargas de trabalho locais e remotas. Em uma máquina local, faça login com a Azure CLI:
Para as funções de que sua identidade precisa, consulte Configuração do Azure RBAC.

​
Usar um token de portador

Claude Code envia o valor de ANTHROPIC_FOUNDRY_AUTH_TOKEN em cada requisição como o cabeçalho Authorization: Bearer. Use esta opção quando outro processo, como um aplicativo host ou um script de login, já tiver obtido um token de acesso para você. Defina a variável para um token de portador que o Microsoft Entra ID emitiu para seu recurso:
ANTHROPIC_FOUNDRY_AUTH_TOKEN tem precedência sobre ANTHROPIC_FOUNDRY_API_KEY e sobre a cadeia de credenciais padrão.

​
  1. Configurar Claude Code

Defina as seguintes variáveis de ambiente para ativar Microsoft Foundry:
Defina ANTHROPIC_FOUNDRY_RESOURCE apenas com o nome do recurso, como my-resource. Claude Code recusa uma URL ou nome de host quando você envia uma mensagem.

​
  1. Fixar versões de modelo

Fixe versões de modelo específicas para cada implantação. Sem fixar, aliases de modelo como sonnet e opus resolvem para o padrão integrado do Claude Code para Microsoft Foundry, que pode ficar atrás da versão mais recente e pode ainda não estar disponível em sua conta. Microsoft Foundry não possui verificação de modelo na inicialização, portanto as solicitações falham quando o padrão não está disponível. Quando você criar implantações do Azure, selecione uma versão de modelo específica em vez de “atualizar automaticamente para a mais recente”.
Defina as variáveis de modelo para corresponder aos nomes de implantação que você criou na etapa 1. Sem ANTHROPIC_DEFAULT_OPUS_MODEL, o alias opus no Microsoft Foundry resolve para Opus 4.6. Defina-o para o ID de um modelo Opus mais recente, como Opus 4.8:
As tarefas em segundo plano, como geração de título de sessão, usam o modelo pequeno/rápido, normalmente um modelo da classe Haiku. No Microsoft Foundry, Claude Code usa como padrão o modelo primário porque nem toda conta tem uma implantação Haiku. Para usar Haiku para tarefas em segundo plano, defina ANTHROPIC_DEFAULT_HAIKU_MODEL para uma implantação Haiku que esteja disponível em sua conta, conforme mostrado acima. Para IDs de modelo atuais e legados, consulte Visão geral de modelos. Consulte Configuração de modelo para a lista completa de variáveis de ambiente. O cache de prompt está ativado automaticamente. Para solicitar um TTL de cache de 1 hora em vez do padrão de 5 minutos, defina a seguinte variável; gravações de cache com TTL de 1 hora são cobradas a uma taxa mais alta:
Para definir TTLs diferentes para sua conversa principal e para as solicitações que Claude Code faz fora dela, escolha o TTL você mesmo.

​
  1. Executar Claude Code

Com as variáveis de ambiente definidas, inicie Claude Code a partir do diretório do seu projeto:
Claude Code lê CLAUDE_CODE_USE_FOUNDRY e as outras variáveis Microsoft Foundry do ambiente e se conecta ao seu recurso Azure no primeiro prompt. Diferentemente de Amazon Bedrock e Google Cloud’s Agent Platform, Microsoft Foundry não possui um assistente de configuração interativo, portanto as variáveis de ambiente nas etapas 3 e 4 são o único caminho de configuração. Para verificar sua configuração, execute /status dentro do Claude Code. A linha do provedor de API mostra Microsoft Foundry, junto com o nome do recurso ou URL base que você configurou.

​
Configuração do Azure RBAC

As funções padrão Azure AI User e Cognitive Services User incluem todas as permissões necessárias para invocar modelos Claude. Para permissões mais restritivas, crie uma função personalizada com o seguinte:
Para detalhes, consulte documentação RBAC do Microsoft Foundry.

​
Janela de contexto de 1M de tokens

No Microsoft Foundry, quando o Claude Code consegue identificar qual modelo a sua implantação serve, os modelos Fable, Sonnet 5 e posteriores, e Opus 4.7 e posteriores são executados com a janela de contexto de 1M de tokens por padrão, sem necessidade do sufixo [1m]. O Claude Code lê o modelo a partir do nome da implantação nas suas variáveis de modelo. Nomeie cada implantação com o ID do modelo, como claude-opus-4-8, ou mapeie o modelo para o nome da sua implantação com modelOverrides. Para um nome de implantação que não consegue associar a um modelo, o Claude Code assume uma janela de 200K, a menos que você declare uma diferente. Esta entrada do settings.json informa ao Claude Code que uma implantação chamada team-opus-prod serve o Opus 4.8:
Para manter uma janela de 200K, defina CLAUDE_CODE_DISABLE_1M_CONTEXT=1. O Opus 4.6 e o Sonnet 4.6 alcançam a janela de 1M quando você acrescenta [1m] ao nome da implantação em ANTHROPIC_DEFAULT_OPUS_MODEL ou ANTHROPIC_DEFAULT_SONNET_MODEL, conforme descrito em Fixar modelos para implantações de terceiros. Antes da v2.1.287, os modelos Fable e o Opus 4.7 e posteriores também precisavam desse sufixo no Microsoft Foundry e, sem ele, eram executados com uma janela de 200K por padrão.

​
Resolução de problemas

Se você receber um erro “Failed to get token from azureADTokenProvider: ChainedTokenCredential authentication failed”:
  • Configure Entra ID no ambiente, ou defina ANTHROPIC_FOUNDRY_API_KEY.
Se as solicitações falharem com erros de conexão repetidos no primeiro prompt:
  • Verifique se ANTHROPIC_FOUNDRY_RESOURCE está definido para o nome do recurso real em vez de um espaço reservado. Claude Code constrói a URL do endpoint a partir deste valor, portanto, um nome incorreto aponta para um host que não existe.

​
Recursos adicionais