SDK de Claude Code
Aprende sobre la integración programática de Claude Code en tus aplicaciones con el SDK de Claude Code.
El SDK de Claude Code permite ejecutar Claude Code como un subproceso, proporcionando una forma de construir asistentes de codificación y herramientas impulsadas por IA que aprovechan las capacidades de Claude.
El SDK está disponible para uso en línea de comandos, TypeScript y Python.
Autenticación
Para usar el SDK de Claude Code, recomendamos crear una clave API dedicada:
- Crea una clave API de Anthropic en la Consola de Anthropic
- Luego, establece la variable de entorno
ANTHROPIC_API_KEY
. Recomendamos almacenar esta clave de forma segura (ej. usando un secreto de Github)
Uso básico del SDK
El SDK de Claude Code te permite usar Claude Code en modo no interactivo desde tus aplicaciones.
Línea de comandos
Aquí hay algunos ejemplos básicos para el SDK de línea de comandos:
TypeScript
El SDK de TypeScript está incluido en el paquete principal @anthropic-ai/claude-code
en NPM:
El SDK de TypeScript acepta todos los argumentos soportados por el SDK de línea de comandos, así como:
Argumento | Descripción | Por defecto |
---|---|---|
abortController | Controlador de aborto | new AbortController() |
cwd | Directorio de trabajo actual | process.cwd() |
executable | Qué runtime de JavaScript usar | node cuando se ejecuta con Node.js, bun cuando se ejecuta con Bun |
executableArgs | Argumentos para pasar al ejecutable | [] |
pathToClaudeCodeExecutable | Ruta al ejecutable de Claude Code | Ejecutable que viene con @anthropic-ai/claude-code |
Python
El SDK de Python está disponible como claude-code-sdk
en PyPI:
Prerrequisitos:
- Python 3.10+
- Node.js
- CLI de Claude Code:
npm install -g @anthropic-ai/claude-code
Uso básico:
El SDK de Python acepta todos los argumentos soportados por el SDK de línea de comandos a través de la clase ClaudeCodeOptions
:
Uso avanzado
La documentación a continuación usa el SDK de línea de comandos como ejemplo, pero también puede usarse con los SDKs de TypeScript y Python.
Conversaciones de múltiples turnos
Para conversaciones de múltiples turnos, puedes reanudar conversaciones o continuar desde la sesión más reciente:
Prompts de sistema personalizados
Puedes proporcionar prompts de sistema personalizados para guiar el comportamiento de Claude:
También puedes añadir instrucciones al prompt de sistema por defecto:
Configuración MCP
El Protocolo de Contexto de Modelo (MCP) te permite extender Claude Code con herramientas y recursos adicionales de servidores externos. Usando la bandera --mcp-config
, puedes cargar servidores MCP que proporcionan capacidades especializadas como acceso a bases de datos, integraciones de API o herramientas personalizadas.
Crea un archivo de configuración JSON con tus servidores MCP:
Luego úsalo con Claude Code:
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 MCPtoolName
es la herramienta específica proporcionada por ese servidor
Esta medida de seguridad asegura que las herramientas MCP solo se usen cuando están explícitamente permitidas.
Si especificas solo el nombre del servidor (es decir, mcp__<serverName>
), todas las herramientas de ese servidor serán permitidas.
Los patrones glob (ej., mcp__go*
) no están 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 ocurre 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 niega la llamada a la herramienta, procedemos con la llamada a la 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:
Por ejemplo, una implementación de herramienta de prompt de permisos MCP en TypeScript podría verse así:
Para usar esta herramienta, añade tu servidor MCP (ej. con --mcp-config
), luego invoca el SDK así:
Notas de uso:
- Usa
updatedInput
para decirle al modelo que el prompt de permisos mutó su entrada; de lo contrario, estableceupdatedInput
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
Opciones CLI disponibles
El SDK aprovecha todas las opciones CLI disponibles en Claude Code. Aquí están las principales para 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 logging verboso | claude --verbose |
--max-turns | Limitar turnos agénticos en modo no interactivo | claude --max-turns 3 |
--system-prompt | Sobrescribir prompt de sistema (solo con --print ) | claude --system-prompt "Instrucción personalizada" |
--append-system-prompt | Añadir al prompt de 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.
Formatos de salida
El SDK soporta múltiples formatos de salida:
Salida de texto (por defecto)
Devuelve solo el texto de respuesta:
Salida JSON
Devuelve datos estructurados incluyendo metadatos:
Formato de respuesta:
Salida JSON en streaming
Transmite cada mensaje a medida que se recibe:
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:
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)
El texto de entrada puede proporcionarse como argumento:
O el texto de entrada puede enviarse por pipe vía stdin:
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.
Ejemplos
Integración de script simple
Procesando archivos con Claude
Gestión de sesiones
Mejores prácticas
-
Usa formato de salida JSON para análisis programático de respuestas:
-
Maneja errores con gracia - verifica códigos de salida y stderr:
-
Usa gestión de sesiones para mantener contexto en conversaciones de múltiples turnos
-
Considera timeouts para operaciones de larga duración:
-
Respeta límites de tasa cuando hagas múltiples solicitudes añadiendo retrasos entre llamadas
Aplicaciones del mundo real
El SDK de Claude Code permite integraciones poderosas con tu flujo de trabajo de desarrollo. Un ejemplo notable son las GitHub Actions de Claude Code, que usa el SDK para proporcionar capacidades de revisión de código automatizada, creación de PR y triaje de issues directamente en tu flujo de trabajo de GitHub.
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