Composio-Plugin

connector-composio ist ein gewöhnliches OHarness-RuntimePlugin. Es nutzt die offizielle REST-API von Composio für Kontoprüfung, Schema-Erkennung und Tool-Ausführung. Es führt weder MCP noch eine weitere Agent-Schleife, einen zweiten Plugin-Host oder eine SDK-Abhängigkeit ein. createConnectorPlugin bleibt der anbieterneutrale Adapter-Helfer.

Umfang und Verifizierung

Implementiert: explizite Tool-Allowlists, Konto- und Nutzerbindung, Schema-Konvertierung, Versions-Pinning, Abbruch, Größenlimits für Antworten und die Berechtigungsschranken von OHarness.
Implementiert: explizit von einem Menschen ausgelöstes Erstellen gehosteter Auth-Links und Kontostatus.
Nicht implementiert: Pipedream, Webhooks, ACLs für geteilte Konten, automatische Identitätsprüfung von OAuth-Callbacks in OHarness Cloud, entfernte Plugin-Installation, automatisierter Datei-Upload/-Download und Hot Reload zur Laufzeit.
Tests verwenden gemockte HTTP-Antworten und brauchen keine Anmeldedaten. Ein Smoke-Test mit einem echten Konto muss separat mit Ihren eigenen Anmeldedaten und Ihrer Zustimmung durchgeführt werden.

Composio empfiehlt für neue Agent-Integrationen Sessions und bezeichnet die direkte Ausführung als Legacy. Dieser erste Adapter nutzt bewusst die weiterhin dokumentierten direkten Endpunkte, damit die bestehende Tool-Registry von OHarness und die Berechtigungen pro Tool die Kontrolle behalten. Bereitgestellt werden nur ausdrücklich ausgewählte Tools, kein generischer Router, der beliebige Aktionen aufrufen kann. Siehe die offizielle Anleitung zur direkten Ausführung.

Dieser direkte Adapter ist für explizit konfigurierte Entwicklungs- oder selbst gehostete Nutzung gedacht. Im gehosteten Produkt gehört der Composio-Schlüssel der Plattform der Cloud, nicht jedem Client. Verwenden Sie für das gehostete Produkt den Cloud-Connector: Er bietet Autorisierungskarten, serverseitig verifizierte Nutzerbindung und das Fortsetzen von Aufgaben.

1. Den API-Schlüssel des Projekts setzen

Setzen Sie COMPOSIO_API_KEY in der Umgebung des Prozesses, in dem OHarness läuft. Legen Sie ihn nicht in Ihr Repository, in Chatnachrichten oder in Plugin-JSON. Die Konfiguration kann über apiKeyEnv eine andere Umgebungsvariable benennen.

Der Transport sendet diesen Schlüssel nur an https://backend.composio.dev, lehnt HTTP-Weiterleitungen ab und akzeptiert keinen konfigurierbaren API-Origin. Alle entfernten Aufrufe sind explizite Client-Anfragen; das Erzeugen oder Importieren des Plugins löst keinen Aufruf aus.

2. Sehen, was bereits verbunden ist

Jeder Toolkit-Eintrag in der Konfiguration braucht eine connectedAccountId, und die erste Frage ist, ob Sie bereits eine haben:

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

Nur lesend, auf diesen Nutzer beschränkt und paginiert – übergeben Sie --toolkit SLUG zum Eingrenzen, --limit N (1–100, Standard 50) für die Seitengröße und --cursor mit dem cursor, den ein vorheriger Aufruf zurückgegeben hat. Pro Konto werden id, toolkit, status und disabled ausgegeben und sonst nichts: Die Upstream-Zeilen enthalten Felder für Anmeldedaten und Zustand, und dieser Befehl lässt sie genauso weg wie die Kontoprüfung.

Ein Konto, das unter einem anderen Nutzer aufgeführt ist, wird abgelehnt statt versteckt, denn einer Antwort, die Nutzer vermischt, ist auch bei den passenden Zeilen nicht zu trauen.

3. Ein Konto verbinden

Ist die Liste leer oder fehlt das benötigte Toolkit, legen Sie in Composio eine Auth-Konfiguration für die App an und fordern dann aus dem Repository ausdrücklich einen gehosteten Connect Link an:

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

Der Befehl führt einen entfernten POST aus und gibt redirectUrl, connectedAccountId und optional ein Ablaufdatum aus. Öffnen Sie diese URL selbst und erteilen Sie die Zustimmung. Behandeln Sie sie als privaten Autorisierungslink: Teilen Sie ihn mit keinem anderen Nutzer. Der Befehl öffnet keinen Browser, gibt keinen Zugriff frei, speichert keine Konfiguration und stellt dem Agenten kein Tool zum Erstellen von Links bereit.

Prüfen Sie die entstandene Verbindung mit einer nur lesenden Anfrage:

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

Fahren Sie fort, wenn der Status ACTIVE ist, das Toolkit stimmt und disabled false ist. Verwenden Sie dieselbe Nutzer-ID für Verknüpfung und Ausführung. Der Adapter lehnt ein Konto, das einem anderen Nutzer gehört, bewusst ab, selbst wenn der API-Schlüssel des Projekts darauf zugreifen könnte. Die Kontoprüfung gibt nie Felder für Anmeldedaten oder Zustand zurück.

