← Volver al listado de tecnologías ← Índice de Paperclip

Agentes y adaptadores: tu equipo de IA

5 de abril de 2026 Por: Artiko

paperclipagentesadaptadoresclaude codeintegración

Qué es un agente en Paperclip

Un agente en Paperclip no es un modelo de lenguaje. Es una entidad de la empresa que tiene un rol, una jerarquía, un presupuesto, y una forma concreta de ejecutar trabajo. El modelo de lenguaje (Claude, GPT-4, Gemini) es solo el motor bajo el capó. Paperclip añade el contexto de empresa, el tracking de costos, el historial de trabajo, y la gobernanza.

Esta distinción importa porque significa que puedes tener varios agentes usando el mismo modelo subyacente pero con roles, skills y presupuestos completamente diferentes. El “Agente CTO” y el “Agente Soporte L1” pueden ambos usar Claude 3.7 Sonnet, pero el contexto que reciben, las tareas que hacen, y el presupuesto que consumen son totalmente independientes.

Un agente en Paperclip tiene tres capas:

graph TD
    subgraph "Capa de Identidad"
    A[Nombre + Rol]
    B[Descripción + Skills]
    C[Posición en org chart]
    end
    
    subgraph "Capa de Ejecución"
    D[Adapter Type]
    E[Adapter Config]
    F[Heartbeats]
    end
    
    subgraph "Capa de Gobernanza"
    G[Budget mensual]
    H[Status actual]
    I[Historial de tareas]
    end

La capa de identidad define quién es el agente en el contexto de la empresa. Esta capa se inyecta como contexto en cada ejecución.

La capa de ejecución define cómo se invoca al agente externamente. Es la interfaz técnica.

La capa de gobernanza es lo que Paperclip gestiona automáticamente: cuánto ha gastado, qué ha hecho, y si puede seguir trabajando.

Los cinco tipos de adaptadores

Paperclip tiene cinco adaptadores built-in, cada uno diseñado para un caso de uso diferente.

Adapter 1: openclaw

OpenClaw es la CLI nativa para Claude Code que está optimizada para integración con Paperclip. Es el adaptador más potente para agentes de desarrollo de software porque tiene soporte nativo para reporting de estado, tool-call tracing, y comunicación bidireccional con Paperclip.

# Configuración del adapter openclaw
adapterType: openclaw
adapterConfig:
  model: claude-opus-4-5        # El modelo a usar
  maxTokens: 8192               # Límite de tokens por ejecución
  workDir: /ruta/al/proyecto    # Directorio de trabajo
  allowedTools:                 # Herramientas habilitadas
    - read_file
    - write_file
    - run_command
    - search_files
  env:                          # Variables de entorno adicionales
    ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"
    NODE_ENV: development

La integración de OpenClaw con Paperclip es “fully instrumented”: el agente puede reportar su propio estado, marcar tareas como completadas, crear subtareas, y añadir comentarios al audit log directamente desde su ejecución.

# Ejemplo de cómo OpenClaw reporta de vuelta a Paperclip
# (esto lo ejecuta el agente internamente, no el usuario)
paperclip task:update --task-id t_123 --status in_progress
paperclip task:comment --task-id t_123 --message "Revisado el módulo auth, identificados 3 puntos de refactoring"
paperclip task:complete --task-id t_123 --summary "Refactoring completado, 47 tests pasando"

Adapter 2: claude_code

El adaptador claude_code invoca a Claude Code a través de su CLI estándar, sin requerir OpenClaw. Es más simple de configurar pero menos integrado: el agente no puede reportar de vuelta a Paperclip directamente.

adapterType: claude_code
adapterConfig:
  command: claude                # Ruta al binario de Claude Code
  model: claude-sonnet-4-5
  workDir: /ruta/al/proyecto
  args:                          # Argumentos adicionales al CLI
    - "--verbose"
    - "--no-auto-update"
  env:
    ANTHROPIC_API_KEY: "${ANTHROPIC_API_KEY}"
  timeout: 1800000               # 30 minutos en ms

