Claude Code SDK
Construye agentes de IA personalizados con el Claude Code SDK
¿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:
Instala @anthropic-ai/claude-code
desde NPM:
Instala @anthropic-ai/claude-code
desde NPM:
Instala claude-code-sdk
desde PyPI y @anthropic-ai/claude-code
desde NPM:
(Opcional) Instala IPython para desarrollo interactivo:
Configurar tu clave API
Obtén tu clave API desde la Consola de Anthropic y configura la variable de entorno ANTHROPIC_API_KEY
:
Crear tu primer agente
Crea uno de estos agentes de ejemplo:
Ejecutar el agente
Copia y pega el comando de arriba directamente en tu terminal.
Copia y pega el comando de arriba directamente en tu terminal.
- Configurar proyecto:
-
Agregar
"type": "module"
a tu package.json -
Guardar el código de arriba como
legal-agent.ts
, luego ejecutar:
Guardar el código de arriba como legal-agent.py
, luego ejecutar:
Para notebooks de IPython/Jupyter, puedes ejecutar el código directamente en una celda:
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ásico
La 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:
Configuración
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 |
--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.
Prerrequisitos
- Node.js 18+
@anthropic-ai/claude-code
desde NPM
Uso básico
La 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:
Configuración
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 |
--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.
Prerrequisitos
- Node.js 18+
@anthropic-ai/claude-code
desde NPM
Para ver el código fuente del SDK de TypeScript, visita la página de @anthropic-ai/claude-code
en NPM.
Uso básico
La interfaz principal a través del SDK de TypeScript es la función query
, que devuelve un iterador asíncrono que transmite mensajes mientras llegan:
Configuración
El SDK de TypeScript acepta todos los argumentos soportados por la línea de comandos, así como las siguientes opciones adicionales:
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 |
permissionMode | Modo de permisos para la sesión | "default" (opciones: "default" , "acceptEdits" , "plan" , "bypassPermissions" ) |
Prerrequisitos
- Python 3.10+
claude-code-sdk
desde PyPI- Node.js 18+
@anthropic-ai/claude-code
desde NPM
Para ver el código fuente del SDK de Python, consulta el repositorio claude-code-sdk
.
Para desarrollo interactivo, usa IPython: pip install ipython
Uso básico
El SDK de Python proporciona dos interfaces principales:
- La clase
ClaudeSDKClient
(Recomendada)
Mejor para respuestas en streaming, conversaciones de múltiples turnos, y aplicaciones interactivas:
El SDK también soporta pasar mensajes estructurados y entradas de imagen:
Los ejemplos de Python en esta página usan asyncio
, pero también puedes usar anyio
.
- La función
query
Para consultas simples de una sola vez:
Configuración
Como el SDK de Python acepta todos los argumentos soportados por la línea de comandos a través de la clase ClaudeCodeOptions
.
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:
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.
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:
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:
Ejemplos de uso:
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 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:
Ejemplos de implementación:
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
Formatos de salida
El SDK soporta múltiples formatos de salida:
Salida de texto (por defecto)
Salida JSON
Devuelve datos estructurados incluyendo metadatos:
Formato de respuesta:
Salida JSON en streaming
Transmite cada mensaje mientras 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)
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 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
-
Usar formato de salida JSON para análisis programático de respuestas:
-
Manejar errores con gracia - verificar códigos de salida y stderr:
-
Usar gestión de sesiones para mantener contexto en conversaciones de múltiples turnos
-
Considerar timeouts para operaciones de larga duración:
-
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