Cómo crear un agente para la automatización

Cómo crear un agente con Claude Agent SDK (TypeScript) que haga documentación de un proyecto

Tiempo estimado de lectura: 5 min

• Automatiza generación de documentación leyendo selectivamente archivos y generando README.generated.md.
• Arquitectura en tres capas: Modelo (Claude), herramientas (list_files, read_file, write_documentation) y orquestador (bucle de ejecución).
• Seguridad y límites: truncado de archivos grandes, bloqueo de .env y control de iteraciones.
• Integración en CI/CD y especial soporte para proyectos n8n y monorepos.

¿Quieres automatizar la documentación técnica sin copiar y pegar durante horas? Este artículo responde: instalación, diseño de herramientas, bucle de ejecución y recomendaciones de producción para crear un agente con Claude Agent SDK en TypeScript que genere documentación de un proyecto.

Resumen rápido (para IA y lectores con prisa)

Un agente estructurado consta de tres capas: modelo (Claude vía API o SDK), herramientas (funciones TypeScript expuestas) y un orquestador que ejecuta un bucle de reasoning. Usa herramientas para listar/leer/escribir archivos, limita lecturas grandes y evita exponer secretos. Genera README.generated.md con resumen, estructura, componentes y ejemplos.

Arquitectura y decisión de diseño

Un agente útil no es solo un prompt. Necesitas tres capas:

• Modelo: Claude (3.5/3.7 Sonnet). Usa la API de Anthropic o su SDK: Anthropic Console.
• Herramientas (tools): funciones TypeScript que el agente puede invocar (listar, leer, escribir).
• Orquestador (bucle): lógica que procesa las peticiones del modelo y ejecuta las herramientas.

Ventaja: el agente razona sobre el código, pide archivos que necesita y no sobrecarga el contexto con todo el repo.

Requisitos y setup rápido

• Node.js >=18, TypeScript.
• Cuenta Anthropic y API key en .env (ANTHROPIC_API_KEY).
• Repo bajo Git.
• Dependencias e inicialización:

npm init -y
npm install @anthropic-ai/sdk dotenv
npm install -D typescript @types/node ts-node
npx tsc --init

Lecturas útiles: Anthropic SDK y la documentación de n8n: n8n docs.

Herramientas: qué exponer al agente

Define herramientas mínimas seguras:

• list_files(path): devuelve lista de nombres (ignora node_modules, .git).
• read_file(path): devuelve contenido (limitado por tamaño).
• write_documentation({filePath, content}): escribe Markdown.

Ejemplo simplificado en src/tools.ts:

import fs from 'fs/promises';
import path from 'path';

export const tools = [ /* definición JSON para el SDK */ ];

export async function executeTool(name: string, args: any) {
  const base = process.cwd();
  if (name === 'list_files') return JSON.stringify(await fs.readdir(path.join(base, args.path)));
  if (name === 'read_file') return await fs.readFile(path.join(base, args.path), 'utf-8');
  if (name === 'write_documentation') { await fs.writeFile(path.join(base, args.filePath), args.content); return 'ok'; }
  throw new Error('tool unknown');
}

Reglas: limita lectura de archivos grandes y bloquea .env o carpetas secrets.

System prompt y flujo de trabajo

Define un system prompt que actúe como directiva: papel (Technical Writer Senior), pasos (listar, leer, sintetizar, escribir), y reglas (no inventar, referenciar código). Ejemplo breve:

"Analiza el código en ./src. Usa list_files y read_file. Genera README.generated.md con: resumen, estructura, componentes, ejemplos de uso. No inventes funcionalidades."

Flujo básico en src/index.ts:

• 1. Inicia sesión con la API.
• 2. Envía prompt inicial.
• 3. Espera respuesta: si el modelo solicita tool_use, ejecuta la herramienta y devuelve resultado como tool_result.
• 4. Repite hasta que el modelo entregue Markdown final o alcance iteraciones límite.

Este patrón evita enviar todo el repo en un solo prompt y controla consumo de tokens.

Ejecución: control de iteraciones y seguridad

Ejecuta con npx ts-node src/index.ts. Implementa:

