Composio-plugin

connector-composio is een gewone RuntimePlugin van OHarness. Hij gebruikt de officiële REST API van Composio om accounts te inspecteren, schema's te vinden en tools uit te voeren. Hij voegt geen MCP toe, geen tweede agent-lus, geen tweede pluginhost en geen SDK-afhankelijkheid. createConnectorPlugin blijft de leveranciersonafhankelijke helper voor adapters.

Reikwijdte en verificatie

Geïmplementeerd: expliciete allowlists voor tools, koppeling aan account en gebruiker, schemaconversie, vastgepinde versies, annulering, limieten op de antwoordgrootte en de permissiepoorten van OHarness.
Geïmplementeerd: het expliciet, door een mens, aanmaken van gehoste autorisatielinks en de accountstatus.
Niet geïmplementeerd: Pipedream, webhooks, ACL's voor gedeelde accounts, automatische verificatie van de callback-identiteit van OAuth in OHarness Cloud, installatie van plugins op afstand, automatisering van bestandsuploads en -downloads of hot reload tijdens runtime.
Tests gebruiken gesimuleerde HTTP-antwoorden en vereisen geen inloggegevens. Een smoke test met een live account moet je apart uitvoeren, met je eigen inloggegevens en toestemming.

Composio raadt Sessions aan voor nieuwe agent-integraties en noemt directe uitvoering legacy. Deze eerste adapter gebruikt bewust de nog steeds gedocumenteerde directe endpoints, zodat het bestaande toolregister van OHarness en de permissies per tool de controle houden. Alleen expliciet geselecteerde tools worden beschikbaar gemaakt, in plaats van een generieke router die elke willekeurige actie kan aanroepen. Zie de officiële handleiding voor directe uitvoering.

Deze directe adapter is bedoeld voor expliciet geconfigureerd gebruik bij ontwikkeling of zelfhosting. In het gehoste product hoort de Composio-sleutel van het platform bij Cloud, niet bij elke client. Gebruik voor het gehoste product de Cloud-connector: die biedt autorisatiekaarten, een door de server geverifieerde koppeling aan de gebruiker en voortzetting van de taak.

1. Stel de API-sleutel van het project in

Zet COMPOSIO_API_KEY in de omgeving van het proces waarin OHarness draait. Zet hem niet in je repository, chatberichten of plugin-JSON. De configuratie kan via apiKeyEnv een andere omgevingsvariabele noemen.

Het transport stuurt deze sleutel alleen naar https://backend.composio.dev, weigert HTTP-redirects en accepteert geen configureerbare API-origin. Alle aanroepen op afstand zijn expliciete clientverzoeken; de plugin aanmaken of importeren doet geen enkele aanroep.

2. Bekijk wat al gekoppeld is

Elke toolkit in de configuratie heeft een connectedAccountId nodig, en de eerste vraag is of je er al een hebt:

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

Alleen-lezen, beperkt tot die gebruiker en gepagineerd — geef --toolkit SLUG mee om in te perken, --limit N (1-100, standaard 50) voor de paginagrootte, en --cursor met de cursor die een vorige aanroep teruggaf. Het commando toont per account id, toolkit, status en disabled en verder niets: de rijen van de bron bevatten velden met inloggegevens en status, en dit commando laat die weg op dezelfde manier als accountinspectie dat doet.

Een account dat onder een andere gebruiker staat, wordt geweigerd in plaats van verborgen, want een antwoord waarin gebruikers door elkaar staan, is ook voor de rijen die wel klopten niet te vertrouwen.

3. Koppel een account

Is de lijst leeg, of ontbreekt de toolkit die je nodig hebt, maak dan in Composio een autorisatieconfiguratie voor de app aan en vraag daarna vanuit de repo expliciet een gehoste Connect Link aan:

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

Het commando doet een POST op afstand en toont redirectUrl, connectedAccountId en een optionele vervaldatum. Open die URL zelf en geef toestemming. Behandel hem als een privé-autorisatielink: deel hem niet met een andere gebruiker. Het commando opent geen browser, keurt geen toegang goed, slaat geen configuratie op en stelt geen tool voor het aanmaken van links beschikbaar aan de agent.

Controleer de resulterende koppeling met een alleen-lezen verzoek:

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

Ga verder als de status ACTIVE is, de toolkit klopt en disabled false is. Gebruik dezelfde gebruikers-id voor koppelen en uitvoeren. De adapter weigert bewust een account van een andere gebruiker, ook als de API-sleutel van het project er toegang toe zou hebben. Accountinspectie geeft nooit velden met inloggegevens of status terug.