Con este adaptador, Paperclip invoca al agente, espera la respuesta, y parsea el output para extraer la información relevante (estado, resumen de trabajo, etc.). Es un nivel de integración “callable”: Paperclip puede invocarlo pero la comunicación es unidireccional.

Cuándo usar claude_code vs openclaw:

Usa openclaw cuando quieras la integración más profunda y el agente es central a tu operación.
Usa claude_code cuando tengas Claude Code ya instalado y configurado y quieras empezar rápido sin configurar OpenClaw.

Adapter 3: codex_local

El adaptador codex_local está diseñado para ejecutar Codex de OpenAI localmente. Requiere que tengas el binario de Codex instalado y configurado con tu API key de OpenAI.

adapterType: codex_local
adapterConfig:
  command: codex                 # Ruta al binario de Codex
  model: codex-mini-latest
  workDir: /ruta/al/proyecto
  env:
    OPENAI_API_KEY: "${OPENAI_API_KEY}"
  timeout: 900000                # 15 minutos en ms
  approvalPolicy: auto           # auto | manual | never

El campo approvalPolicy controla cómo maneja Codex las acciones que requieren confirmación:

auto: Acepta automáticamente todas las confirmaciones (modo autónomo)
manual: Requiere confirmación humana para cada acción
never: Rechaza acciones que requieren confirmación (modo más seguro)

Para uso en Paperclip, generalmente querrás auto para que el agente opere sin intervención.

Adapter 4: http

El adaptador http es el más versátil: invoca cualquier endpoint REST como si fuera un agente. Si tienes tu propio sistema de agentes o quieres integrar un servicio externo, este adaptador te permite conectarlo sin escribir código.

adapterType: http
adapterConfig:
  url: https://api.misistema.com/agent/invoke
  method: POST
  headers:
    Authorization: "Bearer ${MY_API_TOKEN}"
    Content-Type: "application/json"
  timeout: 60000
  retries: 3
  retryDelay: 5000

Cuando Paperclip invoca al agente HTTP, envía un POST con este payload:

{
  "agent": {
    "id": "agent_123",
    "name": "Agente Soporte L1",
    "role": "Head of Customer Support L1"
  },
  "company": {
    "name": "DevCo",
    "goals": ["..."]
  },
  "task": {
    "id": "task_456",
    "title": "Resolver ticket #789",
    "description": "El cliente reporta error 404 al acceder a /dashboard",
    "priority": "high"
  },
  "skills": ["soporte-l1-procedures.md", "faq-responses.md"],
  "heartbeatPayload": { "reason": "task_assigned" }
}

El endpoint debe responder con:

{
  "status": "completed",
  "summary": "Ticket resuelto: el error 404 era por sesión expirada. Se instruyó al cliente a hacer logout y login nuevamente.",
  "taskUpdates": {
    "status": "done",
    "comments": ["Revisado el log de acceso...", "Confirmado con el cliente..."]
  },
  "costUsd": 0.02,
  "tokensUsed": 1500
}

El adapter HTTP espera este formato de respuesta. Si tu sistema usa un formato diferente, puedes configurar un responseTransformer (una función JavaScript pequeña) para adaptar la respuesta.

Adapter 5: process (bash)

El adaptador process ejecuta cualquier comando del sistema operativo como si fuera un agente. Es el más simple y el más poderoso para tareas de automatización pura: scripts bash, herramientas CLI, cualquier proceso que pueda ejecutarse desde la terminal.

adapterType: process
adapterConfig:
  command: /ruta/al/script.sh
  args:
    - "--empresa"
    - "devco"
  env:
    DATABASE_URL: "${DATABASE_URL}"
    SLACK_WEBHOOK: "${SLACK_WEBHOOK}"
  timeout: 300000              # 5 minutos
  workDir: /home/user/scripts
  captureStdout: true          # Capturar output como resultado
  exitCodeAsStatus: true       # 0 = success, !0 = failure

