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

Casos avanzados: multi-empresa, plugins y el futuro

Por: Artiko
paperclipavanzadomulti-empresapluginsskillsecosistema

Más allá del caso básico

Los nueve capítulos anteriores cubren todo lo necesario para tener una empresa de agentes funcionando. Este capítulo va más allá: explora los casos de uso avanzados que convierten Paperclip de una herramienta útil en la infraestructura central de tu operación de IA.

Cubriremos la gestión de múltiples empresas en un solo deployment, cómo exportar e importar organizaciones completas, el Skills Manager para gestión dinámica de conocimiento, el plugin system para extensibilidad, y una mirada al ecosistema y roadmap.

Gestión multi-empresa: un deployment, muchas organizaciones

Un solo deployment de Paperclip puede alojar múltiples empresas completamente aisladas entre sí. Esto tiene varios casos de uso importantes:

Agencia de IA: Gestionas agentes IA para múltiples clientes. Cada cliente es una “empresa” en tu deployment. Los agentes de un cliente nunca ven el trabajo ni la configuración de otro cliente.

Conglomerado: Tienes múltiples líneas de negocio o subsidiarias. Cada una tiene su propio equipo de agentes, su propio presupuesto, y sus propios goals. El Board (tú) tiene visión global.

Ambientes separados: Usas “empresas” para separar producción de staging. La empresa “DevCo-Prod” tiene agentes con presupuestos reales y permisos de producción. La empresa “DevCo-Staging” tiene la misma estructura pero con configuraciones más permisivas.

Testing de configuraciones: Antes de cambiar la configuración de un agente en producción, lo pruebas en una empresa de staging.

Aislamiento de datos en multi-empresa

El aislamiento entre empresas es completo a nivel de base de datos. Cada entidad en la base de datos tiene un campo companyId y todas las queries incluyen ese campo como condición. No hay forma de que una query de la empresa A devuelva datos de la empresa B.

graph TD
    subgraph "Deployment único PostgreSQL"
    subgraph "Company: DevCo"
        A1[Agentes DevCo]
        T1[Tareas DevCo]
        B1[Presupuesto DevCo]
    end
    
    subgraph "Company: ClienteXYZ"
        A2[Agentes ClienteXYZ]
        T2[Tareas ClienteXYZ]
        B2[Presupuesto ClienteXYZ]
    end
    
    subgraph "Company: Staging"
        A3[Agentes Staging]
        T3[Tareas Staging]
        B3[Presupuesto Staging]
    end
    end
    
    Board[Board Admin] --> DevCo
    Board --> ClienteXYZ
    Board --> Staging

El Board admin puede ver y gestionar todas las empresas. Los boards individuales (si configuras acceso por empresa) solo ven su empresa.

Crear múltiples empresas

# Via CLI
npx paperclipai company:create \
  --name "ClienteXYZ" \
  --description "Cliente de la agencia, empresa retail" \
  --industry "Retail"

# Listar todas las empresas
npx paperclipai company:list

# Salida:
# ID                  NAME           STATUS    AGENTS  BUDGET
# company_devco       DevCo          active    6       $200/mo
# company_clientexyz  ClienteXYZ     active    4       $150/mo
# company_staging     DevCo Staging  active    6       $50/mo

# Cambiar entre empresas en la UI
# La UI tiene un selector de empresa en el header

Presupuesto por empresa

Cada empresa tiene su propio pool de presupuesto, independiente de las demás. Si tu agencia cobra a cada cliente por los costos de IA, esto te permite:

  1. Configurar el presupuesto de la empresa cliente según lo que has acordado con ellos
  2. Exportar el informe de costos mensual por empresa
  3. Presentar al cliente un desglose exacto de lo que se gastó y en qué
# Exportar informe de costos de una empresa específica
npx paperclipai cost:report \
  --company company_clientexyz \
  --month 2026-04 \
  --format csv \
  --output clientexyz-costs-abril-2026.csv

Exportar e importar organizaciones

El sistema de export/import es lo que hace a Paperclip verdaderamente portable. Una organización bien diseñada puede convertirse en un template reutilizable.

El script companies.sh

Paperclip incluye un script de utilidades para operaciones masivas de empresas:

# companies.sh - utilidades de gestión de empresas

# Exportar TODAS las empresas como templates
./companies.sh export-all --format template --output ./backups/templates/

# Importar una empresa desde template
./companies.sh import --file ./templates/agencia-marketing.json \
  --company-name "NuevoCliente" \
  --dry-run     # Ver qué haría sin ejecutar

