Configurar o Claude Code para Microsoft Foundry

Anthropic Claude Code é uma ferramenta de codificação agente que lê a sua base de código, edita ficheiros, executa comandos e integra-se com as suas ferramentas de desenvolvimento. Está disponível como ferramenta CLI e extensão VS Code. Quando configura o Claude Code com o Microsoft Foundry, executa o agente de codificação na infraestrutura Azure mantendo os seus dados dentro dos limites de conformidade. Esta configuração proporciona segurança de nível empresarial, redes privadas, controlo de acesso baseado em funções e gestão de custos.

Neste artigo, aprende como:

• Instale e configure o Claude Code CLI para o Microsoft Foundry
• Configurar a extensão Claude Code VS Code
• Autenticar com Microsoft Entra ID ou chaves API
• Criar ficheiros de contexto de projeto para melhor assistência em IA
• Execute código Claude no GitHub Actions para automação CI/CD

Para utilizar os modelos Claude no Microsoft Foundry, deve ter uma subscrição Azure paga com uma conta de faturação num país ou região onde a Anthropic disponibiliza os modelos para compra. Para uma lista de erros comuns relacionados com subscrições, veja Mensagens e soluções de erro comuns. Os seguintes tipos de subscrição atualmente não são suportados:

• Contas Empresariais localizadas na Coreia do Sul
• Subscrições do Fornecedor de Soluções em Nuvem
• Subscrições do Azure que não têm um método ativo de faturação pay-as-you-go (por exemplo, contas de estudante, de teste gratuito ou de crédito inicial)
• Subscrições patrocinadas que utilizam apenas créditos do Azure. Nota: Se tiver uma conta com cartão de crédito registado, o cartão de crédito será cobrado em vez de Azure Créditos.

Para uma lista de regiões suportadas, veja localizações geográficas suportadas. Note que, a "Política de Regiões Suportadas" da Anthropic pode aplicar-se à disponibilidade na sua região, consulte c0 para mais detalhes.

Pré-requisitos

• Uma subscrição do Azure com um método de pagamento válido. Se não tiver uma subscrição Azure, crie uma conta Azure pago.
• Acesso ao Microsoft Foundry com permissões de Contribuinte para criar e gerir recursos.
• Um projeto Microsoft Foundry criado numa das regiões suportadas para implementações de modelos Claude.
• Papel de Contribuinte ou Proprietário no seu grupo de recursos da Foundry. Para mais informações, consulte funções de RBAC do Azure.
• Acesso ao Azure Marketplace para implementar Modelos Foundry de parceiros.
• Para Windows, usa o Git Bash (incluído com Git para Windows) ou instala o WSL2 (recomendado para total compatibilidade com Linux). Ver Instalar WSL.
• (Opcional) CLI do Azure instalado e configurado para autenticação com Microsoft Entra ID.

Requisitos do sistema

Implementar um modelo Claude no Foundry

Antes de configurar o Claude Code, implemente os modelos Claude disponíveis que o Claude Code necessita. A maioria dos modelos Claude suporta implementação global de normas. Para mais informações sobre tipos de implementação suportados, consulte Modelos Claude no Microsoft Foundry.

O Claude Code utiliza diferentes modelos para diferentes tarefas:

Implementar o modelo diretamente no Foundry

Para implementar um modelo:

1. Siga as instruções em Deploy e use modelos Claude no Microsoft Foundry para implementar um modelo Claude, como o Opus 4.6.

2. Após a implementação, selecione o separador Detalhes da implementação e anote o seu URI e Chave de Alvo. Precisas destes valores para a configuração.

Alternativa: Modelo de implementação usando Model Router

Model Router é um modelo Foundry que encaminha inteligentemente cada prompt para o melhor modelo subjacente, com base na complexidade da consulta, custo e desempenho. A versão 2025-11-18 Model Router suporta alguns modelos Claude selecionados (claude-haiku-4-5, claude-sonnet-4-5, claude-opus-4-6, claude-opus-4-7, e claude-opus-4-8), juntamente com outros modelos Foundry.

Benefícios para os utilizadores 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 encaminham para modelos mais capazes.
• Otimização de custos: Utilize perfis de encaminhamento para equilibrar qualidade versus custo, mantendo o desempenho base.
• Ponto final único: Uma implementação trata de todas as decisões de roteamento na sua frota de modelos.

Para usar o Model Router com Claude Code, implemente primeiro os modelos Claude suportados, depois implemente o Model Router e permita-os através da configuração de subconjuntos de modelos.

Instalar o Claude Code CLI

Instala o Claude Code CLI para funcionar diretamente com Claude Code no teu terminal. Depois, verifica que está claude no teu PATH executando claude --version.