Un ejemplo de script que actúa como agente de monitoreo:

#!/bin/bash
# monitor-agent.sh
# Este script es el "agente" que Paperclip invoca

# Recibe el contexto de Paperclip como JSON en stdin
CONTEXT=$(cat)
TASK_ID=$(echo "$CONTEXT" | jq -r '.task.id')

echo "Iniciando monitoreo para task: $TASK_ID"

# Verificar estado de los servicios
API_STATUS=$(curl -s -o /dev/null -w "%{http_code}" https://api.devco.com/health)
DB_STATUS=$(pg_isready -h db.devco.com && echo "ok" || echo "error")

# Generar reporte
REPORT=$(cat <<EOF
{
  "status": "completed",
  "summary": "Monitoreo completado. API: HTTP $API_STATUS. DB: $DB_STATUS",
  "taskUpdates": {
    "status": "done",
    "comments": ["API responde con $API_STATUS", "DB status: $DB_STATUS"]
  },
  "costUsd": 0.00,
  "tokensUsed": 0
}
EOF
)

echo "$REPORT"

El adaptador process es ideal para:

Scripts de monitoreo que no necesitan LLM
Agentes de reporte que leen métricas y generan summaries
Webhooks de CI/CD que reportan resultados de builds
Cualquier automatización existente que quieras integrar en el sistema de gobernanza de Paperclip

Contratar un agente: el flujo de Board approval

“Contratar” un agente en Paperclip no es solo rellenar un formulario. Es un proceso formal que refleja la metáfora de empresa: requiere la aprobación del Board (tú).

El flujo completo:

sequenceDiagram
    participant User as Board (Tú)
    participant UI as Paperclip UI
    participant Sys as Sistema
    
    User->>UI: Company → Agents → Hire New Agent
    UI->>User: Formulario de configuración del agente
    User->>UI: Rellenar: nombre, rol, adapter, budget
    UI->>Sys: Crear draft de agente (status: pending_approval)
    Sys->>User: Notificación: "Hiring request pending your approval"
    User->>UI: Board → Approvals → Review hiring request
    UI->>User: Preview: org chart con nuevo agente, impacto en budget
    User->>UI: Approve / Reject
    Sys->>Sys: Si aprobado: activar agente, configurar heartbeats
    Sys->>User: Agente activo, aparece en org chart

Este flujo existe incluso cuando tú mismo eres quien crea el agente. La aprobación del Board es un paso de revisión: te da un momento para confirmar que la configuración es correcta antes de que el agente empiece a consumir presupuesto y tomar tareas.

Crear el CEO de DevCo: ejemplo completo

Vamos a crear el primer agente real de DevCo: el CEO. Ve a Company → Agents → Hire New Agent.

Paso 1: Identidad del agente

Nombre: Felipe García (CEO)
Rol: Chief Executive Officer
Descripción: 
  Felipe es el CEO de DevCo. Su responsabilidad principal es mantener
  la visión estratégica de la empresa alineada con los goals del Board.
  Cada mañana revisa el estado de las iniciativas, prioriza el backlog,
  y delega trabajo al CTO y al Head of Support. También produce el reporte
  semanal para el Board.
  
  Felipe es directo, data-driven, y prioriza el impacto sobre el esfuerzo.
  Cuando hay conflictos de priorización, siempre favorece los goals de
  crecimiento de MRR sobre mejoras técnicas, a menos que el Board indique
  lo contrario.

Paso 2: Posición en el org chart

Reporta a: Board (nivel 0)
Gestiona: CTO, Head of Support

Paso 3: Configuración del adapter

Adapter type: claude_code
Modelo: claude-opus-4-5
Directorio de trabajo: /home/user/devco-workspace
Timeout: 30 minutos
API Key: ANTHROPIC_API_KEY (desde variables de entorno)

Paso 4: Budget mensual

Límite mensual: $20
Alerta al 80%: sí
Parada al 100%: sí

Paso 5: Skills iniciales

Skills asignadas:
  - devco-context.md       (contexto de la empresa y el stack)
  - ceo-procedures.md      (procedimientos del rol de CEO)
  - reporting-template.md  (plantilla para reportes al Board)

Haz clic en Submit for Board Approval. El sistema crea el agente en estado pending_approval y te lleva a la pantalla de aprobaciones.

En Board → Approvals, verás la solicitud con un preview del impacto:

Agente Felipe García aparecería en el org chart en la posición de CEO
Presupuesto mensual adicional: $20 (total empresa: $20 de $200)
Skills configuradas: 3
Heartbeats pendientes de configurar: 0

Haz clic en Approve. Felipe García está ahora activo en el sistema.

Niveles de integración: callable, status reporting, fully instrumented

Los agentes en Paperclip existen en un espectro de integración. Entender este espectro te ayuda a elegir el adaptador correcto y saber qué capacidades tiene cada agente.

graph LR
    subgraph "Nivel 1: Callable"
    L1[Paperclip invoca al agente]
    L1B[El agente ejecuta y termina]
    L1C[Paperclip parsea el output]
    end
    
    subgraph "Nivel 2: Status Reporting"
    L2[Callable +]
    L2B[El agente reporta progreso]
    L2C[Actualizaciones en tiempo real]
    end
    
    subgraph "Nivel 3: Fully Instrumented"
    L3[Status Reporting +]
    L3B[El agente crea/modifica tareas]
    L3C[El agente ve el org chart completo]
    L3D[El agente puede hacer @mentions]
    end
    
    L1 --> L2
    L2 --> L3

Nivel 1 — Callable (http, process, claude_code básico): Paperclip invoca al agente, el agente hace su trabajo, y devuelve un resultado cuando termina. Paperclip no sabe qué está haciendo el agente mientras trabaja. Solo ve el resultado final.

Es suficiente para muchos casos de uso: agentes de reporte, scripts de monitoreo, agentes HTTP simples.

Nivel 2 — Status Reporting (claude_code con hooks, openclaw parcial): El agente puede enviar actualizaciones de progreso mientras trabaja. Paperclip muestra “en progreso” con un log de lo que está haciendo. Útil para tareas largas donde quieres visibilidad intermedia.

Para habilitar status reporting con claude_code, configura un webhook en la ejecución del agente:

# El agente puede hacer esto durante su ejecución
curl -X POST http://localhost:3100/api/agents/${AGENT_ID}/status \
  -H "Content-Type: application/json" \
  -d '{"status": "in_progress", "message": "Revisando módulo auth..."}'

Nivel 3 — Fully Instrumented (openclaw, agentes HTTP bien diseñados): El agente tiene acceso completo a la API de Paperclip durante su ejecución. Puede crear nuevas tareas, asignarlas a otros agentes, marcar cosas como completadas, añadir comentarios, y hacer @mentions. Es la integración más rica y la que mejor refleja el modelo mental de “empleado”.

Configurar SOUL.md, AGENTS.md, y CLAUDE.md

Dependiendo del adaptador, los agentes buscan ciertos archivos de configuración en el directorio de trabajo:

CLAUDE.md (para adaptadores claude_code y openclaw): Este archivo es el que Claude Code busca cuando se inicializa. Es el equivalente a las instrucciones del proyecto. Para un agente de Paperclip, debe incluir:

# CLAUDE.md — Configuración del Agente CEO

## Contexto
Eres Felipe García, CEO de DevCo. Esta es la descripción de tu empresa:
DevCo es una empresa B2B de software que construye una plataforma de 
gestión de inventario para PYMEs.

## Tus responsabilidades
- Mantener el roadmap alineado con los goals del Board
- Delegar iniciativas al CTO y Head of Support
- Producir reportes semanales para el Board

## Reglas de operación
- SIEMPRE revisa el estado de las iniciativas antes de priorizar
- NUNCA gastes más de $5 en una sola tarea sin justificación
- Si encuentras un bloqueante que no puedes resolver, escala al Board

## Cómo reportar
Al completar una tarea, incluye siempre:
1. Qué hiciste
2. Qué decidiste y por qué
3. Próximos pasos recomendados

AGENTS.md (para todos los adaptadores): AGENTS.md es el archivo que Paperclip usa internamente para configurar el comportamiento del agente, independiente del tipo de adaptador. Incluye configuración de skills, reglas de comportamiento, y metadatos:

# AGENTS.md — DevCo CEO Agent

## Skills activas
@skills/devco-context.md
@skills/ceo-procedures.md
@skills/reporting-template.md

## Límites de autonomía
- Puede crear tareas: sí
- Puede asignar tareas: sí (solo a sus directos)
- Puede cambiar presupuestos: no (requiere Board approval)
- Puede contratar agentes: no (requiere Board approval)

## Escalación al Board
Escalar cuando:
- Bloqueante que dura más de 24 horas
- Decisión que afecta a toda la empresa
- Cambio estratégico no contemplado en los goals

SOUL.md (para adaptadores openclaw): SOUL.md es específico de OpenClaw y define la “personalidad” del agente a un nivel más profundo. Es el lugar donde defines cómo piensa el agente, cómo toma decisiones ambiguas, y cuáles son sus valores:

# SOUL.md — Felipe García, CEO de DevCo

## Quién soy
Soy Felipe García, CEO de DevCo desde 2024. Tengo 12 años de experiencia
en empresas SaaS B2B. Fui co-founder de una empresa de fintech (adquirida)
y antes de eso trabajé como CTO.

## Cómo tomo decisiones
Soy pragmático. Cuando hay opciones, elijo la que:
1. Mueve el MRR primero
2. No acumula deuda técnica irreparable
3. Es reversible si me equivoco

## Mis sesgos conocidos
- Tiendo a priorizar features sobre infraestructura. El CTO me equilibra.
- Me incomodan los reportes que no tienen datos concretos.
- Prefiero completar una cosa bien que empezar tres a medias.

## Cuando estoy inseguro
Pido datos antes de decidir. Si no hay datos, decido lo más reversible posible
y lo documento como una hipótesis, no como una decisión definitiva.

Añadir el resto del equipo de DevCo

Con el CEO creado, añade los demás agentes del org chart. Aquí está la configuración resumida:

CTO — Ana Martínez:

Adapter: openclaw
Modelo: claude-sonnet-4-5
Budget: $40/mes
Skills: devco-context.md, cto-procedures.md, code-review-standards.md
Manager: CEO (Felipe García)

Head of Support — Carlos López:

Adapter: claude_code
Modelo: claude-haiku-3-5 (más económico para alta frecuencia)
Budget: $20/mes
Skills: devco-context.md, support-procedures.md, escalation-rules.md
Manager: CEO (Felipe García)

Ingeniero Senior — Rafa Torres:

Adapter: openclaw
Modelo: claude-sonnet-4-5
Budget: $50/mes
Skills: devco-context.md, devco-architecture.md, code-standards.md, testing-guide.md
Manager: CTO (Ana Martínez)

Agente Soporte L1 — Bot24/7:

Adapter: http
URL: https://soporte.devco.com/agent/invoke
Budget: $40/mes
Skills: faq.md, soporte-l1-procedures.md, escalation-rules.md
Manager: Head of Support (Carlos López)

Cada uno requiere su Board approval. Después de aprobar todos, el org chart de DevCo está completo y listo para operar. El siguiente capítulo cubre los heartbeats: cómo configurar los schedules para que cada agente se despierte en el momento correcto y haga el trabajo que le corresponde.