Configurar o Código Claude para o Microsoft Foundry

O Código Claude da Antropic é uma ferramenta de codificação agente que lê sua base de código, edita arquivos, executa comandos e integra-se às ferramentas de desenvolvimento. Ele está disponível como uma ferramenta da CLI e uma extensão do VS Code. Ao configurar o Claude Code com o Microsoft Foundry, você executa o agente de codificação na infraestrutura do Azure mantendo seus dados dentro do limite de conformidade. Essa configuração fornece segurança de nível empresarial, rede privada, controle de acesso baseado em função e gerenciamento de custos.

Neste artigo, você aprenderá a:

• Instalar e configurar a CLI do Claude Code para o Microsoft Foundry
• Configurar a extensão do Claude Code VS Code
• Autentique-se com o Microsoft Entra ID ou chaves de API
• Criar arquivos de contexto de projeto para obter melhor assistência de IA
• Executar o Código Claude no GitHub Actions para automação de CI/CD

Para usar Modelos Claude no Microsoft Foundry, você deve ter uma assinatura paga do Azure com uma conta de cobrança em um país ou região, onde a Anthropic oferece os modelos para compra. Para obter uma lista de erros comuns relacionados à assinatura, consulte mensagens de erro comuns e soluções. Atualmente, não há suporte para os seguintes tipos de assinatura:

• Contas corporativas localizadas na Coreia do Sul
• Assinaturas do Provedor de Soluções em Nuvem
• As assinaturas do Azure que não têm um método de cobrança ativa pago conforme o uso (por exemplo, estudante, teste gratuito ou contas baseadas em crédito inicial)
• Assinaturas patrocinadas que utilizam exclusivamente créditos do Azure. Observação: se você tiver uma conta com um cartão de crédito registrado, o cartão de crédito será cobrado automaticamente em vez de créditos do Azure.

Para obter uma lista de regiões com suporte, consulte as localizações geográficas com suporte. Observe que, a "Política de Regiões Com Suporte" da Anthropic pode se aplicar à disponibilidade em sua região, verificar as regiões com suporte para obter detalhes.

Pré-requisitos

• Uma assinatura do Azure com uma forma de pagamento válida. Se você não tiver uma assinatura do Azure, crie uma conta paga do Azure.
• Acesso ao Microsoft Foundry com permissões de Colaborador para criar e gerenciar recursos.
• Um projeto do Microsoft Foundry criado em uma das regiões com suporte para implantações de modelo claude.
• Função de Colaborador ou Proprietário no seu grupo de recursos do Foundry. Para obter mais informações, consulte as funções RBAC do Azure.
• Acesso ao Azure Marketplace para implantar Modelos do Foundry de parceiros.
• Para Windows, use o Git Bash (incluído no Git para Windows) ou instale o WSL2 (recomendado para compatibilidade completa do Linux). Consulte Instalação do WSL.
• (Opcional) CLI do Azure instalada com az login completo para a autenticação do Microsoft Entra ID.

Requisitos do sistema

Implantar um modelo Claude no Foundry

Antes de configurar o Claude Code, implante os modelos claude disponíveis de que o Claude Code precisa. A maioria dos modelos Claude oferece suporte à implantação global padrão. Para obter mais informações sobre tipos de implantação com suporte, consulte os modelos de Claude no Microsoft Foundry.

Claude Code usa modelos diferentes para tarefas diferentes:

Implantar o modelo diretamente no Foundry

Para implantar um modelo:

1. Siga as instruções em Implantar e usar modelos claude no Microsoft Foundry para implantar um modelo Claude, como o Opus 4.6.

2. Após a implantação, selecione a guia Detalhes da implantação e anote o URI de Destino e a Chave. Você precisa desses valores para a configuração.

Alternativa: implantar modelo usando o Roteador de Modelo

O Roteador de Modelo é um modelo de Foundry que roteia de forma inteligente cada prompt para o melhor modelo subjacente com base na complexidade, no custo e no desempenho da consulta. A versão 2025-11-18 do Roteador de Modelo dá suporte a modelos selecionados de Claude (claude-haiku-4-5, claude-sonnet-4-5, claude-opus-4-6, claude-opus-4-7e claude-opus-4-8), ao lado de outros modelos do Foundry.

Benefícios para usuários do Claude Code:

• Seleção automática de modelos: prompts simples direcionam para modelos mais rápidos e econômicos. Tarefas de codificação complexas são direcionadas para modelos mais capazes.
• Otimização de custo: use perfis de roteamento para equilibrar a qualidade versus o custo, mantendo o desempenho da linha de base.
• Ponto de extremidade único: uma implantação gerencia todas as decisões de roteamento na frota de modelos.

Para usar o Roteador de Modelo com o Claude Code, primeiro implante os modelos Claude com suporte e, em seguida, implante o Model Router e habilite-os por meio da configuração do subconjunto de modelo.

Instalar a CLI do Claude Code

Instale a CLI do Claude Code para trabalhar com Claude Code diretamente em seu terminal. Em seguida, verifique se está claude em seu PATH executando claude --version.

Instalação nativa (recomendado)

As instalações nativas são atualizadas automaticamente em segundo plano para mantê-lo na versão mais recente.

curl -fsSL https://claude.ai/install.sh | bash
claude --version # verify installation

irm https://claude.ai/install.ps1 | iex
claude --version # verify installation

Instalação com Homebrew

Se estiver usando macOS:

brew install --cask claude-code
claude --version # verify installation

As instalações homebrew não são atualizadas automaticamente. Execute brew upgrade claude-code periodicamente para obter os recursos e correções de segurança mais recentes.

Solucionar problemas de local de instalação

Se o claude --version comando não for encontrado, adicione o local de instalação ao SEU PATH da seguinte maneira:

echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.bashrc && source ~/.bashrc

Para obter mais opções de instalação, consulte a documentação do Claude Code.

Configurar o Código Claude para Foundry

Você usa o nome do recurso do Foundry ou a URL base para configurar o Claude Code para o Foundry.

Para localizar o nome do recurso do Foundry no portal da Foundry:

1. Vá para a navegação superior esquerda e selecione Gerenciar>Project detalhes.
2. Copie o valor do recurso pai da página de detalhes do Projeto .

Para localizar sua URL base no portal do Foundry:

1. Vá para a home page do portal do Foundry
2. Localize o endpoint do projeto e copie a parte da URL que vem antes do /api/projects/<your-project-name>. Sua URL base é do formulário https://<your-resource-name>.services.ai.azure.com. Claude Code acrescenta /anthropic a essa URL automaticamente quando você usa ANTHROPIC_FOUNDRY_RESOURCE.

Defina variáveis de ambiente para conectar o Claude Code à implantação do Microsoft Foundry:

# Required: Enable Foundry integration
export CLAUDE_CODE_USE_FOUNDRY=1

# Azure resource name (replace <your-resource-name> with your resource name)
export ANTHROPIC_FOUNDRY_RESOURCE=<your-resource-name>
# Or provide the full base URL:
# export ANTHROPIC_FOUNDRY_BASE_URL=https://<your-resource-name>.services.ai.azure.com

# Optional: Specify model deployment names if different from defaults
export ANTHROPIC_DEFAULT_SONNET_MODEL="claude-sonnet-4-6"
export ANTHROPIC_DEFAULT_HAIKU_MODEL="claude-haiku-4-5"
export ANTHROPIC_DEFAULT_OPUS_MODEL="claude-opus-4-6"

# Required: Enable Foundry integration
$env:CLAUDE_CODE_USE_FOUNDRY = "1"

# Azure resource name (replace <your-resource-name> with your resource name)
$env:ANTHROPIC_FOUNDRY_RESOURCE = "<your-resource-name>"
# Or provide the full base URL:
# $env:ANTHROPIC_FOUNDRY_BASE_URL = "https://<your-resource-name>.services.ai.azure.com"

# Optional: Specify model deployment names if different from defaults
$env:ANTHROPIC_DEFAULT_SONNET_MODEL = "claude-sonnet-4-6"
$env:ANTHROPIC_DEFAULT_HAIKU_MODEL = "claude-haiku-4-5"
$env:ANTHROPIC_DEFAULT_OPUS_MODEL = "claude-opus-4-6"

A tabela a seguir descreve cada variável:

Para persistir essas variáveis em sessões de terminal, adicione-as ao seu perfil de shell (como ~/.bashrc ou ~/.zshrc).

Autenticar com o Foundry