Leiten Sie für ein gehostetes Produkt mit mehreren Nutzern userId aus dem authentifizierten Anwendungszustand ab und erstellen Sie entsprechend isolierte Harness-Instanzen. Akzeptieren Sie die ID nicht als Modelleingabe. Die optionale Identitätsprüfung für Callbacks bei Composio erfordert einen authentifizierten HTTPS-Verifier in Ihrer Anwendung; dieser lokale Adapter implementiert diesen Server nicht. Siehe die offizielle Dokumentation zu Verbindungen und Callback-Identität.

4. Das Plugin aktivieren

Bauen Sie den Workspace (npm run build) und fügen Sie einen Eintrag zu Ihrer OHarness-Plugin-Datei des Nutzers hinzu, normalerweise ~/.oharness/plugins.json (oder $OHARNESS_HOME/plugins.json). Ersetzen Sie Modulpfad, Nutzer-ID und Konto-ID; kopieren Sie Platzhalter nicht unverändert.

{
  "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 hält OHarness nutzbar, wenn dieser optionale Connector nicht starten kann; der Fehler ist in /plugins und in der Plugin-Liste der Web-Oberfläche sichtbar. Setzen Sie es nur dann auf true, wenn der Start ohne den Connector fehlschlagen muss. Projektkonfiguration kann keine ausführbaren Plugins aktivieren und deren vertrauenswürdige Kontokonfiguration nicht ersetzen.

Zum Einbetten verwenden Sie dieselbe Implementierung direkt:

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

Ausführungssemantik

Beim Start wird geprüft, ob jedes konfigurierte Konto dem konfigurierten Nutzer gehört, das konfigurierte Toolkit hat und aktiv bzw. nicht deaktiviert ist.
Nur benannte Tool-Slugs werden abgerufen; höchstens 40 Tools über 20 Toolkits.
Zurückgegebener Slug und Toolkit müssen zur Allowlist passen. latest wird beim Start zu einer konkreten, datierten Version aufgelöst und für die Ausführung wiederverwendet. Eine konfigurierte datierte Version muss exakt mit der zurückgegebenen Schema-Version übereinstimmen.
Tools werden als composio__SLUG registriert. Namen mit mehr als 64 Zeichen werden mit einem stabilen Hash-Suffix gekürzt. Die genauen Namen erscheinen in der ToolRegistry.
Aufrufe laufen durch die normale Berechtigungs-Engine von OHarness. Alle Composio-Tools haben readOnly: false und sessionLocal: false, auch entfernte Lesevorgänge. Die Freigabe entfällt nur, wenn Ihre normale, explizite Berechtigungsrichtlinie das erlaubt.
Vor jeder Ausführung werden Kontozugehörigkeit, Status und Toolkit erneut geprüft. Der POST-Umschlag verwendet den vertrauenswürdigen Nutzer, das vertrauenswürdige Konto und die gepinnte Version; Modellparameter liegen verschachtelt unter arguments und können diese Felder nicht ersetzen.
Erfolgreiche Daten werden in ein ToolResult umgewandelt und gelangen in den normalen Agent-Ablauf und das Ausführungs-Audit. HTTP- und API-Fehler werden zu Tool-Fehlern.

Tool-Eingaben müssen Objekte sein. Die detaillierte Validierung des Argumentschemas übernimmt Composio; das zurückgegebene JSON Schema wird dem Modell bereitgestellt. Unterstützt werden nur explizite Tool-Implementierungen, keine Proxy-Ausführung, keine eigenen Auth-Overrides, keine Ausführung per natürlicher Sprache und keine beliebigen entfernten URLs. Dieser Adapter liest oder lädt keine lokalen Dateien hoch.

Kein HTTP-Aufruf wird automatisch wiederholt. Ein abgebrochener oder fehlgeschlagener POST kann die entfernte Aktion bereits ausgeführt haben: Prüfen Sie vor einer Wiederholung den externen Dienst oder das Composio-Log. Der Timeout pro Anfrage beträgt standardmäßig 30 Sekunden und ist zwischen 100 ms und 120 Sekunden einstellbar. Antworten sind auf 2 MiB begrenzt. Rohe Fehlerinhalte und API-Schlüssel werden nicht in Logs weitergegeben; Erfolgsdaten bleiben sensible Anwendungsdaten und sind wie vorgesehen für den Agenten sichtbar.

Die ersten Konto- und Metadatenanfragen erfolgen, wenn das Plugin beim Start aktiviert ist; die Initialisierung legt kein neues Konto an und führt keine Aktion aus der Allowlist aus.

Verwendeter offizieller API-Vertrag

Der Adapter zielt auf die dokumentierten /api/v3-Routen auf backend.composio.dev. Sie wurden am 2026-09-02 mit der offiziellen Dokumentation abgeglichen; HTTP-Vertragstests sind kein Nachweis einer echten Kontoautorisierung oder der Verfügbarkeit beim Anbieter.

← Plugins Cloud-Connectors →