Claude no Microsoft Foundry

Este guia orienta você pelo processo de configuração e realização de chamadas de API para o Claude no Microsoft Foundry usando um dos SDKs de cliente da Anthropic ou requisições HTTP diretas. Quando você acessa o Claude no Microsoft Foundry, você é cobrado pelo uso do Claude no Azure Marketplace, permitindo que você acesse os recursos mais recentes do Claude enquanto gerencia custos através da sua assinatura do Azure.

O Claude está disponível nos tipos de implantação Global Standard e US Data Zone Standard em recursos do Foundry, cobrado em Claude Consumption Units através do Azure Marketplace. Visite Preços para mais detalhes.



Opções de hospedagem

Os modelos Claude no Microsoft Foundry estão disponíveis em duas opções de hospedagem. Você escolhe a opção de hospedagem ao configurar a implantação.



Pré-requisitos

Antes de começar, certifique-se de ter:

• Uma assinatura ativa do Azure
• Acesso ao Foundry
• A Azure CLI instalada (opcional, para gerenciamento de recursos)



Instalar um SDK

Os SDKs de cliente da Anthropic oferecem suporte ao Foundry através de um pacote ou classe de cliente específico da plataforma.



Provisionamento

O Foundry usa uma hierarquia de dois níveis: recursos contêm sua configuração de segurança e cobrança, enquanto implantações são as instâncias de modelo que você chama através da API. Você primeiro criará um recurso do Foundry e, em seguida, criará uma ou mais implantações do Claude dentro dele.



Provisionando recursos do Foundry

Crie um recurso do Foundry, que é necessário para usar e gerenciar serviços no Azure. Você pode seguir estas instruções para criar um recurso do Foundry. Alternativamente, você pode começar criando um projeto do Foundry, o que envolve a criação de um recurso do Foundry.

Para provisionar seu recurso:

