SDK
Integra Claude Code programáticamente en tus aplicaciones usando el SDK.
El SDK de Claude Code permite a los desarrolladores integrar Claude Code programáticamente en sus aplicaciones. Permite ejecutar Claude Code como un subproceso, proporcionando una forma de crear asistentes y herramientas de codificación potenciados 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 (por ejemplo, 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 compatibles con el SDK de línea de comandos, así como:
Argumento | Descripción | Valor predeterminado |
---|---|---|
abortController | Controlador de aborto | new AbortController() |
cwd | Directorio de trabajo actual | process.cwd() |
executable | Qué entorno de ejecución 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:
Requisitos previos:
- 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 compatibles con el SDK de línea de comandos a través de la clase ClaudeCodeOptions
:
Uso avanzado
La documentación a continuación utiliza el SDK de línea de comandos como ejemplo, pero también se puede usar con los SDK 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 predeterminado:
Configuración MCP
El Protocolo de Contexto del 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:
Al usar herramientas MCP, debes permitirlas explícitamente usando la bandera --allowedTools
. Los nombres de las 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 garantiza que las herramientas MCP solo se utilicen cuando estén explícitamente permitidas.
Si especificas solo el nombre del servidor (es decir, mcp__<serverName>
), se permitirán todas las herramientas de ese servidor.
No se admiten patrones glob (por ejemplo, mcp__go*
).
Herramienta personalizada de solicitud de permisos
Opcionalmente, usa --permission-prompt-tool
para pasar una herramienta MCP que usaremos para verificar si el usuario otorga al modelo permisos para invocar una herramienta determinada. 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 deniega 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 las siguientes:
Por ejemplo, una implementación de herramienta MCP de solicitud de permisos en TypeScript podría verse así:
Para usar esta herramienta, agrega tu servidor MCP (por ejemplo, con --mcp-config
), luego invoca el SDK así:
Notas de uso:
- Usa
updatedInput
para indicar al modelo que la solicitud de permiso modificó 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 les permite editar el diff manualmente, la herramienta de solicitud de permiso debe devolver esa edición actualizada. - La carga útil debe estar en formato JSON-stringified
Opciones CLI disponibles
El 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 |
--max-turns | Limitar turnos agénticos en modo no interactivo | claude --max-turns 3 |
--system-prompt | Anular 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 solicitudes de permisos (solo con --print ) | claude --permission-prompt-tool mcp__auth__prompt |
Para una lista completa de opciones y características CLI, consulta la documentación Uso de CLI.
Formatos de salida
El SDK admite múltiples formatos de salida:
Salida de texto (predeterminado)
Devuelve solo el texto de respuesta:
Salida JSON
Devuelve datos estructurados que incluyen 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 inicial init
, seguido de una lista de mensajes de usuario y asistente, seguido de un mensaje de sistema final result
con estadísticas. Cada mensaje se emite como un objeto JSON separado.
Esquema de mensajes
Los mensajes devueltos por 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 importantes en este formato.
Los tipos Message
y MessageParam
están disponibles en los SDK de Anthropic. Por ejemplo, consulta los SDK de Anthropic TypeScript y Python.
Ejemplos
Integración simple de scripts
Procesamiento de archivos con Claude
Gestión de sesiones
Mejores prácticas
-
Usa el formato de salida JSON para el análisis programático de respuestas:
-
Maneja los errores con elegancia - verifica los códigos de salida y stderr:
-
Usa la gestión de sesiones para mantener el contexto en conversaciones de múltiples turnos
-
Considera los tiempos de espera para operaciones de larga duración:
-
Respeta los límites de tasa cuando realices múltiples solicitudes añadiendo retrasos entre llamadas
Aplicaciones del mundo real
El SDK de Claude Code permite integraciones potentes con tu flujo de trabajo de desarrollo. Un ejemplo notable son las Acciones de GitHub de Claude Code, que utilizan el SDK para proporcionar capacidades automatizadas de revisión de código, creación de PR y clasificación de problemas directamente en tu flujo de trabajo de GitHub.
Recursos relacionados
- Uso y controles de CLI - Documentación completa de CLI
- Integración con GitHub Actions - Automatiza tu flujo de trabajo de GitHub con Claude
- Tutoriales - Guías paso a paso para casos de uso comunes