Configuración de Claude Code para Microsoft Foundry

Anthropic's Claude Code es una herramienta de programación basada en agentes que lee el repositorio de código, edita archivos, ejecuta comandos y se integra con herramientas de desarrollo. Está disponible como una herramienta de la CLI y la extensión de VS Code. Al configurar Claude Code con Microsoft Foundry, ejecute el agente de codificación en la infraestructura de Azure mientras mantiene los datos dentro de los límites de cumplimiento. Esta configuración proporciona seguridad de nivel empresarial, redes privadas, control de acceso basado en roles y administración de costos.

En este artículo, aprenderá a:

• Instalación y configuración de la CLI de Claude Code para Microsoft Foundry
• Configurar la extensión de Claude Code para VS Code
• Autenticar con Microsoft Entra ID o claves de API
• Creación de archivos de contexto de proyecto para mejorar la asistencia de inteligencia artificial
• Ejecución de Claude Code en Acciones de GitHub para la automatización de CI/CD

Para usar modelos de Claude en Microsoft Foundry, debe tener una suscripción de Azure de pago con una cuenta de facturación en un país o región donde Anthropic ofrece los modelos para su compra. Para obtener una lista de errores comunes relacionados con la suscripción, consulte Mensajes y soluciones de error comunes. Actualmente no se admiten los siguientes tipos de suscripción:

• Cuentas empresariales ubicadas en Corea del Sur
• Suscripciones del proveedor de soluciones en la nube
• Suscripciones de Azure que no tienen un método de facturación de pago por uso activo (por ejemplo, estudiantes, evaluación gratuita o cuentas basadas en crédito de inicio)
• Suscripciones patrocinadas que solo usan créditos de Azure. Nota: Si tiene una cuenta con una tarjeta de crédito registrada, la tarjeta de crédito se cobrará en lugar de créditos de Azure.

Para obtener una lista de las regiones admitidas, consulte ubicaciones geográficas admitidas. Tenga en cuenta que, la "Política de Regiones Admitidas" de Anthropic puede aplicarse a la disponibilidad en su región, consulte las regiones admitidas para más detalles.

Requisitos previos

• Una suscripción de Azure con un método de pago válido. Si no tiene una suscripción de Azure, cree una cuenta de Azure de pago.
• Acceso a Microsoft Foundry con permisos de colaborador para crear y administrar recursos.
• Un proyecto de Microsoft Foundry creado en una de las regiones admitidas para las implementaciones de modelos de Claude.
• Colaborador o Propietario en el grupo de recursos Foundry. Para más información, consulte Roles RBAC de Azure.
• Acceso a Azure Marketplace para implementar Modelos de Foundry desde socios.
• Para Windows, use Git Bash (incluido con Git para Windows) o instale WSL2 (recomendado para compatibilidad completa con Linux). Consulte Instalación de WSL.
• (Opcional) CLI de Azure instalada con az login completada para la autenticación de Microsoft Entra ID.

Requisitos del sistema

Implementación de un modelo de Claude en Foundry

Antes de configurar Claude Code, implemente los modelos de Claude disponibles que Necesita Claude Code. La mayoría de los modelos de Claude admiten la implementación estándar global. Para obtener más información sobre los tipos de implementación admitidos, vea Modelos de Claude en Microsoft Foundry.

Claude Code usa modelos diferentes para diferentes tareas:

Implementación del modelo directamente en Foundry

Para implementar un modelo:

1. Siga las instrucciones de Implementación y uso de modelos de Claude en Microsoft Foundry para implementar un modelo de Claude, como Opus 4.6.

2. Después de la implementación, seleccione la pestaña Detalles de la implementación y anote el URI de destino y la clave. Necesita estos valores para la configuración.

Alternativa: Implementación del modelo mediante el enrutador de modelos