1. Navegue até o portal do Foundry
2. Crie um novo recurso do Foundry ou selecione um existente
3. Configure o gerenciamento de acesso usando chaves de API emitidas pelo Azure ou Entra ID (anteriormente Azure Active Directory) para controle de acesso baseado em função
4. Opcionalmente, configure o recurso para fazer parte de uma rede privada (Azure Virtual Network) para segurança aprimorada
5. Anote o nome do seu recurso. Você o usará como {resource} nos endpoints da API (por exemplo, https://{resource}.services.ai.azure.com/anthropic/v1/*)



Criando implantações do Foundry

Após criar seu recurso, implante um modelo Claude para disponibilizá-lo para chamadas de API. Estas etapas descrevem o novo portal do Foundry (o botão New Foundry está ativado):

1. Faça login no portal do Foundry. Na página inicial do portal, selecione Discover na navegação superior direita e, em seguida, Models no painel esquerdo para abrir o catálogo de modelos.
2. Pesquise e selecione um modelo Claude (por exemplo, claude-opus-4-8). Cada modelo aparece uma vez no catálogo, independentemente de quantas opções de hospedagem ele suporta.
3. No cartão do modelo, selecione Deploy e, em seguida, Custom settings para abrir o painel de configurações de implantação. Se você escolher Default settings em vez disso, a implantação será automaticamente configurada como Hospedada no Azure para modelos disponíveis em ambas as opções de hospedagem.
4. Na sua primeira implantação do Claude, revise os termos do Azure Marketplace, selecione um setor e selecione Agree and Proceed para aceitar os termos e assinar a oferta do Azure Marketplace.
5. Configure a implantação:
   • Deployment name: O padrão é o ID do modelo, mas você pode personalizá-lo (por exemplo, my-claude-deployment). O nome da implantação não pode ser alterado após a criação.
   • Region scope: Selecione Global ou, para modelos hospedados no Azure, Data Zone. Selecionar Data Zone cria uma implantação US Data Zone Standard, que mantém a inferência dentro dos Estados Unidos e é equivalente a definir inference_geo: "us" na API do Claude.
   • Model version: Expanda Model version settings e selecione uma versão no menu suspenso Model version. Cada opção de hospedagem é listada como uma versão de modelo separada, rotulada com sua opção de hospedagem (por exemplo, versão 1 para Hospedado na Anthropic, versão 2 para Hospedado no Azure).
6. Selecione Deploy e aguarde a conclusão do provisionamento.
7. Após a implantação, selecione Build na navegação superior direita, depois Models no painel esquerdo e abra sua implantação. A aba Details mostra o Target URI (a URL do seu endpoint) e a Key (sua chave de API).



Autenticação

O Claude no Microsoft Foundry suporta dois métodos de autenticação: chaves de API e tokens do Entra ID. Ambos os métodos usam endpoints hospedados no Azure no formato https://{resource}.services.ai.azure.com/anthropic/v1/*.



Autenticação por chave de API

Após provisionar seu recurso Claude no Foundry, você pode obter uma chave de API no portal do Foundry:

1. No portal do Foundry, selecione Build na navegação superior direita e, em seguida, Models no painel esquerdo.
2. Abra sua implantação do Claude e selecione a aba Details.
3. Copie o valor de Key (e anote o Target URI para seu endpoint).
4. Use o cabeçalho api-key ou x-api-key nas suas requisições, ou forneça-o ao SDK.

Os SDKs do Foundry exigem uma chave de API e um nome de recurso ou URL base. Os SDKs de C#, Java, PHP, Python e TypeScript leem automaticamente esses valores das seguintes variáveis de ambiente, se estiverem definidas:

• ANTHROPIC_FOUNDRY_API_KEY - Sua chave de API
• ANTHROPIC_FOUNDRY_RESOURCE - O nome do seu recurso (por exemplo, example-resource)
• ANTHROPIC_FOUNDRY_BASE_URL - Alternativa ao nome do recurso; a URL base completa (por exemplo, https://example-resource.services.ai.azure.com/anthropic/)

Exemplo usando chave de API:



Autenticação Microsoft Entra

Para segurança aprimorada e gerenciamento centralizado de acesso, você pode usar tokens do Entra ID:

1. Habilite a autenticação Entra para seu recurso do Foundry
2. Obtenha um token de acesso do Entra ID
3. Use o token no cabeçalho Authorization: Bearer {TOKEN}

Exemplo usando Entra ID:



IDs de requisição de correlação

O Foundry inclui identificadores de requisição nos cabeçalhos de resposta HTTP para depuração e rastreamento. Ao entrar em contato com o suporte, forneça os valores de request-id e apim-request-id para ajudar as equipes a localizar e investigar rapidamente sua requisição nos sistemas da Anthropic e do Azure.



Suporte a recursos

O Claude no Microsoft Foundry suporta a maioria dos recursos poderosos do Claude. Você pode encontrar todos os recursos atualmente suportados em Visão geral de recursos.



Janela de contexto

Claude Fable 5, Claude Opus 4.8, Claude Opus 4.7, Claude Opus 4.6, Claude Sonnet 5 e Claude Sonnet 4.6 têm uma janela de contexto de 1M de tokens no Microsoft Foundry. Outros modelos Claude, incluindo Claude Sonnet 4.5, têm uma janela de contexto de 200k tokens.



Recursos do Claude não suportados para o Claude no Microsoft Foundry

• Admin API
• Ferramenta Advisor
• Claude Managed Agents
• Compliance API
• Models API
• Message Batches API
• Fallback do lado do servidor (o parâmetro fallbacks; use o padrão de fallback do lado do cliente em vez disso)



Recursos adicionais não suportados quando hospedado no Azure

Os seguintes recursos estão disponíveis para implantações hospedadas na Anthropic, mas não são suportados para implantações hospedadas no Azure:

• Saídas estruturadas
• Ferramentas do lado do servidor (busca na web, busca de conteúdo web, execução de código e busca de ferramentas)
• Conector MCP
• Agent Skills
• Chamada programática de ferramentas
• Files API

Requisições que usam esses recursos em uma implantação hospedada no Azure retornam um erro 400 Bad Request por design. O Claude Code detecta implantações hospedadas no Azure e adapta automaticamente seu conjunto de recursos.



Respostas da API

As respostas da API do Claude no Microsoft Foundry seguem o formato de resposta padrão da API do Claude. Isso inclui o objeto usage nos corpos de resposta, que fornece informações detalhadas de consumo de tokens para suas requisições. O objeto usage é consistente em todas as plataformas (API do Claude, Foundry, Claude Platform na AWS, Amazon Bedrock e Google Cloud).

Para detalhes sobre cabeçalhos de resposta específicos do Foundry, consulte IDs de requisição de correlação.



IDs de modelo da API e implantações

Os termos de ciclo de vida (Deprecated, Retired) são definidos em Descontinuações de modelos. O Microsoft Foundry segue o cronograma de ciclo de vida da API do Claude.

Os seguintes modelos Claude estão disponíveis através do Foundry:

Por padrão, os nomes de implantação correspondem aos IDs de modelo mostrados na tabela anterior. No entanto, você pode criar implantações personalizadas com nomes diferentes no portal do Foundry para gerenciar diferentes configurações, versões ou limites de taxa. Use o nome da implantação (não necessariamente o ID do modelo) nas suas requisições de API.



Cobrança

O Claude no Microsoft Foundry é cobrado através do Azure Marketplace. O uso é denominado em Claude Consumption Units (CCUs), medido por hora e faturado mensalmente em atraso na sua fatura do Azure. CCUs não são créditos pré-pagos; não há saldo ou compromisso de CCU.

Para o preço de CCU, mecânica de conversão e taxas de token por modelo, consulte Preços do Claude no Microsoft Foundry.



Migrando entre opções de hospedagem

Para mover uma implantação existente de uma opção de hospedagem para a outra:

1. Crie uma nova implantação da outra versão de hospedagem do modelo (Hospedado no Azure ou Hospedado na Anthropic). Isso pode ser no mesmo recurso do Foundry ou em um novo.
2. Atualize sua aplicação para passar o novo nome de implantação no parâmetro model.
3. Exclua a implantação antiga assim que o tráfego tiver sido movido.

Se a nova implantação estiver no mesmo recurso do Foundry, a URL do seu endpoint e a autenticação permanecem inalteradas. Se você criou um novo recurso, atualize o endpoint e as credenciais da sua aplicação para apontar para ele.



Monitoramento e registro de logs

O Azure fornece recursos abrangentes de monitoramento e registro de logs para seu uso do Claude através de padrões padrão do Azure:

• Azure Monitor: Acompanhe o uso da API, latência e taxas de erro
• Azure Log Analytics: Consulte e analise logs de requisição/resposta
• Cost Management: Monitore e preveja custos associados ao uso do Claude

A Anthropic recomenda registrar sua atividade em uma base contínua de pelo menos 30 dias para entender padrões de uso e investigar possíveis problemas.



Solução de problemas



Erros de autenticação

Erro: 401 Unauthorized ou Invalid API key

• Solução: Verifique se sua chave de API está correta. Você pode encontrá-la no portal do Foundry na aba Details da sua implantação (em Build > Models).
• Solução: Se estiver usando Microsoft Entra ID, certifique-se de que seu token de acesso é válido e não expirou. Tokens normalmente expiram após 1 hora.

Erro: 403 Forbidden

• Solução: Sua conta do Azure pode não ter as permissões necessárias. Certifique-se de ter a função Azure RBAC apropriada atribuída (por exemplo, Foundry User (anteriormente Azure AI User) ou Cognitive Services User).



Limitação de taxa

Erro: 429 Too Many Requests

• Solução: Você excedeu seu limite de taxa. Implemente lógica de backoff exponencial e nova tentativa na sua aplicação.
• Solução: Considere solicitar aumentos de limite de taxa através do portal do Azure ou do suporte do Azure.



Cabeçalhos de limite de taxa

O Foundry não inclui os cabeçalhos padrão de limite de taxa da Anthropic (anthropic-ratelimit-tokens-limit, anthropic-ratelimit-tokens-remaining, anthropic-ratelimit-tokens-reset, anthropic-ratelimit-input-tokens-limit, anthropic-ratelimit-input-tokens-remaining, anthropic-ratelimit-input-tokens-reset, anthropic-ratelimit-output-tokens-limit, anthropic-ratelimit-output-tokens-remaining e anthropic-ratelimit-output-tokens-reset) nas respostas. Gerencie a limitação de taxa através das ferramentas de monitoramento do Azure.



Erros de modelo e implantação

Erro: Model not found ou Deployment not found

• Solução: Verifique se você está usando o nome de implantação correto. Se você não criou uma implantação personalizada, use o ID de modelo padrão (por exemplo, claude-sonnet-4-6).
• Solução: Certifique-se de que o modelo/implantação está disponível na sua região do Azure.

Erro: Invalid model parameter

• Solução: O parâmetro model deve conter o nome da sua implantação, que pode ser personalizado no portal do Foundry. Verifique se a implantação existe e está configurada corretamente.



Recursos adicionais

• Documentação do Foundry: ai.azure.com/catalog
• Preços do Azure: azure.microsoft.com/en-us/pricing/details/ai-foundry
• Detalhes de preços da Anthropic: Preços de modelos
• Guia de autenticação: Consulte Autenticação
• Portal do Azure: portal.azure.com