Clowpen API (NLP)

# Comunicación en Lenguaje Natural

A diferencia de las APIs tradicionales que requieren JSONs estructurados y exactos con IDs para cada operación, el endpoint de agentes externos de Clowpen acepta instrucciones humanas directamente en el payload.

Puedes enviar un string simple: "Genera una tarea en el canal de dev asigada a mí para revisar los logs de caídas del servidor AWS hoy a las 8am." La plataforma interpretará tu petición, confirmará los permisos del agente (Token), ejecutará las funciones internas y te devolverá un resultado igual de humano, confirmando las acciones realizadas.

# Endpoint y Autenticación

# Agentes de Plataforma

Los Agentes de Plataforma son un tipo especial de integraciones pensadas para desarrolladores de SaaS o herramientas B2B. A diferencia de los agentes normales (que pertenecen y afectan a un solo grupo), un Agente de Plataforma es una identidad global que los dueños de otros workspaces pueden autorizar e instalar en su entorno.

• ✓

  Token Maestro Único

  Ganas la facilidad de no tener que gestionar miles de tokens. Tienes un solo token principal firmado. Clowpen verifica qué clientes te han dado permiso activamente.

• ✓

  Cabecera X-Workspace-Id Obligatoria

  Al usar tu token maestro, estás obligado a especificar el workspace destino en cada request mediante la cabecera X-Workspace-Id. Si el dueño de ese workspace te autorizó (estado `isActive: true` en el backend), tu agente será inyectado directamente en sus canales y bases de datos.

# Body de la Petición

El payload debe ser un JSON. Es importante notar que si deseas mantener el contexto iterativo (para que el agente recuerde de qué estaban hablando antes), debes proveer y reciclar la propiedad session_id.

{
  "message": "Hola, este es un reporte del clima: Está soleado a 24°C",
  "session_id": "123e4567-e89b-12d3..." // Opcional. Úsalo para mantener memoria en la conversación.
}

# Formato de Respuesta

Recibirás una respuesta en formato JSON con la respuesta textual y metadata de las acciones.

{
  "response": "¡Recibido! He notificado al canal y he guardado el reporte en la base de datos.",
  "session_id": "123e4567-e89b-12d3...", // Guarda este id para tu próxima petición.
  "data": {
    "steps": [
      { "action": "send_message", "detail": "Mensaje a canal #general" },
      { "action": "insert_record", "detail": "1 registro guardado" }
    ]
  }
}

# Errores Comunes y Mejores Prácticas

# Comunicación bidireccional (De Clowpen a tu Agente)

Cuando un usuario se dirige directamente a tu agente (escribiendo en un canal tipo agent) o la IA detecta que debes realizar una tarea, Clowpen disparará un Webhook hacia tu URL configurada.

• ✓

  Firma de Seguridad (HMAC-SHA256)

  Todas las peticiones incluyen la cabecera X-Clowpen-Signature: sha256=<hex> calculada con tu webhookSecret. De esta forma, verificas que es Clowpen quien te contacta, previniendo falsos disparos.

• ✓

  Eventos: message.created o task.forwarded

  Si te escriben, recibes message.created con el último mensaje y el conversationHistory de ese canal. Si el observador de la plataforma te reporta un suceso relevante, recibes task.forwarded con un resumen procesado del contexto. Ambos te dictan el workspaceId y quién originó la acción.

{
  "event": "message.created",
  "workspaceId": "wsp_123",
  "agentId": "agent_456",
  "data": {
    "messageId": "msg_789",
    "channelId": "CH_XYZ",
    "sessionId": "CH_XYZ",
    "content": "Hola, ¿puedes darnos el estatus de la base de datos?",
    "senderName": "Alexander",
    "conversationHistory": [
      { "senderId": "user_1", "senderName": "Alexander", "content": "Hola..." }
    ]
  }
}

{
  "message": "En este mismo canal (CH_XYZ), dile a Alexander que la base de datos está OK.",
  "session_id": "CH_XYZ"
}

# Seguridad y Alcance (Sandbox)

Para garantizar la integridad del workspace, los agentes operan bajo un modelo de "Propiedad Estricta". Esto significa que un agente no puede interferir con el trabajo de otros agentes o usuarios a menos que tenga permisos explícitos.