Model Router es un modelo foundry que enruta de forma inteligente cada solicitud al mejor modelo subyacente en función de la complejidad, el costo y el rendimiento de las consultas. La versión 2025-11-18 del enrutador de modelos admite modelos de Claude seleccionados (claude-haiku-4-5, claude-sonnet-4-5, claude-opus-4-6, claude-opus-4-7y claude-opus-4-8), junto con otros modelos foundry.

Ventajas para los usuarios de Claude Code:

• Selección automática de modelos: Las indicaciones sencillas se dirigen a modelos más rápidos y económicos. Las tareas de codificación complejas se dirigen a modelos más capaces.
• Optimización de costos: use perfiles de enrutamiento para equilibrar la calidad frente al costo mientras se mantiene el rendimiento de línea base.
• Punto de conexión único: un despliegue controla todas las decisiones de enrutamiento en toda la flota de modelos.

Para usar el enrutador de modelos con Claude Code, implemente primero los modelos de Claude admitidos y, a continuación, implemente el enrutador de modelos y habilite a través de la configuración del subconjunto de modelos.

Instalación de la CLI de Claude Code

Instale la CLI de Claude Code para trabajar con Claude Code directamente en el terminal. A continuación, compruebe que claude está en su PATH ejecutando claude --version.

Instalación nativa (recomendada)

Las instalaciones nativas se actualizan automáticamente en segundo plano para mantenerlo en la versión más reciente.

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

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

Instalación con Homebrew

Si usa macOS:

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

Las instalaciones de Homebrew no se actualizan automáticamente. Ejecute brew upgrade claude-code periódicamente para obtener las características y correcciones de seguridad más recientes.

Solucionar problemas de ubicación de instalación

Si no se encuentra el claude --version comando, agregue la ubicación de instalación a la ruta de acceso como se indica a continuación:

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

Para obtener más opciones de instalación, consulte la documentación de Claude Code.

Configuración de Claude Code para Foundry

Usa el nombre de tu recurso Foundry o la URL base para configurar Claude Code para Foundry.

Para encontrar el nombre de tu recurso de Foundry en el portal de Foundry:

1. Vaya al panel de navegación superior izquierdo y seleccione Administrar>Project detalles.
2. Copie el valor del recurso primario de la página Detalles del proyecto .

Para buscar la dirección URL base desde el portal de Foundry:

1. Vaya a la página principal del portal de Foundry.
2. Busque el punto de conexión del proyecto y copie la parte de la URL que viene antes de /api/projects/<your-project-name>. La dirección URL base tiene el formato https://<your-resource-name>.services.ai.azure.com. Claude Code adjunta /anthropic automáticamente a esta URL cuando utilizas ANTHROPIC_FOUNDRY_RESOURCE.

Establezca variables de entorno para conectar Claude Code a la implementación de 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"

En la tabla siguiente se describe cada variable:

Para conservar estas variables entre sesiones de terminal, agréguelas al perfil de shell (por ejemplo ~/.bashrc , o ~/.zshrc).

Autenticación con Foundry

Claude Code admite dos métodos de autenticación para Microsoft Foundry:

• Microsoft Entra ID (recomendado): usa las credenciales de la CLI de Azure. Lo mejor para entornos empresariales, accesos de equipo y canalizaciones de CI/CD donde se pretende una administración centralizada de identidades sin gestionar secretos.
• Clave de API: usa una clave de API de proyecto desde el portal de Foundry. Lo mejor para pruebas rápidas o entornos en los que la CLI de Azure no está disponible.

Opción A: Id. de Microsoft Entra (recomendado)

La autenticación de Microsoft Entra ID utiliza automáticamente las credenciales de CLI de Azure. Ejecute az login antes de iniciar Claude Code:

1. Inicie sesión con la CLI de Azure:

   az login
   

   Sugerencia

   Si el recurso foundry está en un inquilino diferente al del inquilino predeterminado de la CLI de Azure, especifique el identificador de inquilino:

   az login --tenant <tenant-id>
   

2. Compruebe que el inicio de sesión tiene como destino la suscripción correcta:

   az account show
   