Leid bij een gehost product voor meerdere gebruikers userId af uit de geauthenticeerde status van de applicatie en maak passend geïsoleerde Harness-instanties aan. Accepteer het niet als modelinvoer. De optionele verificatie van de callback-identiteit van Composio vereist een geauthenticeerde HTTPS-verifier in je applicatie; deze lokale adapter implementeert die server niet. Zie de officiële documentatie over koppelingen en callback-identiteit.

4. Zet de plugin aan

Bouw de werkruimte (npm run build) en voeg een vermelding toe aan je OHarness-pluginbestand voor de gebruiker, normaal ~/.oharness/plugins.json (of $OHARNESS_HOME/plugins.json). Vervang het modulepad, de gebruikers-id en de account-id; kopieer placeholders niet zoals ze zijn.

{
  "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"]
          }
        ]
      }
    }
  ]
}

Met required: false blijft OHarness bruikbaar als deze optionele connector niet kan starten; de fout is zichtbaar in /plugins en in de pluginlijst van Web. Zet het alleen op true als het opstarten zonder de connector moet mislukken. Projectconfiguratie kan geen uitvoerbare plugins aanzetten en hun vertrouwde accountconfiguratie niet vervangen.

Gebruik voor embedding direct dezelfde implementatie:

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

Uitvoeringssemantiek

Bij het opstarten wordt voor elk geconfigureerd account gecontroleerd of het bij de geconfigureerde gebruiker hoort, de geconfigureerde toolkit heeft en actief/niet uitgeschakeld is.
Alleen genoemde tool-slugs worden opgehaald; maximaal 40 tools over 20 toolkits.
De teruggegeven slug/toolkit moet overeenkomen met de allowlist. latest wordt bij het opstarten omgezet naar een concrete gedateerde versie, die bij het uitvoeren wordt hergebruikt. Een geconfigureerde gedateerde versie moet exact overeenkomen met de teruggegeven schemaversie.
Tools worden geregistreerd als composio__SLUG. Namen langer dan 64 tekens worden ingekort met een stabiel hash-achtervoegsel. De exacte namen staan in ToolRegistry.
Aanroepen gaan door de normale permissie-engine van OHarness. Alle Composio-tools hebben readOnly: false en sessionLocal: false, ook leesacties op afstand. Goedkeuring wordt alleen overgeslagen als je normale, expliciete permissiebeleid dat toestaat.
Vóór elke uitvoering worden eigendom, status en toolkit van het account opnieuw gecontroleerd. De POST-envelop gebruikt de vertrouwde gebruiker/het vertrouwde account en de vastgepinde versie; modelparameters staan genest onder arguments en kunnen die velden niet vervangen.
Geslaagde data wordt omgezet in een ToolResult en gaat de gewone agent-flow en uitvoeringsaudit in. HTTP- en API-fouten worden toolfouten.

Toolinvoer moet een object zijn. Gedetailleerde validatie van het argumentschema doet Composio; het teruggegeven JSON Schema gaat naar het model. Alleen expliciete toolimplementaties worden ondersteund, geen proxy-uitvoering, eigen auth-overrides, uitvoering in natuurlijke taal of willekeurige URL's op afstand. Deze adapter leest of uploadt geen lokale bestanden.

Geen enkele HTTP-aanroep wordt automatisch opnieuw geprobeerd. Een geannuleerde of mislukte POST kan de actie op afstand al hebben uitgevoerd: controleer de externe dienst of het Composio-log voordat je het opnieuw probeert. De time-out per verzoek is standaard 30 seconden en is in te stellen van 100 ms tot 120 seconden. Antwoorden zijn begrensd op 2 MiB. Ruwe foutberichten en API-sleutels komen niet in logs terecht; geslaagde data blijft gevoelige applicatiedata en is, zoals bedoeld, zichtbaar voor de agent.

De eerste verzoeken voor account en metadata gebeuren wanneer de plugin bij het opstarten is ingeschakeld; initialisatie maakt geen nieuw account aan en voert geen enkele actie uit de allowlist uit.

Gebruikt officieel API-contract

De adapter richt zich op de gedocumenteerde /api/v3-routes op backend.composio.dev. Die zijn op 2026-09-02 gecontroleerd aan de hand van de officiële documentatie; HTTP-contracttests bewijzen geen live accountautorisatie of beschikbaarheid van de leverancier.

← Plugins Cloudconnectors →