# Clonar una empresa existente (template export + import)
./companies.sh clone \
  --source company_devco \
  --target "DevCo Copy" \
  --type template   # Solo estructura, sin datos

# Sincronizar configuración entre empresas (ej: staging ← producción)
./companies.sh sync \
  --source company_devco_prod \
  --target company_devco_staging \
  --sync-skills true \
  --sync-agents true \
  --sync-tasks false  # No copiar tareas reales a staging

Template export vs Snapshot export

La diferencia entre estos dos tipos de export es fundamental y tiene muchos casos de uso:

Template export: Exporta la estructura sin datos de ejecución.

{
  "exportType": "template",
  "version": "1.0",
  "metadata": {
    "exportedAt": "2026-04-05T10:00:00Z",
    "exportedBy": "Board Admin"
  },
  "company": {
    "name": "Agencia Marketing Template",
    "description": "Plantilla para agencias de marketing digital",
    "industry": "Marketing / Agencia"
  },
  "goals": [
    "Producir contenido de alta calidad consistentemente",
    "Responder a clientes en menos de 24 horas"
  ],
  "orgStructure": {
    "roles": [
      { "title": "CEO", "level": 1, "description": "..." },
      { "title": "Content Director", "level": 2, "description": "..." },
      { "title": "SEO Specialist", "level": 3, "description": "..." }
    ]
  },
  "skills": [
    {
      "name": "content-strategy.md",
      "content": "# Estrategia de contenido\n..."
    }
  ],
  "heartbeatTemplates": [
    {
      "agentRole": "Content Director",
      "schedule": "0 9 * * 1-5",
      "payloadTemplate": "Revisión de la agenda de contenidos..."
    }
  ]
}

Snapshot export: Incluye el estado actual completo.

{
  "exportType": "snapshot",
  "version": "1.0",
  "company": { ... },
  "agents": [
    {
      "id": "agent_123",
      "name": "Felipe García (CEO)",
      "adapterConfig": { ... },
      "budget": { "spentThisMonth": 8.43, "monthlyLimit": 20 },
      "heartbeats": [ ... ]
    }
  ],
  "tasks": [
    {
      "id": "task_456",
      "title": "...",
      "status": "done",
      "auditLog": [ ... ]
    }
  ],
  "budgetTransactions": [ ... ]
}

Usa templates para crear nuevas empresas desde una base conocida. Usa snapshots para backups, migraciones, y análisis histórico.

Skills Manager: gestión dinámica de conocimiento

El Skills Manager es la interfaz central para gestionar todo el conocimiento inyectable en los agentes. Es donde creates, editas, versiones, y asignas skills.

Estructura de una skill

Una skill es un archivo Markdown con frontmatter opcional:

---
skillId: devco-architecture
name: "Arquitectura de DevCo"
version: "2.1.0"
applicableTo:
  - roles: ["CTO", "Ingeniero Senior", "Ingeniero Jr"]
  - companies: ["devco"]
lastUpdated: 2026-04-05
author: "Board Admin"
---

# Arquitectura de DevCo

## Stack tecnológico
- Backend: Node.js 20 + TypeScript + Express
- Base de datos: PostgreSQL 16
- ORM: Drizzle ORM
- Frontend: React 19 + Vite + Tailwind CSS
- Deploy: Docker en Railway

## Estructura del repositorio
El repositorio sigue arquitectura hexagonal:
- `src/domain/` — Entidades y lógica de negocio pura
- `src/application/` — Casos de uso
- `src/infrastructure/` — Adapters (DB, HTTP, etc.)

## Convenciones de código
- Nombres en inglés para código, español para documentación
- Tests con Vitest, cobertura mínima 80%
- ESLint + Prettier sin excepciones
- Commits: feat/fix/refactor/chore + descripción en español

## APIs internas
La API interna está documentada en: http://api.devco.internal/docs
Autenticación: Bearer token desde env variable `DEVCO_API_TOKEN`

## Decisiones de arquitectura recientes
### 2026-03-15: Migración a Drizzle ORM
Migramos de Prisma a Drizzle por mejor performance en queries complejas.
Los schemas están en `src/infrastructure/database/schema.ts`

### 2026-02-01: Adopción de event sourcing para billing
El módulo de billing usa event sourcing. Ver `src/domain/billing/events/`

Asignación dinámica de skills

La potencia del Skills Manager está en la asignación dinámica. Puedes definir reglas que determinan qué skills recibe un agente según el contexto:

# Reglas de asignación de skills
skillAssignmentRules:
  - skill: devco-architecture
    assignTo:
      roles: ["CTO", "Ingeniero Senior", "Ingeniero Jr"]
      companies: ["devco"]
    always: true    # Siempre incluir, no importa la tarea

  - skill: soporte-l1-procedures
    assignTo:
      agents: ["agent_support_bot"]
    always: true

  - skill: deployment-runbook
    assignTo:
      roles: ["CTO", "Ingeniero Senior"]
    when:
      taskTags: ["deployment", "release", "hotfix"]

  - skill: incident-response
    assignTo:
      all: true    # Todos los agentes
    when:
      taskPriority: "critical"
      taskTags: ["incident", "outage"]

Con esta configuración, cuando Rafa el ingeniero toma una tarea con tag deployment, automáticamente recibe la skill deployment-runbook. Si es una tarea marcada como critical con tag incident, todos los agentes reciben la skill incident-response.

Versionado de skills

Las skills se versionan automáticamente. Cuando editas una skill existente, se crea una nueva versión:

Skills Manager → [skill] → Version History

v2.1.0 (actual)   — 2026-04-05 — Añadida sección de Drizzle ORM
v2.0.0            — 2026-03-15 — Migración a Drizzle ORM documentada
v1.5.0            — 2026-02-01 — Event sourcing añadido
v1.0.0            — 2026-01-01 — Versión inicial

Si una actualización de skill introduce comportamiento incorrecto, puedes hacer rollback a cualquier versión anterior:

npx paperclipai skills:rollback \
  --skill devco-architecture \
  --version "2.0.0"

Plugin system: extender Paperclip

El plugin system de Paperclip permite añadir funcionalidades custom sin modificar el código core. Los plugins pueden:

Anatomía de un plugin

// plugins/slack-notifications/index.js
module.exports = {
  name: 'slack-notifications',
  version: '1.0.0',
  description: 'Envía notificaciones al Slack del equipo',
  
  // Hooks disponibles en el sistema
  hooks: {
    'task:completed': async (task, context) => {
      if (task.priority === 'critical') {
        await sendSlackMessage({
          channel: '#ops-alerts',
          text: `✅ Tarea crítica completada: ${task.title}`,
          agent: context.agent.name
        });
      }
    },
    
    'agent:budget_warning': async (agent, budget, context) => {
      await sendSlackMessage({
        channel: '#finance',
        text: `⚠️ ${agent.name} al ${budget.percentUsed}% de presupuesto`
      });
    },
    
    'board:approval_required': async (approval, context) => {
      await sendSlackMessage({
        channel: '#board-approvals',
        text: `🔔 Aprobación requerida: ${approval.title}`,
        blocks: buildApprovalBlocks(approval)
      });
    }
  }
};

Plugin de knowledge base

Un caso de uso muy poderoso es conectar Paperclip con una base de conocimiento externa. Los agentes pueden buscar en ella durante su ejecución:

// plugins/notion-knowledge/index.js
const { Client } = require('@notionhq/client');

module.exports = {
  name: 'notion-knowledge',
  
  // Añade una herramienta al toolkit de los agentes
  tools: {
    'search_knowledge_base': {
      description: 'Busca en la base de conocimiento interna de la empresa',
      parameters: {
        query: { type: 'string', description: 'Términos de búsqueda' }
      },
      handler: async ({ query }) => {
        const notion = new Client({ auth: process.env.NOTION_TOKEN });
        const results = await notion.search({ query, filter: { value: 'page' } });
        return results.results.map(page => ({
          title: page.properties.title?.title[0]?.plain_text,
          url: page.url,
          lastEdited: page.last_edited_time
        }));
      }
    }
  }
};

Plugin de custom tracing

Para integraciones con sistemas de observabilidad existentes:

// plugins/otel-tracing/index.js
const { trace } = require('@opentelemetry/api');

module.exports = {
  name: 'otel-tracing',
  
  hooks: {
    'heartbeat:start': (heartbeat) => {
      const span = trace.getTracer('paperclip')
        .startSpan(`heartbeat.${heartbeat.id}`);
      heartbeat._span = span;
    },
    
    'heartbeat:complete': (heartbeat, result) => {
      heartbeat._span?.setStatus({ code: result.success ? 'OK' : 'ERROR' });
      heartbeat._span?.end();
    },
    
    'tool_call:complete': (toolCall) => {
      trace.getTracer('paperclip')
        .startSpan(`tool.${toolCall.toolName}`)
        .setAttribute('cost_usd', toolCall.costUsd)
        .setAttribute('tokens', toolCall.tokensUsed)
        .end();
    }
  }
};

Instalar un plugin

# Plugin del repositorio oficial
npx paperclipai plugin:install slack-notifications

# Plugin desde npm
npx paperclipai plugin:install @mi-empresa/paperclip-plugin-crm