Cuando se usa Microsoft Foundry, los /login comandos y /logout dentro de Claude Code están deshabilitados. La autenticación se controla mediante las credenciales de Azure.

Claude Code detecta la sesión de la CLI de Azure y la usa para la autenticación sin configuración adicional.

Opción B: clave de API

Si prefiere la autenticación de clave de API, establezca la clave en las variables de entorno.

1. En el portal de Microsoft Foundry, abra el recurso.
2. En la página Principal, encuentre el campo Clave API de proyecto.
3. Seleccione Copiar clave de Project API para copiar el valor. Esta es la clave que se usa para la variable de entorno ANTHROPIC_FOUNDRY_API_KEY.
4. Establezca la variable de entorno en el terminal:

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

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

Configuración de la extensión de VS Code

La extensión Claude Code VS Code proporciona una interfaz gráfica nativa para Claude Code directamente en el IDE.

1. Instale la extensión desde Marketplace de VS Code.

2. Abra la configuración de VS Code (Ctrl+, o Cmd+) y busque Claude Code: Variables de entorno.

3. Seleccione Editar en settings.json y agregue la siguiente configuración:

     {
       "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. Seleccione el icono de Spark en la barra lateral para abrir el panel Claude Code.

5. Claude Code se autentica con sus credenciales de Azure. Ejecute az login primero si usa la autenticación de Microsoft Entra ID.

La extensión admite el modo de aceptación automática de ediciones, el modo de planificación, la lógica extendida y la gestión de archivos con menciones del tipo @-mentions, todo ello mientras se enruta a través de la implementación de Microsoft Foundry.

Validación de la configuración

Compruebe que Claude Code está configurado correctamente para usar Microsoft Foundry.

1. Abra un terminal y vaya a un directorio de proyecto:

   cd your-project
   

2. Inicie Claude Code:

   claude
   

   Claude Code tiene como valor predeterminado el modelo sonnet para la codificación general. Si aún no ha implementado los tres modelos, puede especificar un modelo implementado directamente:

   claude --model claude-opus-4-6
   

3. Ejecute el /status comando :

   > /status
   

   La salida debe ser similar al ejemplo siguiente. El formato exacto puede variar en función de la versión de 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 lo siguiente en la salida de estado:

   Campo	Valor esperado
   Proveedor de API	Microsoft Foundry
   Recurso de Foundry	Nombre del recurso de Foundry
   Modelo	El modelo implementado (por ejemplo, claude-sonnet-4-6)

4. Envíe un mensaje de prueba como "Resumir la estructura de este proyecto".

5. Confirme que Claude Code responde con un análisis del proyecto. Una conexión correcta muestra el aviso interactivo de Claude Code sin errores de autenticación.

   Si Claude Code muestra un error como "No se pudo obtener el token" o "el modelo no está disponible", consulte la sección Solución de problemas .

Creación de contexto de proyecto con CLAUDE.md

Mediante archivos CLAUDE.md, puede proporcionar instrucciones y orientación adicional a Claude Code. Claude Code busca CLAUDE.md archivos en los siguientes lugares y los combina de arriba abajo (es decir, los archivos se cargan en orden, con archivos posteriores invalidando los anteriores), lo que le da contexto sobre sus preferencias personales, detalles específicos del proyecto y la tarea actual:

1. ~/.claude/CLAUDE.md – Valores predeterminados globales en todos los proyectos
2. ./CLAUDE.md – Configuración raíz del repositorio
3. ./current-dir/CLAUDE.md – Detalles del directorio actual

Claude Code también admite reglas de proyecto (.claude/rules/*.md) y memoria local (CLAUDE.local.md) para un control más granular. Para obtener la jerarquía de memoria completa, consulte la documentación de memoria de Claude Code.

En el ejemplo siguiente se muestra un CLAUDE.md archivo para un proyecto de Microsoft Agent Framework . Cree un archivo similar en la raíz del proyecto para ayudar a Claude Code a comprender el código base:

# 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

Después de crear un CLAUDE.md archivo, inicie Claude Code en el directorio del proyecto para cargar el 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 RBAC de Azure

Para conceder a los miembros del equipo acceso a los modelos de Claude hospedados en Foundry, asigne uno de los siguientes roles integrados:

El rol Usuario de Foundry es el recomendado de forma nativa en Foundry. El rol de usuario de Cognitive Services es un rol heredado que también concede permisos de invocación de modelos en el nivel de recursos de Azure.

Estos roles incluyen todos los permisos necesarios para ejecutar Claude Code con Foundry.

Para un acceso más restrictivo, cree un rol personalizado con ámbito para las acciones de datos específicas que necesita su equipo. Para obtener instrucciones sobre cómo definir roles personalizados, consulte Control de acceso basado en roles para Microsoft Foundry.

Ejecución de Claude Code en Acciones de GitHub

Claude Code se integra con Acciones de GitHub para la automatización de CI/CD. Almacene la clave de API en el almacén de secretos del repositorio antes de usar estos flujos de trabajo.

Generar pruebas en solicitudes de incorporación de cambios

Cree un flujo de trabajo que genere pruebas cuando cambien los archivos de agente o herramienta:

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

Activar la revisión de PR con @claude

Cree un flujo de trabajo que responda a menciones de @claude en los comentarios de la solicitud de incorporación de cambios:

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

Supervisión del uso

Supervise el uso de Claude Code en el portal de Foundry:

1. Vaya a Microsoft Foundry y abra el proyecto.

2. Vaya a Funcionamiento para ver las métricas de uso:

   • Consumo de tokens por modelo
   • Latencia de solicitud
   • Índices de error y eventos por límite de velocidad

Para establecer límites de token por solicitud, configure la variable de ANTHROPIC_MAX_TOKENS entorno:

export ANTHROPIC_MAX_TOKENS=100000

$env:ANTHROPIC_MAX_TOKENS = "100000"

Para conocer las opciones de configuración que controlan el uso y el costo de los tokens, como los límites de tokens específicos del modelo, consulte la documentación de configuración de Claude Code.

Limpieza de recursos

Si ya no necesita las implementaciones del modelo de Claude, elimínelas para liberar espacios de implementación y cuota de uso en sus recursos. Los modelos de Claude usan implementaciones estándar globales con facturación de pago por token, por lo que las implementaciones inactivas no incurren en cargos. Sin embargo, cada implementación cuenta para el límite de implementaciones de 32 por recurso.

Eliminación de implementaciones en el portal de Foundry

Use cualquiera de estas rutas de navegación:

• Seleccione Operar en el panel de navegación superior y luego elija Recursos>Modelos en el panel de navegación izquierdo. Seleccione la implementación que desea eliminar y, a continuación, seleccione Eliminar.
• Seleccione Compilar en el panel de navegación superior y, a continuación, seleccione Modelos en el panel de navegación izquierdo. Seleccione el nombre de implementación para abrir su página de detalles, seleccione la pestaña Detalles y, a continuación, seleccione Eliminar en el panel superior.

Eliminación de implementaciones con la CLI de Azure

Ejecute el comando az cognitiveservices account deployment delete para cada implementación:

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

Reemplace por <deployment-name> el nombre de implementación del modelo (como claude-sonnet-4-6), <resource-name> por el nombre del recurso Foundry y <resource-group-name> por el grupo de recursos que contiene el recurso Foundry.

Solución de problemas

Contenido relacionado

• Modelos de Claude en Microsoft Foundry
• Implementación y uso de modelos de Claude en Microsoft Foundry
• Datos, privacidad y seguridad para los modelos de Claude
• Límites y cuotas de modelos de Microsoft Foundry
• Supervisión del uso y los costos del modelo
• Configuración de Claude Desktop para Microsoft Foundry
• Claude en Microsoft Foundry (documentos de Anthropic)
• Documentación técnica de Claude Code (Documentos de Anthropic)
• Claude Code en Microsoft Foundry (docs de Anthropic)