O Claude Code dá suporte a dois métodos de autenticação para o Microsoft Foundry:

• ID do Microsoft Entra (recomendado): usa suas credenciais da CLI do Azure. Melhor para ambientes empresariais, acesso à equipe e pipelines de CI/CD em que você deseja centralizar o gerenciamento de identidades sem gerenciar segredos.
• Chave de API: usa uma chave de API do projeto no portal do Foundry. Melhor para testes rápidos ou ambientes em que a CLI do Azure não está disponível.

Opção A: ID do Microsoft Entra (recomendado)

A autenticação da ID do Microsoft Entra usa suas credenciais da CLI do Azure automaticamente. Execute az login antes de iniciar o Claude Code:

1. Entre com a CLI do Azure:

   az login
   

   Dica

   Se o recurso Foundry estiver em um locatário diferente do locatário padrão da CLI do Azure, especifique a ID do locatário:

   az login --tenant <tenant-id>
   

2. Verifique se sua entrada tem como destino a assinatura correta:

   az account show
   

Quando você usa o Microsoft Foundry, os comandos /login e /logout dentro do Claude Code são desativados. A autenticação é tratada por meio de suas credenciais do Azure.

Claude Code detecta sua sessão da CLI do Azure e a usa para autenticação sem configuração extra.

Opção B: chave de API

Se preferir a autenticação de chave de API, defina a chave em suas variáveis de ambiente.

1. No portal do Microsoft Foundry, abra o recurso.
2. Na home page , localize o campo de chave da API do Project .
3. Selecione Copiar a chave da API do Projeto para copiar o valor. Essa é a chave que você usa para a variável de ANTHROPIC_FOUNDRY_API_KEY ambiente.
4. Defina a variável de ambiente em seu terminal:

export ANTHROPIC_FOUNDRY_API_KEY="<your-foundry-api-key>"

$env:ANTHROPIC_FOUNDRY_API_KEY = "<your-foundry-api-key>"

Configurar a extensão do VS Code

A extensão claude code vs code fornece uma interface gráfica nativa para Claude Code diretamente em seu IDE.

1. Instale a extensão do VS Code Marketplace.

2. Abra as configurações do VS Code (Ctrl+ ou Cmd+) e pesquise por Claude Code: Variáveis de Ambiente.

3. Selecione Editar no settings.json e adicione a seguinte configuração:

     {
       "Claude Code: Environment Variables": [
         { "name": "CLAUDE_CODE_USE_FOUNDRY", "value": "1" },
         { "name": "ANTHROPIC_FOUNDRY_RESOURCE", "value": "<your-resource-name>" },
         { "name": "ANTHROPIC_FOUNDRY_API_KEY", "value": "<optional-for-non-entra-auth>" }
       ]
     }
   

4. Selecione o ícone do Spark na barra lateral para abrir o painel do Claude Code.

5. O Claude Code autentica-se usando suas credenciais do Azure. Execute primeiro az login se você estiver usando a autenticação do Microsoft Entra ID.

A extensão dá suporte ao modo de aceitação automática de edições, modo de planejamento, pensamento ampliado e gerenciamento de arquivos com @-menções, tudo isso enquanto roteia por meio da implantação do Microsoft Foundry.

Validar a configuração

Verifique se o Claude Code está configurado corretamente para usar o Microsoft Foundry.

1. Abra um terminal e navegue até um diretório de projeto:

   cd your-project
   

2. Inicie o Claude Code:

   claude
   

   O Claude Code usa como padrão o modelo sonnet para codificação geral. Se você ainda não implantou todos os três modelos, poderá especificar um modelo implantado diretamente:

   claude --model claude-opus-4-6
   

3. Execute o /status comando:

   > /status
   

   A saída deve ser semelhante ao exemplo a seguir. O formato exato pode variar dependendo da sua versão do Claude Code.

   ─────────────────────────────────────
   Version: 2.1.52
   Session name: /rename to add a name
   Session ID: <your-session-ID>
   cwd: C:\WINDOWS\system32
   API provider: Microsoft Foundry
   Microsoft Foundry Resource: <your-resource-name>
   Model: Default (claude-sonnet-4-6)
   Memory:
   Setting sources:
   ─────────────────────────────────────
   

   Verifique o seguinte na saída de status:

   Campo	Valor esperado
   Provedor de API	Microsoft Foundry
   Recurso do Foundry	Seu nome do recurso Foundry
   Modelo	Seu modelo implantado (por exemplo, claude-sonnet-4-6)

