Capítulo 2: Instalación y Configuración

Paso 1: Instalar Claude Code CLI

El SDK requiere Claude Code como runtime.

macOS / Linux / WSL

curl -fsSL https://claude.ai/install.sh | bash

Homebrew (macOS)

brew install --cask claude-code

npm (Todas las plataformas)

npm install -g @anthropic-ai/claude-code

Paso 2: Instalar el SDK

Python

pip install claude-agent-sdk

Requisitos: Python 3.10+

TypeScript / Node.js

npm install @anthropic-ai/claude-agent-sdk

Requisitos: Node.js 18+

Paso 3: Configurar API Key

Obtener tu API Key

1. Ve a console.anthropic.com
2. Crea una cuenta o inicia sesión
3. Genera una nueva API Key

Configurar Variable de Entorno

# Linux / macOS
export ANTHROPIC_API_KEY=sk-ant-xxxxx

# Windows (PowerShell)
$env:ANTHROPIC_API_KEY="sk-ant-xxxxx"

# Windows (CMD)
set ANTHROPIC_API_KEY=sk-ant-xxxxx

Archivo .env (Recomendado)

# .env
ANTHROPIC_API_KEY=sk-ant-xxxxx

# Python con python-dotenv
from dotenv import load_dotenv
load_dotenv()

Verificar Instalación

Python

import asyncio
from claude_agent_sdk import query

async def test():
    async for msg in query(prompt="Di 'Hola, instalación exitosa!'"):
        if hasattr(msg, 'result'):
            print(msg.result)

asyncio.run(test())

TypeScript

import { query } from "@anthropic-ai/claude-agent-sdk";

async function test() {
  for await (const msg of query({
    prompt: "Di 'Hola, instalación exitosa!'"
  })) {
    if ("result" in msg) console.log(msg.result);
  }
}

test();

Proveedores Alternativos

Amazon Bedrock

export CLAUDE_CODE_USE_BEDROCK=1
export AWS_ACCESS_KEY_ID=xxx
export AWS_SECRET_ACCESS_KEY=xxx
export AWS_REGION=us-east-1

Google Vertex AI

export CLAUDE_CODE_USE_VERTEX=1
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/credentials.json

Microsoft Foundry

export CLAUDE_CODE_USE_FOUNDRY=1
# Configura credenciales de Azure

Configuración del Directorio de Trabajo

from claude_agent_sdk import query, ClaudeAgentOptions
from pathlib import Path

options = ClaudeAgentOptions(
    cwd="/ruta/a/tu/proyecto"  # o Path("/ruta/a/tu/proyecto")
)

async for msg in query(prompt="Lista los archivos", options=options):
    print(msg)

CLI Personalizado

Si tienes Claude Code en una ruta personalizada:

options = ClaudeAgentOptions(
    cli_path="/ruta/personalizada/claude"
)

Estructura de Proyecto Recomendada

mi-agente/
├── .env                    # API Key (no commitear)
├── .gitignore
├── requirements.txt        # o package.json
├── src/
│   ├── __init__.py
│   ├── agent.py           # Lógica principal
│   ├── tools/             # Herramientas custom
│   │   └── custom_tool.py
│   └── hooks/             # Hooks personalizados
│       └── audit_hook.py
└── tests/
    └── test_agent.py

.gitignore

.env
__pycache__/
*.pyc
node_modules/
.claude/

Solución de Problemas

Error: CLI Not Found

from claude_agent_sdk import CLINotFoundError

try:
    async for msg in query(prompt="test"):
        pass
except CLINotFoundError:
    print("Instala Claude Code: npm i -g @anthropic-ai/claude-code")

Error: API Key Inválida

# Verifica que la variable existe
echo $ANTHROPIC_API_KEY

# Verifica que es válida (empieza con sk-ant-)

Error: Conexión

from claude_agent_sdk import CLIConnectionError

try:
    async for msg in query(prompt="test"):
        pass
except CLIConnectionError:
    print("Verifica tu conexión a internet")

Resumen

• Claude Code CLI es prerequisito del SDK
• API Key de Anthropic es necesaria
• Soporta múltiples proveedores cloud
• Configura cwd para especificar el directorio de trabajo