Plugin de Composio

connector-composio es un RuntimePlugin normal de OHarness. Usa la API REST oficial de Composio para inspeccionar cuentas, descubrir esquemas y ejecutar herramientas. No introduce MCP, otro bucle del agente, un segundo host de plugins ni una dependencia de SDK. createConnectorPlugin sigue siendo el helper de adaptador independiente del proveedor.

Alcance y verificación

Implementado: listas explícitas de herramientas permitidas, vinculación de cuenta/usuario, conversión de esquemas, fijación de versiones, cancelación, límites de tamaño de respuesta y barreras de permisos de OHarness.
Implementado: creación explícita, operada por una persona, de enlaces de autorización alojados y estado de la cuenta.
No implementado: Pipedream, webhooks, ACL de cuentas compartidas, verificación automática de identidad en el callback OAuth en OHarness Cloud, instalación remota de plugins, automatización de subida/descarga de archivos ni recarga en caliente del runtime.
Las pruebas usan respuestas HTTP simuladas y no requieren credenciales. Una prueba de humo con una cuenta real debe hacerse por separado con tus propias credenciales y consentimiento.

Composio recomienda Sessions para las integraciones de agentes nuevas y marca la ejecución directa como heredada. Este primer adaptador usa a propósito los endpoints directos, todavía documentados, para mantener bajo control el registro de herramientas existente de OHarness y los permisos por herramienta. Solo se exponen las herramientas seleccionadas explícitamente, en lugar de un enrutador genérico capaz de invocar una acción arbitraria. Consulta la guía oficial de ejecución directa.

Este adaptador directo es para un uso de desarrollo o autoalojado configurado explícitamente. En el producto alojado, la clave de Composio de la plataforma pertenece a Cloud, no a cada cliente. Usa el conector en la nube para el producto alojado: ofrece tarjetas de autorización, vinculación de usuario verificada por el servidor y continuación de tareas.

1. Define la clave API del proyecto

Define COMPOSIO_API_KEY en el entorno del proceso que ejecuta OHarness. No la pongas en tu repositorio, en mensajes de chat ni en el JSON del plugin. La configuración puede indicar otra variable de entorno mediante apiKeyEnv.

El transporte solo envía esta clave a https://backend.composio.dev, rechaza las redirecciones HTTP y no acepta un origen de API configurable. Todas las llamadas remotas son solicitudes explícitas del cliente; construir o importar el plugin no hace ninguna llamada.

2. Mira qué está ya conectado

Cada entrada de toolkit de la configuración necesita un connectedAccountId, y la primera pregunta es si ya tienes uno:

npm run composio:auth -- list --user YOUR_USER_ID

Es de solo lectura, limitado a ese usuario y paginado: pasa --toolkit SLUG para acotarlo, --limit N (1-100, 50 por defecto) para fijar el tamaño de la página, y --cursor con el cursor que devolvió una llamada anterior. Imprime id, toolkit, status y disabled por cuenta y nada más: las filas de origen llevan campos de credenciales y de estado, y este comando los descarta igual que la inspección de cuentas.

Una cuenta listada bajo otro usuario se rechaza en lugar de ocultarse, porque no conviene fiarse de una respuesta que mezcla usuarios ni siquiera para las filas que sí coincidían.

3. Conecta una cuenta

Si la lista está vacía, o falta el toolkit que necesitas, crea una configuración de autorización para la app en Composio y luego solicita explícitamente un Connect Link alojado desde el repositorio:

npm run composio:auth -- link --user YOUR_USER_ID --auth-config ac_YOUR_AUTH_CONFIG

El comando hace un POST remoto e imprime redirectUrl, connectedAccountId y una caducidad opcional. Abre esa URL tú mismo y completa el consentimiento. Trátala como un enlace de autorización privado: no la compartas con otro usuario. El comando no abre un navegador, no aprueba el acceso, no guarda la configuración ni expone al agente una herramienta para crear enlaces.

Inspecciona la conexión resultante con una solicitud de solo lectura:

npm run composio:auth -- status --user YOUR_USER_ID --account ca_YOUR_ACCOUNT

Continúa cuando el estado sea ACTIVE, el toolkit sea el correcto y disabled sea false. Usa el mismo ID de usuario para vincular y para ejecutar. El adaptador rechaza deliberadamente una cuenta que pertenezca a otro usuario, aunque la clave API del proyecto pudiera acceder a ella. La inspección de cuentas nunca devuelve campos de credenciales ni de estado.

Para un producto alojado multiusuario, obtén userId del estado autenticado de la aplicación y crea instancias de Harness aisladas adecuadamente. No lo aceptes como entrada del modelo. La verificación opcional de identidad en el callback de Composio requiere un verificador HTTPS autenticado en tu aplicación; este adaptador local no implementa ese servidor. Consulta la documentación oficial de conexiones e identidad en el callback.

