Plugin Composio

connector-composio è un normale RuntimePlugin di OHarness. Usa la REST API ufficiale di Composio per l'ispezione degli account, la scoperta degli schemi e l'esecuzione degli strumenti. Non introduce MCP, un altro ciclo dell'agente, un secondo host di plugin né una dipendenza da SDK. createConnectorPlugin resta l'helper di adattamento indipendente dal fornitore.

Ambito e verifica

Implementato: allowlist esplicite degli strumenti, associazione account/utente, conversione degli schemi, blocco della versione, annullamento, limiti sulla dimensione delle risposte e filtri dei permessi di OHarness.
Implementato: creazione esplicita, gestita da una persona, di link di autorizzazione ospitati e stato dell'account.
Non implementato: Pipedream, webhook, ACL per account condivisi, verifica automatica dell'identità nel callback OAuth in OHarness Cloud, installazione remota di plugin, automazione di upload/download di file o ricaricamento a caldo del runtime.
I test usano risposte HTTP simulate e non richiedono credenziali. Uno smoke test su un account reale va eseguito a parte, con le tue credenziali e il tuo consenso.

Composio consiglia le Sessions per le nuove integrazioni di agenti e indica l'esecuzione diretta come legacy. Questo primo adattatore usa di proposito gli endpoint diretti, ancora documentati, per mantenere il controllo nel registro degli strumenti di OHarness e nei permessi per singolo strumento. Vengono esposti solo gli strumenti selezionati esplicitamente, non un router generico capace di invocare un'azione arbitraria. Vedi la guida ufficiale all'esecuzione diretta.

Questo adattatore diretto è pensato per un uso di sviluppo/self-hosted configurato esplicitamente. Nel prodotto ospitato, la chiave Composio della piattaforma appartiene a Cloud, non a ciascun client. Per il prodotto ospitato usa il connettore Cloud: fornisce schede di autorizzazione, associazione dell'utente verificata dal server e continuazione delle attività.

1. Imposta la chiave API del progetto

Imposta COMPOSIO_API_KEY nell'ambiente del processo che esegue OHarness. Non metterla nel repository, nei messaggi di chat o nel JSON del plugin. La configurazione può indicare un'altra variabile d'ambiente tramite apiKeyEnv.

Il trasporto invia questa chiave solo a https://backend.composio.dev, rifiuta i redirect HTTP e non accetta un'origine API configurabile. Tutte le chiamate remote sono richieste esplicite del client; costruire/importare il plugin non effettua alcuna chiamata.

2. Guarda cosa è già connesso

Ogni voce di toolkit nella configurazione richiede un connectedAccountId, e la prima domanda è se ne hai già uno:

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

In sola lettura, limitato a quell'utente e paginato: passa --toolkit SLUG per restringere, --limit N (1-100, predefinito 50) per la dimensione della pagina e --cursor con il cursor restituito da una chiamata precedente. Stampa id, toolkit, status e disabled per ogni account e nient'altro: le righe a monte contengono campi di credenziali e di stato, e questo comando li scarta come fa l'ispezione degli account.

Un account elencato sotto un altro utente viene rifiutato anziché nascosto, perché di una risposta che mescola utenti non ci si può fidare nemmeno per le righe che corrispondevano.

3. Connetti un account

Se l'elenco è vuoto, o manca il toolkit che ti serve, crea in Composio una configurazione di autorizzazione per l'app e poi richiedi esplicitamente dal repository un Connect Link ospitato:

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

Il comando esegue una POST remota e stampa redirectUrl, connectedAccountId e una scadenza opzionale. Apri tu quell'URL e completa il consenso. Trattalo come un link di autorizzazione privato: non condividerlo con altri utenti. Il comando non apre un browser, non approva l'accesso, non salva la configurazione e non espone all'agente uno strumento per creare link.

Ispeziona la connessione risultante con una richiesta in sola lettura:

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

Prosegui quando lo stato è ACTIVE, il toolkit è corretto e disabled è false. Usa lo stesso ID utente per il collegamento e per l'esecuzione. L'adattatore rifiuta di proposito un account che appartiene a un altro utente, anche se la chiave API del progetto potrebbe accedervi. L'ispezione degli account non restituisce mai campi di credenziali/stato.

