Agentes y automatización

El SDK de agentes Claude

El SDK de agentes Claude (Software Development Kit) es la biblioteca oficial de Anthropic que permite crear programas en los que Claude actúa de forma autónoma: lee entradas, decide qué herramientas llamar, las ejecuta, lee los resultados y repite el ciclo hasta completar la tarea. Esto es diferente de un simple mensaje de chat porque el modelo gestiona un flujo de trabajo de múltiples pasos, no solo una respuesta única.

El SDK se publica como @anthropic-ai/claude-code-sdk para JavaScript/TypeScript y ofrece una interfaz similar en Python. Su núcleo expone una función de streaming llamada query() que envía un prompt a Claude, transmite en tiempo real cada turno de asistente y cada bloque de uso de herramienta (cada acción discreta que Claude decide ejecutar), y permite que tu código reaccione a cada evento en tiempo real.

Lo que puedes construir abarca un amplio espectro:

• Agentes de código sin interfaz: ejecuta Claude Code de forma no interactiva dentro de un pipeline CI/CD (pipeline de integración continua, sistema automatizado de construcción y pruebas) para escribir, corregir o revisar código en cada commit.
• Integraciones IDE personalizadas: integra Claude en cualquier editor redirigiendo su salida hacia tu propia interfaz en lugar del terminal.
• Pipelines multiagente: una instancia de Claude actúa como orquestador que lanza subagentes, cada uno con permisos más limitados y una subtarea específica.
• Flujos de aprobación: intercepta cada llamada a herramienta antes de su ejecución para que un humano (u otro modelo) pueda aprobarla, rechazarla o modificarla.

El SDK aplica el mismo modelo de permisos que Claude Code interactivo: declaras qué herramientas están permitidas (lecturas de archivos, comandos de shell, servidores MCP) y el agente no puede exceder ese alcance. Esto lo hace seguro para ejecutarse en entornos automatizados sin supervisión humana.

Anatomía de un bucle agentivo

Un bucle agentivo es el ciclo repetitivo que permite a un modelo de IA realizar trabajo de varios pasos de forma autónoma. En lugar de responder una vez y detenerse, el modelo recorre cuatro fases una y otra vez hasta que la tarea se completa o decide detenerse.

Las cuatro fases son:

1. Percibir: el modelo lee su contexto actual (tu objetivo, resultados anteriores, salidas de herramientas, memoria).
2. Decidir: elige la siguiente acción (llamar a una herramienta, escribir un archivo, hacer una pregunta de aclaración o declarar que ha terminado).
3. Actuar: ejecuta esa acción, por ejemplo ejecutando un comando de shell o editando un archivo.
4. Observar: lee el resultado (stdout, mensaje de error, diff de archivo) y lo agrega al contexto, luego vuelve a la fase Percibir.

Claude Code (el agente de codificación CLI e IDE) está construido alrededor de este bucle. Cada iteración se llama un turno. El bucle termina cuando el modelo emite una respuesta de texto final en lugar de otra llamada a herramienta, o cuando se alcanza una condición de parada que hayas definido (presupuesto de tokens, turnos máximos o una salida explícita).

Comprender el bucle es importante porque cada fallo que tendrás que depurar en un agente, ya sea que gire indefinidamente, se rinda demasiado pronto o omita un paso, se origina en una de estas cuatro fases que sale mal.

Definir las herramientas en las que un agente puede confiar

Una herramienta es una función que se expone a un agente para que pueda realizar acciones más allá de generar texto: consultar una base de datos, llamar a una API, leer un archivo. El agente decide cuándo invocar cada herramienta basándose únicamente en la información que se le proporciona en la definición de la herramienta. Si esa definición es vaga, el agente adivina y, con frecuencia, se equivoca.

Cada definición de herramienta tiene tres partes que el agente lee antes de decidir si la utiliza:

• Nombre: corto, sin ambigüedad, en snake_case (por ejemplo get_order_status en lugar de tool1 o fetch). El nombre por sí solo debe sugerir lo que hace la herramienta.
• Descripción: una o dos oraciones que expliquen qué hace la herramienta, cuándo usarla y cuándo NO usarla. Este es el campo más importante. El modelo lo lee como contexto de razonamiento, no solo como documentación.
• Esquema: un objeto JSON Schema que lista cada parámetro, su tipo, si es obligatorio y una descripción breve de cada campo. Las descripciones de parámetros ambiguas o ausentes provocan alucinaciones silenciosas en las que el agente rellena los vacíos con valores de apariencia plausible.

Una herramienta bien definida es autónoma: otro desarrollador (u otro modelo) debe poder leer la definición sola y saber exactamente cuándo y cómo llamarla. Trate la descripción como un contrato, no como un comentario.

Automatización sin interfaz en scripts

El modo headless consiste en ejecutar Claude Code sin ninguna solicitud interactiva: sin teclado, sin terminal esperando su entrada. Usted envía la entrada mediante una tubería, Claude la procesa y su script lee la salida. Así es como se integra Claude dentro de pipelines de CI, tareas cron o cualquier flujo de trabajo automatizado.

El flag clave es --print (abreviado: -p), que indica a Claude Code que imprima la respuesta final y salga de inmediato. Combínelo con --output-format json para obtener una salida estructurada que su script pueda analizar de forma fiable. Use --model para fijar un identificador de modelo específico de modo que su pipeline nunca realice actualizaciones silenciosas.

Algunos flags son importantes en la automatización:

• --print: modo no interactivo, imprime el resultado y sale.
• --output-format json: envuelve la respuesta en un contenedor JSON con los campos result, cost y session_id.
• --model claude-sonnet-4-6: fija el modelo (opciones: claude-opus-4-8, claude-sonnet-4-6, claude-haiku-4-5).
• --max-turns N: limita el número de turnos agentivos para que un bucle desbocado no gire indefinidamente.
• --no-ansi: elimina los códigos de color para que los archivos de registro se mantengan limpios.

La entrada estándar también funciona: redirija un archivo o una solicitud generada directamente a claude mediante una tubería. El proceso termina con el código 0 en caso de éxito y con un código distinto de cero en caso de error, de modo que su shell o script Node puede gestionar los fallos de la manera habitual.

Claude en GitHub Actions

GitHub Actions es una plataforma CI/CD (Integración Continua / Entrega Continua) integrada en GitHub. Cada push, pull request o disparador programado puede ejecutar un workflow, un archivo YAML que ejecuta pasos dentro de un contenedor. Claude puede ser uno de esos pasos, convirtiendo una revisión a nivel humano en una comprobación automatizada que se ejecuta en cada pull request sin necesidad de esperar a un compañero de equipo.

El punto de entrada oficial es claude-code-action, una GitHub Action de código abierto publicada por Anthropic. Se agrega al YAML del workflow, se pasa la ANTHROPIC_API_KEY como secreto, y la action lanza Claude Code en un contenedor sin interfaz gráfica. Claude lee el diff, los archivos del repositorio y las instrucciones proporcionadas, luego publica sus hallazgos como comentario de PR o establece un estado de verificación fallido.

Los patrones de automatización comunes en CI incluyen:

• Revisión de PR en cada apertura o actualización: Claude lee el diff y publica un comentario de revisión de código estructurado.
• Verificación de seguridad: Claude busca secretos codificados en duro o riesgos de inyección evidentes y hace fallar la verificación si los encuentra.
• Etiquetado automático: Claude lee el diff y aplica etiquetas de GitHub como bug, feature o docs.
• Borrador de notas de versión: En un push a main, Claude resume todos los títulos de PR fusionadas en una entrada de changelog.