Instalação nativa (recomendada)

As instalações nativas atualizam-se automaticamente em segundo plano para o manter 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 a usar macOS:

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

As instalações caseiras não atualizam automaticamente. Execute brew upgrade claude-code periodicamente para obter as funcionalidades mais recentes e correções de segurança.

Local de instalação - resolução de problemas

Se o claude --version comando não for encontrado, adicione a localização de instalação ao seu PATH da seguinte forma:

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

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

Configurar o Código Claude para a Foundry

Usa o nome do seu recurso Foundry ou o URL base para configurar o Código Claude para o Foundry.

Para encontrar o nome do seu recurso Foundry no portal Foundry:

1. Vá para a navegação no canto superior esquerdo e selecione Gerenciar>detalhes do Project.
2. Copie o valor de Recurso pai da página Detalhes do projeto.

Para encontrar a URL base no portal Foundry:

1. Ir à página inicial do portal da Foundry
2. Encontre o endpoint Project e copie a parte da URL que vem antes de /api/projects/<your-project-name>. O seu URL base é da forma https://<your-resource-name>.services.ai.azure.com. O código Claude adiciona /anthropic automaticamente neste URL quando usa ANTHROPIC_FOUNDRY_RESOURCE.

Defina variáveis de ambiente para ligar o Claude Code à sua implementação no 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 seguinte descreve cada variável:

Para persistir estas variáveis ao longo das sessões de terminais, adicione-as ao seu perfil de shell (como ~/.bashrc ou ~/.zshrc).

Autenticar com Foundry

O Claude Code suporta dois métodos de autenticação para o Microsoft Foundry:

• Microsoft Entra ID (recomendado): Usa as suas credenciais CLI do Azure. Ideal para ambientes empresariais, acesso de equipas e pipelines CI/CD, onde pretende uma gestão centralizada de identidades sem a necessidade de gerir segredos.
• Chave API: Utiliza uma chave API de projeto do portal Foundry. É melhor para testes rápidos ou ambientes onde a CLI do Azure não está disponível.

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

A autenticação Microsoft Entra ID utiliza automaticamente as suas credenciais CLI do Azure. Executar az login antes de iniciar Claude Code:

1. Inicie sessão com a CLI do Azure:

   az login
   

   Dica

   Se o seu recurso Foundry estiver num tenant diferente do seu tenant padrão do CLI do Azure, especifique o ID do inquilino:

   az login --tenant <tenant-id>
   

2. Verifique se o seu login tem como alvo a subscrição correta:

   az account show
   

Quando usas Microsoft Foundry, os comandos /login e /logout dentro do Claude Code ficam desativados. A autenticação é gerida através das suas credenciais do Azure.

O Claude Code deteta a sua sessão CLI do Azure e usa-a para autenticação sem configuração adicional.

Opção B: Chave API

Se preferir autenticação por chave API, defina a chave nas variáveis do seu ambiente.

1. No portal Microsoft Foundry, abra o seu recurso.
2. Na página Home, encontre o campo chave API do projeto.
3. Selecione Copiar chave API do projeto para copiar o valor. Esta é a chave que usas para a ANTHROPIC_FOUNDRY_API_KEY variável ambiente.
4. Defina a variável ambiente no seu terminal:

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

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

Configurar a extensão VS Code

A extensão Claude Code VS Code fornece uma interface gráfica nativa para Claude Code diretamente no seu IDE.

1. Instala a extensão no VS Code Marketplace.

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

3. Selecione Editar em 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 Spark na barra lateral para abrir o painel Claude Code.

5. O Claude Code autentica usando as suas credenciais Azure. Executa primeiro az login se estiveres a usar autenticação Microsoft Entra ID.

A extensão suporta o modo de aceitação automática de edições, modo de planeamento, modo de pensamento alargado, e gestão de ficheiros com @-menções—tudo isto enquanto processa através do seu deployment na Microsoft Foundry.

Validar a configuração

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

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

   cd your-project
   

2. Lançar o Código Claude:

   claude
   

   Claude Code utiliza como padrão o modelo Sonnet para programação geral. Se ainda não implementou os três modelos, pode especificar um modelo implementado diretamente:

   claude --model claude-opus-4-6
   

3. Executa o /status comando:

   > /status
   

   A saída deverá ser semelhante ao exemplo seguinte. O formato exato pode variar consoante a versão do teu 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:
   ─────────────────────────────────────
   

   Confirme o seguinte na saída de estado:

   Campo	Valor esperado
   Fornecedor de API	Microsoft Foundry
   Recurso da fundição	Nome do recurso da tua Foundry
   Modelo	O seu modelo implementado (por exemplo, claude-sonnet-4-6)

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

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

   Se o Claude Code apresentar um erro como "Falhou em obter o token" ou "o modelo não está disponível", consulte a secção de Resolução de Problemas .

