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 "context window" (janela de contexto) de 1M de tokens, enquanto gerencia os custos por meio 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 por meio 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 (obrigatória para o exemplo de cURL com Entra ID, opcional nos demais casos)
• Uma função RBAC do Azure 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 por meio 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 o 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: os recursos contêm sua configuração de segurança e cobrança, enquanto as implantações são as instâncias de modelo que você chama por meio 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 o 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

Depois de criar seu recurso, implante um modelo Claude para disponibilizá-lo para chamadas de API. Estas etapas descrevem o novo portal do Foundry (com a opção New Foundry ativada):

1. Entre 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 única 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, a implantação será configurada automaticamente como Hospedado 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:
   • Nome da implantação: 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.
   • Escopo de região: 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 Claude API.
   • Versão do modelo: 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 guia 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. Nele, 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 por chave de API

Após provisionar seu recurso Claude do Foundry, você pode obter uma "API key" (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 guia Details.
3. Copie o valor de Key (e anote o Target URI do seu endpoint).
4. Use o cabeçalho api-key ou x-api-key em suas requisições, ou forneça-o ao SDK.

Os SDKs do Foundry exigem uma chave de API e um nome de recurso ou uma URL base. Os SDKs de C#, Java, PHP, Python e TypeScript leem esses valores automaticamente 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 RBAC do Azure, integrar-se ao 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 do Microsoft Entra ID 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:

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

# Obter 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"
)

# Criar 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
)

# Fazer 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 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 (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 na 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 o Claude Sonnet 4.5, têm uma janela de contexto de 200 mil 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 seu lugar)



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 (pesquisa na web, busca na web, execução de código e pesquisa 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 Claude API. 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 (Claude API, Amazon Bedrock, Claude Platform on AWS, Foundry e Google Cloud).

Para detalhes sobre os 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 (Descontinuado, Desativado) são definidos em Descontinuações de modelos. O Microsoft Foundry segue o cronograma de ciclo de vida da Claude API.

Os seguintes modelos Claude estão disponíveis por meio 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) em suas requisições de API.



Cobrança

O Claude no Microsoft Foundry é cobrado por meio do Azure Marketplace. O uso é denominado em Claude Consumption Units (CCUs), medido por hora e faturado mensalmente de forma postecipada na sua fatura do Azure. As CCUs não são créditos pré-pagos. Não há saldo nem compromisso de CCUs.

Para o preço da CCU, a mecânica de conversão e as taxas de tokens 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). Ela pode estar 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 depois que o tráfego tiver sido migrado.

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 monitoramento e registro de logs para o seu uso do Claude por meio dos padrões do Azure:

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

A Anthropic recomenda registrar sua atividade em uma base contínua de pelo menos 30 dias para entender os 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 guia 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 RBAC do Azure 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 "rate limit" (limite de taxa). Implemente lógica de backoff exponencial e de novas tentativas em sua aplicação.
• Solução: Considere solicitar aumentos de limite de taxa por meio 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. Em vez disso, gerencie a limitação de taxa por meio 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