La elección del modelo influye en el costo y la velocidad. El modelo claude-haiku-4-5 (el nivel más rápido y económico) maneja bien el etiquetado y los resúmenes cortos. claude-sonnet-4-6 es el valor predeterminado recomendado para revisiones completas de PR. claude-opus-4-8 se reserva para auditorías de seguridad profundas donde la precisión supera el mayor costo por token.

Agentes cloud programados

El skill /schedule le permite crear agentes cloud (también llamados rutinas) que ejecutan Claude Code según un calendario recurrente sin que usted esté presente. El agente se ejecuta en la nube, lee su repositorio o archivos, realiza el trabajo y puede confirmar resultados o enviar notificaciones, todo según un horario cron (un formato de activación basado en tiempo, como "todos los días a las 9 am").

Usted invoca el skill en Claude Code escribiendo /schedule seguido de una descripción en lenguaje natural de lo que desea hacer y cuándo. Claude convierte esa descripción en una rutina programada almacenada en su cuenta. También puede usarlo para ejecuciones únicas en el futuro ("ejecutar una vez a las 3 pm") sin ningún patrón recurrente.

Los casos de uso comunes de los agentes cloud programados incluyen:

• Auditorías diarias de SEO o rendimiento que confirman un informe en su repositorio cada mañana
• Verificaciones semanales de dependencias que abren una pull request cuando se encuentran actualizaciones
• Monitoreo por hora de una API o servicio que le alerta sobre anomalías
• Trabajos nocturnos de pipeline de datos que procesan registros y actualizan un archivo de panel de control

Usted administra sus rutinas con el mismo skill: listarlas para ver lo que está programado, actualizar una rutina para cambiar su horario o instrucciones, o eliminar una cuando ya no sea necesaria. Cada rutina se ejecuta como una sesión completa de agente Claude Code, por lo que tiene acceso a herramientas, puede leer y escribir archivos, y puede llamar a servicios externos dentro de sus permisos configurados.

El patrón /loop

La skill /loop en Claude Code te permite ejecutar un prompt (u otro comando slash) de forma repetida, ya sea en un intervalo de tiempo fijo o al ritmo que el propio modelo decide entre iteraciones. Piensa en ello como una tarea programada (cron job) integrada directamente en tu sesión de Claude, sin necesidad de un planificador externo.

Para iniciar un bucle, escribe /loop seguido de un intervalo opcional y un prompt o comando. Si omites el intervalo, Claude se autorregula: termina una ejecución, decide cuánto tiempo esperar según el contexto y vuelve a disparar. Esto es útil para tareas de monitoreo donde la cadencia adecuada depende de lo que el modelo encuentre.

Casos de uso comunes para /loop:

• Consultar un registro de despliegue cada 2 minutos hasta que aparezca una palabra clave
• Ejecutar un linter o una suite de pruebas en un intervalo recurrente mientras editas
• Verificar un endpoint de API para detectar un cambio de estado sin escribir un script shell
• Ejecutar un comando slash personalizado (como /babysit-prs) de forma programada

Para detener un bucle en ejecución, usa /stop o presiona Ctrl+C. Cada iteración es un turno normal de Claude Code, por lo que el modelo tiene acceso completo a las herramientas (lectura de archivos, comandos shell, recuperación web) en cada ciclo.

Agentes en worktrees aislados

Un git worktree es una segunda (o tercera, o cuarta) copia extraída del mismo repositorio, que vive en su propio directorio en disco y comparte el almacén de objetos git subyacente. Cada worktree tiene sus propios archivos de trabajo y su propia rama, por lo que los cambios en un worktree no pueden afectar a otro hasta que se fusionen de forma explícita.

Cuando se ejecutan varios agentes de Claude Code en paralelo, que cada agente modifique los mismos archivos en la misma rama es una receta para los conflictos. El patrón seguro es: un agente, un worktree, una rama. Los agentes trabajan en aislamiento completo; usted revisa y fusiona cuando terminan.

Claude Code incluye dos comandos slash nativos para este flujo de trabajo:

• /worktree create <name> crea un nuevo worktree y una rama asociada, y luego traslada el agente a ese entorno.
• /worktree list muestra todos los worktrees activos y qué agente (si existe) se está ejecutando en cada uno.
• /worktree remove <name> elimina el directorio del worktree una vez que el agente termina.
• El comando git estándar también funciona: git worktree add ../repo-feat-a feat/a crea un worktree manualmente si lo prefiere.

El beneficio es la mutación paralela segura: tres agentes pueden refactorizar tres módulos distintos al mismo tiempo, cada uno en su propia rama, sin ningún riesgo de que un agente sobreescriba las ediciones en progreso de otro. Usted recopila sus pull requests y fusiona en secuencia.

MCP en producción y herramientas remotas

El Model Context Protocol (MCP) es un estándar abierto que permite a un agente de IA llamar herramientas externas, leer recursos y recibir datos estructurados, todo a través de una interfaz común. En lugar de codificar llamadas a la API directamente en un prompt, se exponen como definiciones de herramientas MCP que cualquier agente compatible puede descubrir e invocar en tiempo de ejecución.

Un despliegue MCP en producción separa las responsabilidades con claridad. El servidor MCP gestiona la conexión con el backend (base de datos, API REST, sistema de archivos). El cliente MCP integrado en Claude Code lee el manifiesto del servidor, conoce las herramientas disponibles y los argumentos que esperan, y decide cuándo llamarlas. Claude nunca ve las credenciales directamente: el servidor gestiona la autenticación y devuelve solo los datos que el agente necesita.

Registrar un servidor MCP remoto en Claude Code requiere una única entrada en la configuración del proyecto o en la configuración global. El servidor puede ejecutarse en local o en un host remoto mediante stdio (entrada/salida estándar, para procesos locales) o SSE (Server-Sent Events, el transporte HTTP en streaming utilizado para servidores remotos). Las buenas prácticas de fiabilidad incluyen:

• Validación de esquema: cada herramienta debe declarar su JSON Schema para que el agente pueda formar llamadas correctas y rechazar respuestas incorrectas de forma temprana.
• Herramientas idempotentes: las operaciones de escritura deben ser seguras de reintentar, porque el agente puede llamar a una herramienta de nuevo tras un timeout.
• Permisos acotados: lista solo las herramientas que el agente necesita para un workflow determinado; una superficie menor implica menos errores y auditorías más sencillas.
• Respuestas de error estructuradas: devuelve objetos de error legibles por máquina, no cadenas de texto simples, para que el agente pueda decidir si reintentar, escalar o detenerse.

La mentalidad de ejecucion paralela

La mayoria de las personas le dan una tarea a un agente, esperan la respuesta y luego dan la siguiente tarea. Eso es pensamiento serial, y es lento. La mentalidad de ejecucion paralela trata su objetivo como un arbol: divídalo en ramas independientes, ejecute todas las ramas a la vez y luego combine los resultados.

El patron de cuatro pasos es descomponer, distribuir, verificar, sintetizar. Descomponer significa dividir el objetivo en subtareas que no comparten ninguna dependencia bloqueante entre si. Distribuir significa lanzarlas todas simultaneamente, ya sea pidiendo a Claude que cree subagentes o enviando multiples llamadas usted mismo. Verificar significa comprobar cada resultado antes de confiar en el (detectar respuestas incorrectas temprano, no despues de la sintesis). Sintetizar significa combinar las salidas verificadas en el entregable final.

En Claude Code se controla esto con el flag --dangerously-skip-permissions para ejecuciones no interactivas, o con el Task tool dentro de un prompt de agente, que permite a una instancia de Claude crear subagentes en paralelo. La Batch API (el endpoint dedicado de Anthropic) es la capa adecuada cuando se necesitan cientos de llamadas independientes al 50 % del costo y sin tocar el limite de velocidad por minuto.

Patrones comunes donde esta mentalidad resulta beneficiosa:

