Claude Code SDK - Anthropic

¿Por qué usar el Claude Code SDK?

El Claude Code SDK proporciona todos los bloques de construcción que necesitas para construir agentes listos para producción:

Integración optimizada con Claude: Caché automático de prompts y optimizaciones de rendimiento
Ecosistema rico de herramientas: Operaciones de archivos, ejecución de código, búsqueda web, y extensibilidad MCP
Permisos avanzados: Control granular sobre las capacidades del agente
Elementos esenciales de producción: Manejo de errores integrado, gestión de sesiones, y monitoreo

¿Qué puedes construir con el SDK?

Aquí hay algunos tipos de agentes de ejemplo que puedes crear: Agentes de codificación:

Agentes SRE que diagnostican y solucionan problemas de producción
Bots de revisión de seguridad que auditan código en busca de vulnerabilidades
Asistentes de ingeniería de guardia que clasifican incidentes
Agentes de revisión de código que hacen cumplir el estilo y las mejores prácticas

Agentes de negocio:

Asistentes legales que revisan contratos y cumplimiento
Asesores financieros que analizan informes y pronósticos
Agentes de soporte al cliente que resuelven problemas técnicos
Asistentes de creación de contenido para equipos de marketing

El SDK está actualmente disponible en TypeScript y Python, con una interfaz de línea de comandos (CLI) para prototipado rápido.

Inicio rápido

Pon tu primer agente en funcionamiento en menos de 5 minutos:

Instalar el SDK

Instala @anthropic-ai/claude-code desde NPM:

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

Configurar tu clave API

Obtén tu clave API desde la Consola de Anthropic y configura la variable de entorno ANTHROPIC_API_KEY:

export ANTHROPIC_API_KEY="tu-clave-api-aqui"

Crear tu primer agente

Crea uno de estos agentes de ejemplo:

# Crear un asistente legal simple
claude -p "Revisa esta cláusula de contrato en busca de problemas potenciales: 'La parte acepta responsabilidad ilimitada...'" \
  --append-system-prompt "Eres un asistente legal. Identifica riesgos y sugiere mejoras."

Ejecutar el agente

Copia y pega el comando de arriba directamente en tu terminal.

Cada ejemplo anterior crea un agente funcional que:

Analiza el prompt usando las capacidades de razonamiento de Claude
Planifica un enfoque de múltiples pasos para resolver el problema
Ejecuta acciones usando herramientas como operaciones de archivos, comandos bash, y búsqueda web
Proporciona recomendaciones accionables basadas en el análisis

Uso principal

Descripción general

El Claude Code SDK te permite interactuar con Claude Code en modo no interactivo desde tus aplicaciones.

Prerrequisitos

Node.js 18+
@anthropic-ai/claude-code desde NPM

Uso básicoLa interfaz principal de línea de comandos para Claude Code es el comando claude. Usa la bandera --print (o -p) para ejecutar en modo no interactivo e imprimir el resultado final:

claude -p "Analizar rendimiento del sistema" \
  --append-system-prompt "Eres un ingeniero de rendimiento" \
  --allowedTools "Bash,Read,WebSearch" \
  --permission-mode acceptEdits \
  --cwd /ruta/al/proyecto

ConfiguraciónEl SDK aprovecha todas las opciones CLI disponibles en Claude Code. Aquí están las principales para el uso del SDK:

Bandera	Descripción	Ejemplo
`--print`, `-p`	Ejecutar en modo no interactivo	`claude -p "consulta"`
`--output-format`	Especificar formato de salida (`text`, `json`, `stream-json`)	`claude -p --output-format json`
`--resume`, `-r`	Reanudar una conversación por ID de sesión	`claude --resume abc123`
`--continue`, `-c`	Continuar la conversación más reciente	`claude --continue`
`--verbose`	Habilitar registro detallado	`claude --verbose`
`--append-system-prompt`	Agregar al prompt del sistema (solo con `--print`)	`claude --append-system-prompt "Instrucción personalizada"`
`--allowedTools`	Lista separada por espacios de herramientas permitidas, o cadena de lista separada por comas de herramientas permitidas	`claude --allowedTools mcp__slack mcp__filesystem` `claude --allowedTools "Bash(npm install),mcp__filesystem"`
`--disallowedTools`	Lista separada por espacios de herramientas denegadas, o cadena de lista separada por comas de herramientas denegadas	`claude --disallowedTools mcp__splunk mcp__github` `claude --disallowedTools "Bash(git commit),mcp__github"`
`--mcp-config`	Cargar servidores MCP desde un archivo JSON	`claude --mcp-config servers.json`
`--permission-prompt-tool`	Herramienta MCP para manejar prompts de permisos (solo con `--print`)	`claude --permission-prompt-tool mcp__auth__prompt`