4. Habilita el plugin

Compila el espacio de trabajo (npm run build) y añade una entrada a tu archivo de plugins de OHarness de usuario, normalmente ~/.oharness/plugins.json (o $OHARNESS_HOME/plugins.json). Sustituye la ruta del módulo, el ID de usuario y el ID de cuenta; no copies los marcadores tal cual.

{
  "runtimePlugins": [
    {
      "id": "connector-composio",
      "module": "/absolute/path/to/OHarness/packages/engine/dist/runtime-plugins/composio/index.js",
      "enabled": true,
      "required": false,
      "config": {
        "userId": "YOUR_USER_ID",
        "apiKeyEnv": "COMPOSIO_API_KEY",
        "timeoutMs": 30000,
        "toolkits": [
          {
            "slug": "gmail",
            "connectedAccountId": "ca_YOUR_ACCOUNT",
            "version": "latest",
            "tools": ["GMAIL_GET_PROFILE"]
          }
        ]
      }
    }
  ]
}

required: false deja OHarness utilizable si este conector opcional no puede arrancar; el fallo se ve en /plugins y en la lista de plugins de la web. Ponlo a true solo si el arranque debe fallar sin el conector. La configuración del proyecto no puede habilitar plugins ejecutables ni sustituir su configuración de cuenta de confianza.

Para integrarlo en tu código, usa directamente la misma implementación:

import { Harness, composioPlugin, jsonlAuditPlugin } from "@oharness/engine";

const harness = await Harness.create({
  runtimePlugins: [
    {
      plugin: composioPlugin,
      config: {
        userId: authenticatedUserId,
        toolkits: [{
          slug: "gmail", connectedAccountId: approvedAccountId,
          version: "latest", tools: ["GMAIL_GET_PROFILE"],
        }],
      },
    },
    { plugin: jsonlAuditPlugin, config: { path: "/absolute/path/to/audit.jsonl" } },
  ],
});
// Use the existing Session / Agent API, then await harness.close().

Semántica de ejecución

Al arrancar se verifica que cada cuenta configurada pertenezca al usuario configurado, tenga el toolkit configurado y esté activa/no deshabilitada.
Solo se obtienen los slugs de herramienta indicados; como máximo 40 herramientas en 20 toolkits.
El slug/toolkit devuelto debe coincidir con la lista de permitidas. latest se resuelve al arrancar a una versión concreta con fecha, que se reutiliza para la ejecución. Una versión con fecha configurada debe coincidir exactamente con la versión del esquema devuelto.
Las herramientas se registran como composio__SLUG. Los nombres de más de 64 caracteres se acortan con un sufijo hash estable. Los nombres exactos aparecen en ToolRegistry.
Las llamadas pasan por el motor de permisos normal de OHarness. Todas las herramientas de Composio tienen readOnly: false y sessionLocal: false, incluso las operaciones remotas de lectura. La aprobación solo se omite cuando tu política de permisos explícita habitual lo permite.
Antes de cada ejecución se vuelven a comprobar la propiedad, el estado y el toolkit de la cuenta. El sobre del POST usa el usuario/cuenta de confianza y la versión fijada; los parámetros del modelo van anidados bajo arguments y no pueden sustituir esos campos.
Los datos de un resultado correcto se convierten en un ToolResult y entran en el flujo normal del agente y en la auditoría de ejecución. Los fallos HTTP/API se convierten en errores de herramienta.

La entrada de la herramienta debe ser un objeto. La validación detallada del esquema de argumentos la hace Composio; el JSON Schema devuelto se entrega al modelo. Solo se admiten implementaciones explícitas de herramientas, no la ejecución por proxy, las anulaciones de autorización personalizadas, la ejecución en lenguaje natural ni URL remotas arbitrarias. Este adaptador no lee ni sube archivos locales.

Ninguna llamada HTTP se reintenta automáticamente. Un POST cancelado o fallido puede haber realizado ya la acción remota: revisa el servicio externo o el log de Composio antes de reintentar. El tiempo de espera por solicitud es de 30 segundos por defecto y se puede configurar entre 100 ms y 120 segundos. Las respuestas se limitan a 2 MiB. Los cuerpos de error sin procesar y las claves API no se envían a los logs; los datos de éxito siguen siendo datos sensibles de la aplicación y el agente los ve, como se pretende.

Las primeras solicitudes de cuenta y metadatos se producen cuando el plugin se habilita al arrancar; la inicialización no crea una cuenta nueva ni ejecuta ninguna acción de la lista de permitidas.

Contrato de la API oficial utilizado

El adaptador apunta a las rutas documentadas /api/v3 en backend.composio.dev. Se comprobaron con la documentación oficial el 2026-09-02; las pruebas del contrato HTTP no demuestran la autorización de una cuenta real ni la disponibilidad del proveedor.

← Plugins Conectores en la nube →