Crie o contexto do projeto com CLAUDE.md

Pode dar instruções e orientações extra ao Claude Code usando CLAUDE.md ficheiros. O Claude Code procura CLAUDE.md ficheiros nos seguintes locais e funde-os de cima para baixo (ou seja, os ficheiros carregam por ordem, com ficheiros posteriores a sobrepor os anteriores), dando-lhe contexto sobre as tuas preferências pessoais, detalhes específicos do projeto e a tarefa atual:

1. ~/.claude/CLAUDE.md – Defaults globais em todos os projetos
2. ./CLAUDE.md – Definições raiz do repositório
3. ./current-dir/CLAUDE.md – Especificidades atuais do diretório

O Claude Code também suporta regras de projeto (.claude/rules/*.md) e memória local (CLAUDE.local.md) para um controlo mais granular. Para a hierarquia completa da memória, consulte a documentação de memória Claude Code.

O exemplo seguinte mostra um ficheiro CLAUDE.md para um projeto Microsoft Agent Framework. Crie um ficheiro semelhante na raiz do seu projeto para ajudar o Claude Code a compreender a 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 ficheiro, inicie o Claude Code no diretório do seu 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 Azure RBAC

Para conceder aos membros da equipa acesso aos seus modelos Claude alojados na Foundry, atribua um dos seguintes papéis incorporados:

A função Utilizador do Foundry é a função nativa do Foundry recomendada. O papel Utilizador de Serviços Cognitivos é um papel legado que também concede permissões para invocar modelos ao nível do recurso Azure.

Estas funções incluem todas as permissões necessárias para operar o Código Claude com o Foundry.

Para um acesso mais restritivo, crie uma função personalizada definida pelas ações de dados específicas que a sua equipa necessita. Para orientações sobre a definição de papéis personalizados, veja Controlo de acesso baseado em funções para Microsoft Foundry.

Executar código Claude no GitHub Actions

O Claude Code integra-se com o GitHub Actions para automação CI/CD. Armazene a sua chave API no armazenamento secreto do repositório antes de usar estes fluxos de trabalho.

Gerar testes em pull requests

Crie um fluxo de trabalho que gere testes quando os ficheiros de agentes ou ferramentas mudam:

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 }}

Disparar revisão de PR com @claude

Crie um fluxo de trabalho que responda às menções de @claude nos comentários de pedidos pull:

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 }}

Utilização do monitor

Monitorizar a utilização do Código Claude no portal Foundry:

1. Vai a Microsoft Foundry e abre o teu projeto.

2. Navegue para Operar para visualizar métricas de utilização:

   • Consumo de tokens por modelo
   • Latência de pedidos
   • Taxas de erro e ocorrências de limite de taxa

Para definir limites de tokens por pedido, configure a ANTHROPIC_MAX_TOKENS variável de ambiente:

export ANTHROPIC_MAX_TOKENS=100000

$env:ANTHROPIC_MAX_TOKENS = "100000"

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

Liberar recursos

Se deixar de necessitar das implementações do modelo Claude, elimina-as para libertar slots de implementação e a quota no seu recurso. Os modelos Claude usam implantações do Global Standard com cobrança por token, para que as implantações inativas não acarretem encargos. No entanto, cada implementação conta contra o teu limite de implantação de 32 por recurso.

Eliminar implementações no portal Foundry

Use um destes caminhos de navegação:

• Selecione Operar na navegação superior, depois selecione Modelos de Recursos> na navegação à esquerda. Seleciona a implementação que queres eliminar e depois seleciona Eliminar.
• Selecione Construir na navegação superior, depois selecione Modelos na navegação à esquerda. Selecione o nome da implementação para abrir a página de detalhes, selecione o separador Detalhes e depois selecione Eliminar no painel superior.

Eliminar implementações com a CLI do Azure

Execute o comando az cognitiveservices account deployment delete para cada deployment:

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

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

Resolução de problemas

Conteúdo relacionado

• Modelos Claude no Microsoft Foundry
• Implementar e usar modelos Claude no Microsoft Foundry
• Dados, privacidade e segurança para modelos Claude
• Quotas e limites do Microsoft Foundry Models
• Monitorizar a utilização e custos do modelo
• Configure Claude Desktop para Microsoft Foundry
• Claude na Microsoft Foundry (documentação da Anthropic)
• Documentação do Código Claude (Documentação Antrópica)
• Claude Code na Microsoft Foundry (documentação Anthropic)