Para una lista completa de opciones CLI y características, consulta la documentación de referencia CLI.

Autenticación

Clave API de Anthropic

Para autenticación básica, obtén una clave API de Anthropic desde la Consola de Anthropic y configura la variable de entorno ANTHROPIC_API_KEY, como se demuestra en el Inicio rápido.

Credenciales de API de terceros

El SDK también soporta autenticación a través de proveedores de API de terceros:

Amazon Bedrock: Configura la variable de entorno CLAUDE_CODE_USE_BEDROCK=1 y configura las credenciales de AWS
Google Vertex AI: Configura la variable de entorno CLAUDE_CODE_USE_VERTEX=1 y configura las credenciales de Google Cloud

Para instrucciones de configuración detalladas para proveedores de terceros, consulta la documentación de Amazon Bedrock y Google Vertex AI.

Conversaciones de múltiples turnos

Para conversaciones de múltiples turnos, puedes reanudar conversaciones o continuar desde la sesión más reciente:

# Continuar la conversación más reciente
claude --continue "Ahora refactoriza esto para mejor rendimiento"

# Reanudar una conversación específica por ID de sesión
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Actualizar las pruebas"

# Reanudar en modo no interactivo
claude --resume 550e8400-e29b-41d4-a716-446655440000 "Corregir todos los problemas de linting" --no-interactive

Usar Modo Plan

El Modo Plan permite a Claude analizar código sin hacer modificaciones, útil para revisiones de código y planificación de cambios.

claude -p "Revisar este código" --permission-mode plan

El Modo Plan restringe la edición, creación de archivos, y ejecución de comandos. Consulta modos de permisos para detalles.

Prompts de sistema personalizados

Los prompts de sistema definen el rol, experiencia y comportamiento de tu agente. Aquí es donde especificas qué tipo de agente estás construyendo:

# Agente de respuesta a incidentes SRE
claude -p "La API está caída, investigar" \
  --append-system-prompt "Eres un experto SRE. Diagnostica problemas sistemáticamente y proporciona soluciones accionables."

# Agente de revisión de documentos legales  
claude -p "Revisar este contrato" \
  --append-system-prompt "Eres un abogado corporativo. Identifica riesgos, sugiere mejoras, y asegura el cumplimiento."

# Agregar al prompt de sistema por defecto
claude -p "Refactorizar esta función" \
  --append-system-prompt "Siempre incluye manejo de errores integral y pruebas unitarias."

Uso Avanzado

Herramientas personalizadas vía MCP

El Protocolo de Contexto de Modelo (MCP) te permite dar a tus agentes herramientas y capacidades personalizadas. Esto es crucial para construir agentes especializados que necesitan integraciones específicas del dominio. Configuraciones de herramientas de agente de ejemplo:

{
  "mcpServers": {
    "slack": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-slack"],
      "env": {"SLACK_TOKEN": "tu-token-slack"}
    },
    "jira": {
      "command": "npx", 
      "args": ["-y", "@modelcontextprotocol/server-jira"],
      "env": {"JIRA_TOKEN": "tu-token-jira"}
    },
    "database": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres"],
      "env": {"DB_CONNECTION_STRING": "tu-url-db"}
    }
  }
}

Ejemplos de uso:

# Agente SRE con herramientas de monitoreo
claude -p "Investigar la interrupción del servicio de pagos" \
  --mcp-config sre-tools.json \
  --allowedTools "mcp__datadog,mcp__pagerduty,mcp__kubernetes" \
  --append-system-prompt "Eres un SRE. Usa datos de monitoreo para diagnosticar problemas."

# Agente de soporte al cliente con acceso a CRM
claude -p "Ayudar a resolver el ticket de cliente #12345" \
  --mcp-config support-tools.json \
  --allowedTools "mcp__zendesk,mcp__stripe,mcp__user_db" \
  --append-system-prompt "Eres un especialista en soporte técnico."