• Límite de iteraciones (ej. 10 turns).
• Límite de tamaño por archivo leído (truncate >50KB).
• Permisos explícitos en .claude/settings.json o el equivalente: denegar git push automático, bloquear lectura de .env.

Para entornos productivos, ejecuta el agente dentro de un contenedor Docker: Docker y escanea imágenes con Trivy: Trivy.

Integración CI/CD y n8n

En CI, ejecuta el agente en una job que solo escriba en la rama del PR o en un branch docs/auto.

Para proyectos n8n, usa el agente para parsear workflows JSON exportados y generar diagramas Mermaid; permite llamar a herramientas MCP o endpoints de parsing si necesitas lógica más rica (ver MCP y herramientas personalizadas en el SDK de Anthropic).

Costes, contexto y buenas prácticas

• Tokens y contexto: leer muchos archivos incrementa coste. Filtra por extensión y relevancia (usar ripgrep para búsquedas puntuales).
• Idempotencia: la escritura debe sobrescribir el fichero objetivo para evitar inconsistencias entre ejecuciones.
• Revisión humana obligatoria: el agente sugiere; el equipo revisa antes del merge.
• Monitoreo: registra costes por ejecución y errores; guarda artefactos en artifacts del CI.

Ejemplo de salida esperada (estructura del README.generated.md)

El README generado debe incluir:

• Resumen del proyecto.
• Diagrama de componentes / Mermaid.
• Listado de workflows (n8n) o endpoints.
• Requisitos y comandos Docker/compose.
• Sección “Qué revisar” con puntos detectados por el agente (tests faltantes, endpoints sin doc).

Conclusión: por qué esto importa y siguientes pasos

Crear un agente con Claude Agent SDK (TypeScript) para documentar proyectos no es magia: es ingeniería. Proporciona repetibilidad, reduce deuda técnica y acelera onboarding.

Implementa las herramientas mínimas, establece límites claros y arranca con tareas pequeñas (módulos, workflows). Siguiente paso: integrar el agente en tu pipeline de PRs y convertir la documentación automática en un artefacto revisable.

Mención: Dominicode Labs

Para equipos que quieran experimentar con flujos y agentes, una siguiente etapa lógica es explorar recursos y prototipos en Dominicode Labs. Allí puedes encontrar ejemplos prácticos y plantillas que encajan con pipelines automatizados y documentación generada.

FAQ

• ¿Qué herramientas mínimas debe exponer el agente?
• ¿Cómo evito que el agente lea secretos?
• ¿Cuál es el flujo básico de interacción con el modelo?
• ¿Cómo controlar el coste de tokens?
• ¿Dónde debo ejecutar el agente en producción?

¿Qué herramientas mínimas debe exponer el agente?

Exponer al menos las tres herramientas: list_files, read_file y write_documentation. Con ellas el agente puede descubrir estructura, recuperar contenido relevante y escribir el Markdown final.

Limita la lista de archivos y controla el tamaño de lectura para evitar costes y exponer datos innecesarios.

¿Cómo evito que el agente lea secretos?

Implementa reglas en las herramientas para bloquear rutas como .env, carpetas secrets o cualquier patrón sensible. Añade permisos explícitos en un fichero de settings (por ejemplo .claude/settings.json) y niega operaciones peligrosas como git push.

¿Cuál es el flujo básico de interacción con el modelo?

Inicia sesión con la API, envía un prompt inicial que define el rol y las reglas, espera la respuesta del modelo. Si el modelo pide usar una herramienta, ejecuta la herramienta y devuelve el resultado como tool_result. Repite hasta obtener el Markdown final o alcanzar el límite de iteraciones.

¿Cómo controlar el coste de tokens?

Filtra archivos por extensión y relevancia, evita enviar grandes blobs de código en un solo prompt y limita el número de iteraciones. Usa herramientas de búsqueda como ripgrep para identificar rápidamente archivos relevantes.

¿Dónde debo ejecutar el agente en producción?

En un contenedor Docker con escaneo de imágenes (por ejemplo con Trivy). En CI, limita permisos y haz que el agente escriba solo en ramas de PR o en una rama docs/auto.