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](#4-pin-model-versions) 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](https://ai.azure.com/)
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](https://platform.claude.com/docs/en/build-with-claude/claude-in-microsoft-foundry#hosting-options), que determina se a inferência é executada no Azure ou na infraestrutura da Anthropic.
2) 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](#use-an-api-key): você copia uma chave do portal do Microsoft Foundry e a define como `ANTHROPIC_FOUNDRY_API_KEY`
* [Microsoft Entra ID](#use-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](#use-a-bearer-token): 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:
```bash theme={null}
export ANTHROPIC_FOUNDRY_API_KEY=your-azure-api-key
```
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](https://learn.microsoft.com/en-us/azure/developer/javascript/sdk/authentication/credential-chains#defaultazurecredential-overview) 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:
```bash theme={null}
az login
```
Para as funções de que sua identidade precisa, consulte [Configuração do Azure RBAC](#azure-rbac-configuration).
Usar um token de portador
Claude Code envia o valor de `ANTHROPIC_FOUNDRY_AUTH_TOKEN` em cada solicitaçã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ê. Requer Claude Code v2.1.203 ou posterior.
Defina a variável para um token de portador que o Microsoft Entra ID emitiu para seu recurso:
```bash theme={null}
export ANTHROPIC_FOUNDRY_AUTH_TOKEN=your-entra-access-token
```
`ANTHROPIC_FOUNDRY_AUTH_TOKEN` tem precedência sobre `ANTHROPIC_FOUNDRY_API_KEY` e sobre a cadeia de credenciais padrão.
3. Configurar Claude Code
Defina as seguintes variáveis de ambiente para ativar Microsoft Foundry:
```bash theme={null}
# Ativar integração do Microsoft Foundry
export CLAUDE_CODE_USE_FOUNDRY=1
# Nome do recurso do Azure (substitua {resource} pelo nome do seu recurso)
export ANTHROPIC_FOUNDRY_RESOURCE={resource}
# Ou forneça a URL base completa:
# export ANTHROPIC_FOUNDRY_BASE_URL=https://{resource}.services.ai.azure.com/anthropic
```
Defina `ANTHROPIC_FOUNDRY_RESOURCE` apenas com o nome do recurso, como `my-resource`. Claude Code [recusa uma URL ou nome de host](/docs/pt/errors#anthropic-foundry-resource-must-be-a-foundry-resource-name) quando você envia uma mensagem.
4. 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:
```bash theme={null}
export ANTHROPIC_DEFAULT_OPUS_MODEL='claude-opus-4-8'
export ANTHROPIC_DEFAULT_SONNET_MODEL='claude-sonnet-5'
export ANTHROPIC_DEFAULT_HAIKU_MODEL='claude-haiku-4-5'
```
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](https://platform.claude.com/docs/en/about-claude/models/overview). Consulte [Configuração de modelo](/docs/pt/model-config#pin-models-for-third-party-deployments) para a lista completa de variáveis de ambiente.
O [cache de prompt](/docs/pt/prompt-caching) 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:
```bash theme={null}
export ENABLE_PROMPT_CACHING_1H=1
```
Para definir TTLs diferentes para sua conversa principal e para as solicitações que Claude Code faz fora dela, [escolha o TTL você mesmo](/docs/pt/prompt-caching#choose-the-ttl-yourself).
5. Executar Claude Code
Com as variáveis de ambiente definidas, inicie Claude Code a partir do diretório do seu projeto:
```bash theme={null}
claude
```
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:
```json theme={null}
{
"permissions": [
{
"dataActions": [
"Microsoft.CognitiveServices/accounts/providers/*"
]
}
]
}
```
Para detalhes, consulte [documentação RBAC do Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/concepts/rbac-azure-ai-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](https://platform.claude.com/docs/en/build-with-claude/context-windows#context-window-sizes-by-model) 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`](/docs/pt/model-config#override-model-ids-per-version). 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](/docs/pt/model-config#correct-the-window-for-a-gateway-or-custom-model-id).
Esta entrada do `settings.json` informa ao Claude Code que uma implantação chamada `team-opus-prod` serve o Opus 4.8:
```json theme={null}
{
"modelOverrides": {
"claude-opus-4-8": "team-opus-prod"
}
}
```
Para manter uma janela de 200K, defina [`CLAUDE_CODE_DISABLE_1M_CONTEXT=1`](/docs/pt/model-config#turn-off-1m-context).
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](/docs/pt/model-config#pin-models-for-third-party-deployments). 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
* [Documentação do Microsoft Foundry](https://learn.microsoft.com/en-us/azure/ai-foundry/what-is-azure-ai-foundry)
* [Modelos do Microsoft Foundry](https://ai.azure.com/explore/models)
* [Preços do Microsoft Foundry](https://azure.microsoft.com/en-us/pricing/details/ai-foundry/)