Cuando uses herramientas MCP, debes permitirlas explícitamente usando la bandera --allowedTools. Los nombres de herramientas MCP siguen el patrón mcp__<serverName>__<toolName> donde:

serverName es la clave de tu archivo de configuración MCP
toolName es la herramienta específica proporcionada por ese servidor

Esta medida de seguridad asegura que las herramientas MCP solo se usen cuando se permiten explícitamente.Si especificas solo el nombre del servidor (es decir, mcp__<serverName>), todas las herramientas de ese servidor serán permitidas.Los patrones glob (por ejemplo, mcp__go*) no son soportados.

Herramienta de prompt de permisos personalizada

Opcionalmente, usa --permission-prompt-tool para pasar una herramienta MCP que usaremos para verificar si el usuario otorga permisos al modelo para invocar una herramienta dada. Cuando el modelo invoca una herramienta sucede lo siguiente:

Primero verificamos la configuración de permisos: todos los archivos settings.json, así como --allowedTools y --disallowedTools pasados al SDK; si uno de estos permite o deniega la llamada de herramienta, procedemos con la llamada de herramienta
De lo contrario, invocamos la herramienta MCP que proporcionaste en --permission-prompt-tool

La herramienta MCP --permission-prompt-tool recibe el nombre de la herramienta y la entrada, y debe devolver una carga útil JSON-stringified con el resultado. La carga útil debe ser una de:

// la llamada de herramienta está permitida
{
  "behavior": "allow",
  "updatedInput": {...}, // entrada actualizada, o simplemente devolver la entrada original
}

// la llamada de herramienta está denegada
{
  "behavior": "deny",
  "message": "..." // cadena legible por humanos explicando por qué se denegó el permiso
}

Ejemplos de implementación:

# Usar con tu configuración de servidor MCP
claude -p "Analizar y corregir los problemas de seguridad" \
  --permission-prompt-tool mcp__security__approval_prompt \
  --mcp-config security-tools.json \
  --allowedTools "Read,Grep" \
  --disallowedTools "Bash(rm*),Write"

# Con reglas de permisos personalizadas
claude -p "Refactorizar la base de código" \
  --permission-prompt-tool mcp__custom__permission_check \
  --mcp-config custom-config.json \
  --output-format json

Notas de uso:

Usa updatedInput para decirle al modelo que el prompt de permisos mutó su entrada; de lo contrario, establece updatedInput a la entrada original, como en el ejemplo anterior. Por ejemplo, si la herramienta muestra un diff de edición de archivo al usuario y le permite editar el diff manualmente, la herramienta de prompt de permisos debería devolver esa edición actualizada.
La carga útil debe ser JSON-stringified

Formatos de salida

El SDK soporta múltiples formatos de salida:

Salida de texto (por defecto)

claude -p "Explicar archivo src/components/Header.tsx"
# Salida: Este es un componente React que muestra...

Salida JSON

Devuelve datos estructurados incluyendo metadatos:

claude -p "¿Cómo funciona la capa de datos?" --output-format json

Formato de respuesta:

{
  "type": "result",
  "subtype": "success",
  "total_cost_usd": 0.003,
  "is_error": false,
  "duration_ms": 1234,
  "duration_api_ms": 800,
  "num_turns": 6,
  "result": "El texto de respuesta aquí...",
  "session_id": "abc123"
}

Salida JSON en streaming

Transmite cada mensaje mientras se recibe:

$ claude -p "Construir una aplicación" --output-format stream-json

Cada conversación comienza con un mensaje de sistema init inicial, seguido de una lista de mensajes de usuario y asistente, seguido de un mensaje de sistema result final con estadísticas. Cada mensaje se emite como un objeto JSON separado.

Esquema de mensajes

Los mensajes devueltos desde la API JSON están estrictamente tipados según el siguiente esquema:

type SDKMessage =
  // Un mensaje del asistente
  | {
      type: "assistant";
      message: Message; // del SDK de Anthropic
      session_id: string;
    }

  // Un mensaje del usuario
  | {
      type: "user";
      message: MessageParam; // del SDK de Anthropic
      session_id: string;
    }

  // Emitido como el último mensaje
  | {
      type: "result";
      subtype: "success";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      result: string;
      session_id: string;
      total_cost_usd: float;
    }

  // Emitido como el último mensaje, cuando hemos alcanzado el número máximo de turnos
  | {
      type: "result";
      subtype: "error_max_turns" | "error_during_execution";
      duration_ms: float;
      duration_api_ms: float;
      is_error: boolean;
      num_turns: int;
      session_id: string;
      total_cost_usd: float;
    }

  // Emitido como el primer mensaje al inicio de una conversación
  | {
      type: "system";
      subtype: "init";
      apiKeySource: string;
      cwd: string;
      session_id: string;
      tools: string[];
      mcp_servers: {
        name: string;
        status: string;
      }[];
      model: string;
      permissionMode: "default" | "acceptEdits" | "bypassPermissions" | "plan";
    };

Pronto publicaremos estos tipos en un formato compatible con JSONSchema. Usamos versionado semántico para el paquete principal de Claude Code para comunicar cambios que rompen la compatibilidad con este formato. Los tipos Message y MessageParam están disponibles en los SDKs de Anthropic. Por ejemplo, consulta los SDKs de Anthropic para TypeScript y Python.

Formatos de entrada

El SDK soporta múltiples formatos de entrada:

Entrada de texto (por defecto)

# Argumento directo
claude -p "Explicar este código"

# Desde stdin
echo "Explicar este código" | claude -p

Entrada JSON en streaming

Un flujo de mensajes proporcionado vía stdin donde cada mensaje representa un turno del usuario. Esto permite múltiples turnos de una conversación sin relanzar el binario claude y permite proporcionar orientación al modelo mientras está procesando una solicitud. Cada mensaje es un objeto JSON ‘Mensaje de usuario’, siguiendo el mismo formato que el esquema de mensaje de salida. Los mensajes se formatean usando el formato jsonl donde cada línea de entrada es un objeto JSON completo. La entrada JSON en streaming requiere -p y --output-format stream-json. Actualmente esto está limitado a mensajes de usuario solo de texto.

$ echo '{"type":"user","message":{"role":"user","content":[{"type":"text","text":"Explicar este código"}]}}' | claude -p --output-format=stream-json --input-format=stream-json --verbose

Ejemplos de integración de agentes

Bot de respuesta a incidentes SRE

#!/bin/bash

# Agente de respuesta a incidentes automatizado
investigate_incident() {
    local incident_description="$1"
    local severity="${2:-medium}"
    
    claude -p "Incidente: $incident_description (Severidad: $severity)" \
      --append-system-prompt "Eres un experto SRE. Diagnostica el problema, evalúa el impacto, y proporciona elementos de acción inmediatos." \
      --output-format json \
      --allowedTools "Bash,Read,WebSearch,mcp__datadog" \
      --mcp-config monitoring-tools.json
}

# Uso
investigate_incident "API de pagos devolviendo errores 500" "high"

Revisión de seguridad automatizada

# Agente de auditoría de seguridad para pull requests
audit_pr() {
    local pr_number="$1"
    
    gh pr diff "$pr_number" | claude -p \
      --append-system-prompt "Eres un ingeniero de seguridad. Revisa este PR en busca de vulnerabilidades, patrones inseguros, y problemas de cumplimiento." \
      --output-format json \
      --allowedTools "Read,Grep,WebSearch"
}

# Uso y guardar en archivo
audit_pr 123 > security-report.json

Asistente legal de múltiples turnos

# Revisión de documentos legales con persistencia de sesión
session_id=$(claude -p "Iniciar sesión de revisión legal" --output-format json | jq -r '.session_id')

# Revisar contrato en múltiples pasos
claude -p --resume "$session_id" "Revisar contract.pdf en busca de cláusulas de responsabilidad"
claude -p --resume "$session_id" "Verificar cumplimiento con requisitos GDPR" 
claude -p --resume "$session_id" "Generar resumen ejecutivo de riesgos"

Mejores Prácticas Específicas de Python

Patrones Clave

import asyncio
from claude_code_sdk import ClaudeSDKClient, ClaudeCodeOptions

# Siempre usar gestores de contexto
async with ClaudeSDKClient() as client:
    await client.query("Analizar este código")
    async for msg in client.receive_response():
        # Procesar mensajes en streaming
        pass

# Ejecutar múltiples agentes concurrentemente
async with ClaudeSDKClient() as reviewer, ClaudeSDKClient() as tester:
    await asyncio.gather(
        reviewer.query("Revisar main.py"),
        tester.query("Escribir pruebas para main.py")
    )

