Claude no Microsoft Foundry

Este guia mostra como configurar e fazer chamadas de API para o Claude no Microsoft Foundry usando um dos SDKs de cliente da Anthropic ou requisições HTTP diretas. Ao acessar o Claude no Microsoft Foundry, você é cobrado pelo uso do Claude no Azure Marketplace. Você pode usar os modelos Claude mais recentes, incluindo Claude Opus 5, Claude Opus 4.8 e Claude Sonnet 5, e recursos como a janela de contexto de 1M de tokens, 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 do Claude no Microsoft Foundry 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 portal do Foundry
• A Azure CLI instalada (necessária para o exemplo de cURL com Entra ID, opcional nos demais casos)
• Uma função do Azure RBAC que permita usar o recurso, como Foundry User (anteriormente Azure AI User) ou Cognitive Services User



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. Os exemplos nesta página também mostram requisições com cURL e a CLI ant. Para configurar a CLI, consulte Início rápido da CLI.

pip install -U "anthropic"

# Para autenticação com Entra ID, instale também a biblioteca Azure Identity
pip install azure-identity



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. Primeiro você 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. Como alternativa, 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 restringir o acesso de rede ao seu recurso.
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 (a opção New Foundry está ativada):

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-5). Cada modelo aparece uma vez no catálogo, independentemente de quantas opções de hospedagem ele suporta.
3. No card do modelo, selecione Deploy e, em seguida, Custom settings para abrir o painel de configurações de implantação. Se você escolher Default settings, a implantação será configurada automaticamente 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).

Se a opção New Foundry estiver desativada, você está no layout clássico do portal. Nesse caso, abra Model catalog no painel esquerdo para encontrar e implantar um modelo, e abra Models + endpoints (em My assets) para visualizar suas implantações e os detalhes de seus endpoints.



Autenticação

O Claude no Microsoft Foundry oferece suporte a 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 com 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 header 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/). O SDK de C# não lê essa variável: ele sempre constrói a URL base a partir do nome do recurso.

Exemplo usando chave de API:

import os
from anthropic import AnthropicFoundry

client = AnthropicFoundry(
    api_key=os.environ.get("ANTHROPIC_FOUNDRY_API_KEY"),
    resource="example-resource",  # your resource name
)

message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content)



Autenticação com Microsoft Entra

A autenticação com Entra ID permite gerenciar o acesso com o Azure RBAC, integrar com o gerenciamento de identidade da sua organização e evitar o manuseio manual de chaves de API. Para usar tokens do Entra ID:

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

Exemplo usando Entra ID:

from anthropic import AnthropicFoundry
from azure.identity import DefaultAzureCredential, get_bearer_token_provider

# Obtenha o token do Microsoft Entra ID usando o padrão de provedor de token
token_provider = get_bearer_token_provider(
    DefaultAzureCredential(), "https://ai.azure.com/.default"
)

# Crie o cliente com autenticação do Entra ID
client = AnthropicFoundry(
    resource="example-resource",  # your resource name
    azure_ad_token_provider=token_provider,  # Use token provider for Entra ID auth
)

# Faça a requisição
message = client.messages.create(
    model="claude-opus-5",
    max_tokens=1024,
    messages=[{"role": "user", "content": "Hello!"}],
)
print(message.content)



IDs de requisição para correlação

O Foundry inclui identificadores de requisição nos headers 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 (Azure API Management) 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 oferece suporte à maioria dos recursos do Claude. Você pode encontrar todos os recursos atualmente suportados em Visão geral dos recursos.



Janela de contexto

Claude Fable 5, Claude Opus 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, web fetch, 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 padrão de resposta da API do Claude. Isso inclui o objeto usage nos corpos de resposta, que fornece informações detalhadas sobre o consumo de tokens das suas requisições. O objeto usage é consistente em todas as plataformas (API do Claude, Amazon Bedrock, Claude Platform na AWS, Foundry e Google Cloud).

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



IDs de modelo da API e implantações

Os termos de ciclo de vida (Descontinuado, Desativado) 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 transferido.

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 logging

O Azure fornece monitoramento e logging para seu uso do Claude através de padrões standard 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 logs por pelo menos 30 dias contínuos 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 o Microsoft Entra ID, certifique-se de que seu token de acesso é válido e não expirou. Os 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 apropriada do Azure RBAC 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 retry na sua aplicação.
• Solução: Considere solicitar aumentos de limite de taxa através do portal do Azure ou do suporte do Azure.



Headers de limite de taxa

O Foundry não inclui os headers 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-opus-5).
• 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.



Próximos passos



Recursos adicionais