• Distribucion de investigacion: envia la misma pregunta a multiples consultas de busqueda a la vez y luego reconcilia los resultados.
• Auditoria multiarchivo: asigna cada archivo o modulo a un subagente separado y combina los hallazgos.
• Pipeline de traduccion: traduce a cuatro idiomas simultaneamente en lugar de secuencialmente.
• Verificacion adversarial: despues de que un subagente escribe una respuesta, un segundo subagente la critica antes de la sintesis.

Verificación adversarial a escala

Cuando una sola llamada a una IA produce un resultado, no es posible saber si es correcto, alucinado o sesgado por la formulación del prompt. La verificación adversarial resuelve esto ejecutando múltiples agentes independientes sobre la misma tarea y luego reconciliando sus salidas, de modo que los errores se cancelan en lugar de propagarse silenciosamente.

El patrón básico es un panel de jueces: se envía la misma pregunta (o el mismo fragmento de evidencia) a varias instancias de Claude, cada una con un system prompt o una configuración de temperatura ligeramente diferente (la temperatura controla el grado de aleatoriedad en las elecciones de palabras del modelo). Cada juez devuelve un veredicto. Un agregador de voto mayoritario elige la respuesta que aparece con mayor frecuencia. Si el panel está dividido, el sistema puede escalar a un modelo más potente como claude-opus-4-8 para desempatar, en lugar de aceptar ciegamente cualquier respuesta individual.

A escala, esto se convierte en un pipeline. Un paso de fan-out distribuye una tarea a N agentes en paralelo de forma simultánea, usando el flag --dangerously-skip-permissions de Claude Code o un script batch sin interfaz para evitar los prompts interactivos. Un paso de reducción recopila todas las respuestas y aplica la regla de votación. La reducción en sí puede ser una llamada a Claude con un prompt estricto que solo cuenta veredictos explícitos, ignorando el lenguaje con matices.

Decisiones de diseño clave para un panel fiable:

• Tamaño impar del panel: use 3 o 5 jueces para evitar empates en preguntas binarias.
• Diversidad de prompts: varíe la formulación entre los jueces para que no sean todos engañados por el mismo encuadre.
• Salida estructurada: fuerce a cada juez a devolver una etiqueta legible por la máquina como PASS o FAIL antes de cualquier explicación, para que la reducción procese correctamente.
• Ponderación por confianza: opcionalmente pida a cada juez una puntuación de confianza de 0 a 10 y pondere el voto en consecuencia, en lugar de tratar todos los votos por igual.

Cuando no usar agentes

Un agente es un bucle: el modelo planifica, llama herramientas, lee los resultados y repite hasta que la tarea está completa. Ese bucle tiene un costo en tiempo y tokens, e introduce puntos de falla en cada paso. Muchas tareas no lo necesitan.

Una tarea de un solo llamado es aquella en la que puedes proporcionar todo el contexto necesario de antemano y el modelo puede devolver una respuesta completa y correcta en una sola llamada. Envolverla en un agente agrega sobrecarga sin beneficio. Usa la herramienta más simple que resuelva el problema.

Opta por un prompt simple (sin agente, sin herramientas) cuando la tarea encaje en alguno de estos casos:

• La respuesta no requiere datos externos más allá de lo que pegas en el prompt.
• No se necesita acceso al sistema de archivos, al navegador ni a ninguna API.
• La salida es suficientemente corta para revisarse en una sola lectura.
• Reintentar ante un fallo es más barato que construir lógica de reintento en un bucle de agente.
• La latencia importa y un bucle de agente de ida y vuelta se sentirá lento.

Una regla útil: si pudieras responder la pregunta tú mismo con un resultado de búsqueda o un documento pegado, un chat simple en Claude.ai o una llamada al CLI claude con entrada redirigida es suficiente. Reserva los agentes de Claude Code y los pipelines de múltiples pasos para tareas que genuinamente requieren planificación a través de muchos pasos desconocidos.