Saltar al contenido principal
El Agent SDK te proporciona las mismas herramientas, bucle de agente y gestión de contexto que potencian Claude Code. Está disponible como una CLI para scripts e CI/CD, o como paquetes de Python y TypeScript para control programático completo.
La CLI se llamaba anteriormente “modo sin interfaz”. La bandera -p y todas las opciones de CLI funcionan de la misma manera.
Para ejecutar Claude Code programáticamente desde la CLI, pasa -p con tu indicación y cualquier opción de CLI: 
claude -p "Find and fix the bug in auth.py" --allowedTools "Read,Edit,Bash"
Esta página cubre el uso del Agent SDK a través de la CLI (claude -p). Para los paquetes SDK de Python y TypeScript con salidas estructuradas, devoluciones de llamada de aprobación de herramientas y objetos de mensaje nativos, consulta la documentación completa del Agent SDK.

​
Uso básico

Añade la bandera -p (o --print) a cualquier comando claude para ejecutarlo de forma no interactiva. Todas las opciones de CLI funcionan con -p, incluyendo: Este ejemplo le hace una pregunta a Claude sobre tu base de código e imprime la respuesta: 
claude -p "What does the auth module do?"

​
Ejemplos

Estos ejemplos destacan patrones comunes de CLI.

​
Obtener salida estructurada

Usa --output-format para controlar cómo se devuelven las respuestas:
  • text (predeterminado): salida de texto plano
  • json: JSON estructurado con resultado, ID de sesión y metadatos
  • stream-json: JSON delimitado por saltos de línea para transmisión en tiempo real
Este ejemplo devuelve un resumen del proyecto como JSON con metadatos de sesión, con el resultado de texto en el campo result: 
claude -p "Summarize this project" --output-format json
Para obtener una salida que se ajuste a un esquema específico, usa --output-format json con --json-schema y una definición de JSON Schema. La respuesta incluye metadatos sobre la solicitud (ID de sesión, uso, etc.) con la salida estructurada en el campo structured_output. Este ejemplo extrae nombres de funciones y los devuelve como una matriz de cadenas: 
claude -p "Extract the main function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}'
Usa una herramienta como jq para analizar la respuesta y extraer campos específicos:
# Extract the text result
claude -p "Summarize this project" --output-format json | jq -r '.result'

# Extract structured output
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}},"required":["functions"]}' \
  | jq '.structured_output'

​
Aprobar herramientas automáticamente

Usa --allowedTools para permitir que Claude use ciertas herramientas sin preguntar. Este ejemplo ejecuta un conjunto de pruebas y corrige fallos, permitiendo que Claude ejecute comandos Bash y lea/edite archivos sin pedir permiso: 
claude -p "Run the test suite and fix any failures" \
  --allowedTools "Bash,Read,Edit"

​
Crear una confirmación

Este ejemplo revisa los cambios preparados y crea una confirmación con un mensaje apropiado: 
claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff:*),Bash(git log:*),Bash(git status:*),Bash(git commit:*)"
Los comandos de barra como /commit solo están disponibles en modo interactivo. En modo -p, describe la tarea que deseas realizar en su lugar.

​
Personalizar el indicador del sistema

Usa --append-system-prompt para añadir instrucciones mientras mantienes el comportamiento predeterminado de Claude Code. Este ejemplo canaliza un diff de PR a Claude e le indica que revise vulnerabilidades de seguridad: 
gh pr diff "$1" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities." \
  --output-format json
Consulta banderas de indicador del sistema para más opciones incluyendo --system-prompt para reemplazar completamente el indicador predeterminado.

​
Continuar conversaciones

Usa --continue para continuar la conversación más reciente, o --resume con un ID de sesión para continuar una conversación específica. Este ejemplo ejecuta una revisión y luego envía indicaciones de seguimiento: 
# First request
claude -p "Review this codebase for performance issues"

# Continue the most recent conversation
claude -p "Now focus on the database queries" --continue
claude -p "Generate a summary of all issues found" --continue
Si estás ejecutando múltiples conversaciones, captura el ID de sesión para reanudar una específica: 
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

​
Próximos pasos

Inicio rápido del Agent SDK

Construye tu primer agente con Python o TypeScript

Referencia de CLI

Explora todas las banderas y opciones de CLI

GitHub Actions

Usa el Agent SDK en flujos de trabajo de GitHub

GitLab CI/CD

Usa el Agent SDK en canalizaciones de GitLab