4. Envie um prompt de teste como "Resumir a estrutura deste projeto".

5. Confirme se Claude Code responde com uma análise do seu projeto. Uma conexão bem-sucedida mostra o prompt interativo de Claude Code sem erros de autenticação.

   Se Claude Code exibir um erro como "Falha ao obter token" ou "o modelo não está disponível", consulte a seção Solução de problemas .

Criar contexto de projeto com CLAUDE.md

Você pode fornecer instruções adicionais e diretrizes ao Claude Code usando CLAUDE.md arquivos. Claude Code busca arquivos nos seguintes locais e os mescla de cima para baixo (ou seja, os arquivos são carregados em ordem, com arquivos posteriores substituindo os anteriores), fornecendo contexto sobre suas preferências pessoais, detalhes específicos do projeto e a tarefa atual.

1. ~/.claude/CLAUDE.md – Padrões globais em todos os projetos
2. ./CLAUDE.md – Configurações raiz do repositório
3. ./current-dir/CLAUDE.md – Características do diretório atual

Claude Code também dá suporte a regras de projeto (.claude/rules/*.md) e memória local (CLAUDE.local.md) para controle mais granular. Para obter a hierarquia de memória completa, consulte a documentação de memória do Claude Code.

O exemplo a seguir mostra um CLAUDE.md arquivo para um projeto do Microsoft Agent Framework . Crie um arquivo semelhante na raiz do projeto para ajudar Claude Code a entender sua base de código:

# Project: Customer Service Agent

## Overview
Multi-agent system using Microsoft Agent Framework with Foundry Agent Service.

## Tech Stack
- Python 3.11+
- agent-framework (Microsoft Agent Framework Python SDK)
- Microsoft Foundry for hosted agents
- MCP tools for enterprise data access

## Architecture
- `src/agents/` - Agent definitions (triage, specialist, escalation)
- `src/tools/` - MCP tool implementations
- `src/workflows/` - Multi-agent orchestration
- `tests/` - pytest with async fixtures

## Commands
```bash
# Run locally
python -m src.main

# Test
pytest tests/ -v

# Deploy to Foundry Agent Service
az ai agent deploy --config deploy.yaml
```

## Code Patterns
Use `AzureAIAgentClient` with `AzureCliCredential`:
```python
async with AzureAIAgentClient(async_credential=AzureCliCredential()) as client:
    agent = client.create_agent(instructions="...", tools=[...])
```

## Current Sprint
- Implementing RAG grounding with Foundry IQ
- Adding Fabric connector for sales data

Depois de criar um CLAUDE.md arquivo, inicie o Claude Code no diretório do projeto para carregar o contexto:

# Start Claude Code in your project
cd your-project
claude

# Or run a one-off command
claude "explain the agent orchestration in src/workflows/"

Configurar o RBAC do Azure

Para conceder aos membros da equipe acesso aos modelos Claude hospedados na Foundry, atribua um dos seguintes papéis internos predefinidos:

O perfil Usuário do Foundry é o perfil nativo recomendado do Foundry. A função usuário dos Serviços Cognitivos é uma função herdada que também concede permissões de invocação de modelo no nível de recurso do Azure.

Essas funções incluem todas as permissões necessárias para executar o Claude Code com o Foundry.

Para obter acesso mais restritivo, crie uma função personalizada com escopo para as ações de dados específicas de que sua equipe precisa. Para obter diretrizes sobre como definir funções personalizadas, consulte o controle de acesso baseado em função para o Microsoft Foundry.

Executar o Código Claude no GitHub Actions

O Claude Code integra-se ao GitHub Actions para automação de CI/CD. Armazene sua chave de API no repositório de segredos do repositório antes de usar esses fluxos de trabalho.

Gerar testes em pull requests

Crie um fluxo de trabalho que gere testes quando os arquivos de ferramenta ou agente forem alterados:

name: Generate Agent Tests
on:
  pull_request:
    paths:
      - 'src/agents/**'
      - 'src/tools/**'

jobs:
  generate-tests:
    runs-on: ubuntu-latest
    permissions:
      contents: write
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      
      - name: Run Claude Code
        uses: anthropics/claude-code-action@v1
        with:
          prompt: |
            Review the changed agent files and generate pytest tests.
            Use async fixtures for AIProjectClient mocking.
            Follow patterns in tests/conftest.py.
          allowed_tools: "edit,write,bash"
        env:
          CLAUDE_CODE_USE_FOUNDRY: "1"
          ANTHROPIC_FOUNDRY_RESOURCE: ${{ secrets.AZURE_FOUNDRY_RESOURCE }}
          ANTHROPIC_FOUNDRY_API_KEY: ${{ secrets.AZURE_FOUNDRY_API_KEY }}

Desencadear a revisão de PR com @claude

Crie um fluxo de trabalho que responda a menções em comentários de solicitação de pull @claude:

name: Claude PR Assistant
on:
  issue_comment:
    types: [created]

jobs:
  respond:
    if: contains(github.event.comment.body, '@claude')
    runs-on: ubuntu-latest
    permissions:
      contents: read
      pull-requests: write
    steps:
      - uses: actions/checkout@v4
      
      - name: Claude Review
        uses: anthropics/claude-code-action@v1
        with:
          prompt: ${{ github.event.comment.body }}
          context: "PR #${{ github.event.issue.number }}"
        env:
          CLAUDE_CODE_USE_FOUNDRY: "1"
          ANTHROPIC_FOUNDRY_RESOURCE: ${{ secrets.AZURE_FOUNDRY_RESOURCE }}
          ANTHROPIC_FOUNDRY_API_KEY: ${{ secrets.AZURE_FOUNDRY_API_KEY }}

Monitorar o uso

Monitore o uso do Claude Code no portal do Foundry:

1. Acesse o Microsoft Foundry e abra seu projeto.

2. Navegue até Operar para exibir as métricas de uso:

   • Consumo de token por modelo
   • Latência de solicitação
   • Taxas de erro e atingimentos de limite de taxa

Para definir limites de token por solicitação, configure a variável de ANTHROPIC_MAX_TOKENS ambiente:

export ANTHROPIC_MAX_TOKENS=100000

$env:ANTHROPIC_MAX_TOKENS = "100000"

Para obter opções de configuração que controlam o uso e o custo do token, como limites de token específicos do modelo, consulte a documentação de configuração do Claude Code.

Limpar recursos

Se você não precisar mais das implantações do modelo Claude, exclua-as para liberar espaços de implantação e cota em seu recurso. Os modelos Claude usam implantações Padrão Global com cobrança por token, de modo que implantações ociosas não incorrem em custos. No entanto, cada implantação conta contra o limite de implantação de 32 por recurso.

Excluir implantações no portal do Foundry

Use um destes caminhos de navegação:

• Selecione Operar na navegação superior e, em seguida, selecione Ativos>Modelos na navegação à esquerda. Selecione a implantação que você deseja excluir e, em seguida, selecione Excluir.
• Selecione Compilar na navegação superior e selecione Modelos na navegação à esquerda. Selecione o nome da implantação para abrir sua página de detalhes, selecione a guia Detalhes e, em seguida, selecione Excluir no painel superior.

Excluir implantações com a CLI do Azure

Execute o comando az cognitiveservices account deployment delete para cada implantação:

az cognitiveservices account deployment delete \
  --deployment-name <deployment-name> \
  --name <resource-name> \
  --resource-group <resource-group-name>

Substitua <deployment-name> pelo nome da implantação do modelo (por claude-sonnet-4-6exemplo), <resource-name> pelo nome do recurso Foundry e <resource-group-name> pelo grupo de recursos que contém o recurso Foundry.

Solucionando problemas

Conteúdo relacionado

• Modelos de Claude no Microsoft Foundry
• Implementar e usar Modelos Claude no Microsoft Foundry
• Dados, privacidade e segurança para modelos Claude
• Cotas e limites do Microsoft Foundry Models
• Monitorar o uso e os custos do modelo
• Configurar o Claude Desktop para Microsoft Foundry
• Claude no Microsoft Foundry (documentos da Anthropic)
• Documentação do Claude Code (documentos antropáticos)
• Claude Code no Microsoft Foundry (documentos do Anthropic)