Per un prodotto ospitato multiutente, ricava userId dallo stato autenticato dell'applicazione e crea istanze di Harness adeguatamente isolate. Non accettarlo come input del modello. La verifica opzionale dell'identità nel callback di Composio richiede nella tua applicazione un verificatore HTTPS autenticato; questo adattatore locale non implementa quel server. Vedi la documentazione ufficiale su connessione e identità nel callback.

4. Attiva il plugin

Compila lo spazio di lavoro (npm run build) e aggiungi una voce al tuo file dei plugin OHarness a livello utente, di solito ~/.oharness/plugins.json (o $OHARNESS_HOME/plugins.json). Sostituisci il percorso del modulo, l'ID utente e l'ID account; non copiare i segnaposto così come sono.

{
  "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 lascia OHarness utilizzabile se questo connettore opzionale non riesce ad avviarsi; l'errore è visibile in /plugins e nell'elenco dei plugin del Web. Impostalo a true solo se l'avvio deve fallire senza il connettore. La configurazione di progetto non può attivare plugin eseguibili né sostituire la loro configurazione di account attendibile.

Per l'integrazione nel codice, usa direttamente la stessa implementazione:

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().

Semantica di esecuzione

All'avvio si verifica che ogni account configurato appartenga all'utente configurato, abbia il toolkit configurato e sia attivo/non disabilitato.
Vengono recuperati solo gli slug di strumenti indicati; al massimo 40 strumenti su 20 toolkit.
Lo slug/toolkit restituito deve corrispondere all'allowlist. latest viene risolto all'avvio in una versione datata concreta, riutilizzata per l'esecuzione. Una versione datata configurata deve corrispondere esattamente alla versione dello schema restituito.
Gli strumenti vengono registrati come composio__SLUG. I nomi più lunghi di 64 caratteri vengono accorciati con un suffisso hash stabile. I nomi esatti compaiono nel ToolRegistry.
Le chiamate passano per il normale motore dei permessi di OHarness. Tutti gli strumenti Composio hanno readOnly: false e sessionLocal: false, anche le operazioni remote di lettura. L'approvazione viene saltata solo quando la tua normale policy esplicita dei permessi lo consente.
Prima di ogni esecuzione, proprietà, stato e toolkit dell'account vengono ricontrollati. L'envelope della POST usa l'utente/account attendibile e la versione bloccata; i parametri del modello sono annidati sotto arguments e non possono sostituire quei campi.
I dati di un esito positivo vengono convertiti in un ToolResult ed entrano nel normale flusso dell'agente e nell'audit di esecuzione. Gli errori HTTP/API diventano errori dello strumento.

L'input dello strumento deve essere un oggetto. La convalida dettagliata dello schema degli argomenti è affidata a Composio; il JSON Schema restituito viene fornito al modello. Sono supportate solo implementazioni esplicite degli strumenti, non l'esecuzione via proxy, sostituzioni personalizzate dell'autorizzazione, esecuzione in linguaggio naturale o URL remoti arbitrari. Questo adattatore non legge né carica file locali.

Nessuna chiamata HTTP viene ripetuta automaticamente. Una POST annullata/fallita potrebbe aver già eseguito l'azione remota: controlla il servizio esterno o il log di Composio prima di riprovare. Il timeout per richiesta è di 30 secondi per impostazione predefinita ed è configurabile da 100 ms a 120 secondi. Le risposte sono limitate a 2 MiB. I corpi di errore grezzi e le chiavi API non vengono inoltrati ai log; i dati degli esiti positivi restano dati applicativi sensibili e sono visibili all'agente, come previsto.

Le prime richieste di account/metadati avvengono quando il plugin viene attivato all'avvio; l'inizializzazione non crea un nuovo account né esegue alcuna azione in allowlist.

Contratto API ufficiale utilizzato

L'adattatore usa le route documentate /api/v3 su backend.composio.dev. Sono state verificate rispetto alla documentazione ufficiale il 2026-09-02; i test di contratto HTTP non provano l'autorizzazione di un account reale né la disponibilità del fornitore.

← Plugin Connettori cloud →