# Plugin local (desarrollo)
npx paperclipai plugin:install ./plugins/notion-knowledge

# Ver plugins instalados
npx paperclipai plugin:list

# Desactivar un plugin
npx paperclipai plugin:disable slack-notifications

Clipmart: el marketplace de templates (coming soon)

Clipmart es el marketplace oficial de Paperclip para templates de empresas, skills, y plugins. Aunque todavía está en desarrollo activo, la arquitectura ya está diseñada para soportarlo.

La promesa de Clipmart es: “instala una empresa de marketing en 5 minutos”. En lugar de definir cada agente desde cero, descarga una plantilla creada por alguien con experiencia en ese tipo de empresa, personaliza lo que necesitas, y empieza a operar.

Tipos de assets que habrá en Clipmart:

Org Templates:
  - startup-dev-team        (CEO + CTO + 4 ingenieros)
  - content-agency          (CEO + 3 content creators + SEO)
  - saas-support            (Head of Support + 5 L1 agents)
  - data-team               (Data Director + 3 analysts)

Skill Packs:
  - react-best-practices    (Skills para equipos React)
  - seo-2026               (Guías SEO actualizadas)
  - customer-success-ops   (Procedimientos de CS)

Plugin Collection:
  - github-integration     (Conectar Paperclip con GitHub)
  - linear-sync            (Sincronizar con Linear)
  - stripe-reporting       (Reportes de revenue de Stripe)

Para anticiparte al lanzamiento, puedes publicar tus propias templates en el formato correcto y contribuir a la comunidad:

# Exportar tu empresa como template para compartir
npx paperclipai company:export \
  --company company_devco \
  --type template \
  --public-name "DevCo SaaS Template" \
  --description "Plantilla para startups SaaS con equipo de desarrollo" \
  --output devco-template-public.json

# Cuando Clipmart esté disponible:
npx paperclipai clipmart:publish devco-template-public.json

AGENTS.md como configuración portable

El archivo AGENTS.md merece una sección propia porque es más que un archivo de configuración: es la forma de hacer que la configuración de tus agentes sea portable y versionable en git.

Cuando haces commit de un AGENTS.md bien diseñado en tu repositorio, cualquier agente que clone ese repo (Claude Code, OpenClaw, Codex) automáticamente recibe el contexto correcto. No necesitas configurar cada agente manualmente en la UI de Paperclip.

Un AGENTS.md maduro para un proyecto:

# AGENTS.md — DevCo API

Este archivo configura el comportamiento de todos los agentes de IA
que trabajen en este repositorio.

## Contexto del proyecto

DevCo API es un servidor Node.js + TypeScript que alimenta la plataforma
de gestión de inventario de DevCo. Stack: Express + Drizzle + PostgreSQL.

## Skills a cargar desde Paperclip

Cuando estés trabajando en este repo a través de Paperclip, las siguientes
skills son relevantes:
- @devco-architecture
- @code-standards
- @testing-guide
- @deployment-runbook (solo para tareas con tag "deployment")

## Instrucciones para agentes

### Para tareas de implementación:
1. Lee siempre src/domain/ antes de modificar src/application/
2. Los tests van en __tests__/ junto al archivo que testean
3. Nunca hagas push directo a main — crea una rama y un PR
4. Documenta las decisiones de arquitectura en /docs/adr/

### Para revisiones de código:
1. Verifica que los tests existen y pasan
2. Verifica que no hay secretos hardcodeados
3. Verifica que los nombres siguen las convenciones
4. Comenta en español, código en inglés

### Para deployments:
1. Verifica que todos los tests pasan localmente
2. Crea un tag de versión semántica
3. El pipeline de CI/CD hace el resto
4. Si hay duda, SIEMPRE pregunta al Board antes de hacer deploy a producción

## Límites de autonomía en este repo

- Puedes: leer, modificar código, correr tests, crear PRs
- NO puedes: hacer push a main, modificar .env, acceder a datos de producción
- SIEMPRE pide autorización para: deploys, migraciones de BD, cambios en infra

Casos de uso reales avanzados

Caso 1: Startup autónoma de contenidos

Una empresa de contenidos digitales con 3 empleados humanos y 8 agentes IA:

graph TD
    Board[Board - 3 humanos] --> CEO[CEO Agente]
    CEO --> ED[Editor en Jefe Agente]
    CEO --> SMM[Social Media Agente]
    ED --> W1[Redactor 1 Agente]
    ED --> W2[Redactor 2 Agente]
    ED --> SEO[SEO Specialist Agente]
    SMM --> SC[Scheduler Agente]
    CEO --> ANA[Analytics Agente]