# Manejo de errores
from claude_code_sdk import CLINotFoundError, ProcessError

try:
    async with ClaudeSDKClient() as client:
        # Tu código aquí
        pass
except CLINotFoundError:
    print("Instalar CLI: npm install -g @anthropic-ai/claude-code")
except ProcessError as e:
    print(f"Error de proceso: {e}")

# Recopilar respuesta completa con metadatos
async def get_response(client, prompt):
    await client.query(prompt)
    text = []
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    text.append(block.text)
        if type(msg).__name__ == "ResultMessage":
            return {'text': ''.join(text), 'cost': msg.total_cost_usd}

Consejos para IPython/Jupyter

# En Jupyter, usar await directamente en celdas
client = ClaudeSDKClient()
await client.connect()
await client.query("Analizar data.csv")
async for msg in client.receive_response():
    print(msg)
await client.disconnect()

# Crear funciones auxiliares reutilizables
async def stream_print(client, prompt):
    await client.query(prompt)
    async for msg in client.receive_response():
        if hasattr(msg, 'content'):
            for block in msg.content:
                if hasattr(block, 'text'):
                    print(block.text, end='', flush=True)

Mejores prácticas

Usar formato de salida JSON para análisis programático de respuestas:

# Analizar respuesta JSON con jq
result=$(claude -p "Generar código" --output-format json)
code=$(echo "$result" | jq -r '.result')
cost=$(echo "$result" | jq -r '.cost_usd')

Manejar errores con gracia - verificar códigos de salida y stderr:

if ! claude -p "$prompt" 2>error.log; then
    echo "Ocurrió un error:" >&2
    cat error.log >&2
    exit 1
fi

Usar gestión de sesiones para mantener contexto en conversaciones de múltiples turnos

Considerar timeouts para operaciones de larga duración:

timeout 300 claude -p "$complex_prompt" || echo "Tiempo agotado después de 5 minutos"

Respetar límites de tasa cuando hagas múltiples solicitudes agregando retrasos entre llamadas

Recursos relacionados

Uso y controles CLI - Documentación completa de CLI
Integración con GitHub Actions - Automatiza tu flujo de trabajo de GitHub con Claude
Flujos de trabajo comunes - Guías paso a paso para casos de uso comunes

Release Notes

​¿Por qué usar el Claude Code SDK?

​¿Qué puedes construir con el SDK?

​Inicio rápido

​Uso principal

​Descripción general

​Autenticación

​Clave API de Anthropic

​Credenciales de API de terceros

​Conversaciones de múltiples turnos

​Usar Modo Plan

​Prompts de sistema personalizados

​Uso Avanzado

​Herramientas personalizadas vía MCP

​Herramienta de prompt de permisos personalizada

​Formatos de salida

​Salida de texto (por defecto)

​Salida JSON

​Salida JSON en streaming

​Esquema de mensajes

​Formatos de entrada

​Entrada de texto (por defecto)

​Entrada JSON en streaming

​Ejemplos de integración de agentes

​Bot de respuesta a incidentes SRE

​Revisión de seguridad automatizada

​Asistente legal de múltiples turnos

​Mejores Prácticas Específicas de Python

​Patrones Clave

​Consejos para IPython/Jupyter

​Mejores prácticas

​Recursos relacionados

¿Por qué usar el Claude Code SDK?

¿Qué puedes construir con el SDK?

Inicio rápido

Uso principal

Descripción general

Autenticación

Clave API de Anthropic

Credenciales de API de terceros

Conversaciones de múltiples turnos

Usar Modo Plan

Prompts de sistema personalizados

Uso Avanzado

Herramientas personalizadas vía MCP

Herramienta de prompt de permisos personalizada

Formatos de salida

Salida de texto (por defecto)

Salida JSON

Salida JSON en streaming

Esquema de mensajes

Formatos de entrada

Entrada de texto (por defecto)

Entrada JSON en streaming

Ejemplos de integración de agentes

Bot de respuesta a incidentes SRE

Revisión de seguridad automatizada

Asistente legal de múltiples turnos

Mejores Prácticas Específicas de Python

Patrones Clave

Consejos para IPython/Jupyter

Mejores prácticas

Recursos relacionados