Rutina diaria:

Costos mensuales estimados:

CEO Agente:             $15/mes
Editor en Jefe:         $30/mes
2x Redactores:          $80/mes (×2 = $160)
SEO Specialist:         $25/mes
Social Media:           $20/mes
Scheduler (proceso):    $0/mes (no usa LLM)
Analytics (proceso):    $0/mes (solo parsea métricas)
─────────────────────────────
Total:                  $250/mes

Para una operación que produce 20 artículos por semana, ese costo es marginal comparado con el salario de un equipo humano equivalente.

Caso 2: Agencia de desarrollo IA para clientes

Una agencia que usa Paperclip para gestionar proyectos de varios clientes simultáneamente:

Deployment único con 4 empresas:
  - Cliente A (SaaS fintech):     6 agentes, $300/mes
  - Cliente B (E-commerce):       4 agentes, $200/mes  
  - Cliente C (App móvil):        5 agentes, $250/mes
  - Agencia (ops internas):       3 agentes, $100/mes

Cada cliente tiene su propia empresa con aislamiento completo. La agencia puede:

Caso 3: Sistema de soporte técnico 24/7 con escalación inteligente

Un escenario de soporte con 5 niveles de resolución automática:

graph TD
    Ticket[Nuevo ticket] --> L0[Bot L0: FAQ lookup]
    L0 -->|resuelto| Done[Ticket cerrado]
    L0 -->|no resuelto| L1[Agente L1: análisis básico]
    L1 -->|resuelto| Done
    L1 -->|técnico| L2[Agente L2: análisis técnico]
    L2 -->|resuelto| Done
    L2 -->|bug confirmed| L3[Ingeniero L3: hotfix]
    L3 -->|fix aplicado| Done
    L3 -->|necesita diseño| L4[CTO: decisión arquitectónica]
    L4 -->|Board needed| Board[Board: decisión estratégica]

Con esta arquitectura, el 70-80% de los tickets se resuelven en el nivel L0 o L1 sin intervención humana. Solo los casos más complejos llegan al nivel L3 o superior.

El roadmap y la comunidad

Paperclip es un proyecto en evolución activa. Algunas áreas que están siendo desarrolladas actualmente:

Clipmart (marketplace): El marketplace de templates que hemos mencionado. Cuando esté disponible, instalas empresas enteras en un comando.

Federación: La capacidad de que empresas en diferentes deployments de Paperclip colaboren entre sí de forma segura. Imagine que tu agente CEO puede delegar tareas a la empresa de tu proveedor de servicios, también orquestada con Paperclip.

Agentes reactivos con memoria vectorial: Integración nativa con bases de datos vectoriales para que los agentes tengan memoria de largo plazo sobre el dominio específico de su empresa.

UI mobile: Una app móvil para el Board que permita aprobar requests, ver el estado, y hacer overrides desde el teléfono.

Mejores métricas de ROI: Dashboard nativo que combina costos de IA con métricas de negocio para calcular el ROI automáticamente.

Para seguir el desarrollo:

AGENTS.md en el ecosistema más amplio

El estándar AGENTS.md que Paperclip utiliza no es exclusivo de Paperclip. Es un estándar emergente en la industria de agentes IA que otros sistemas también están adoptando. Cuando escribes un AGENTS.md bien diseñado para tu proyecto, ese mismo archivo funciona con:

Esto significa que tu inversión en documentar bien los procedimientos, convenciones, y límites de autonomía en AGENTS.md beneficia a todos los agentes que trabajan en ese código, independientemente de la herramienta que uses.

Reflexión final: la empresa que trabaja mientras duermes

Al terminar este tutorial, tienes todos los elementos para construir algo que hace unos años habría sonado a ciencia ficción: una empresa de agentes IA que trabaja de forma autónoma, dentro de presupuesto, con trazabilidad completa, bajo tu supervisión como Board.

No es magia. Es infraestructura: un servidor Node.js, una base de datos PostgreSQL, y un modelo mental de empresa aplicado a la orquestación de agentes. Pero la combinación de esas piezas crea algo que ninguna de ellas tiene por sí sola: trabajo autónomo confiable.

El sistema no elimina la necesidad de supervisión humana. La canaliza hacia donde importa: las decisiones estratégicas, las aprobaciones de alto nivel, los casos que los agentes no pueden resolver. En lugar de estar en el camino crítico de cada tarea, eres el Board que establece la dirección y mantiene el control de la gobernanza.

Eso es lo que Paperclip hace posible. Una empresa de IA que escala sin escalar tu atención.

Suerte construyendo la tuya.

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