Composio-plugin

connector-composio är en vanlig RuntimePlugin i OHarness. Den använder Composios officiella REST-API för kontogranskning, upptäckt av scheman och körning av verktyg. Den inför inte MCP, en annan agentloop, en andra pluginvärd eller ett SDK-beroende. createConnectorPlugin är fortfarande den leverantörsneutrala hjälpen för adaptrar.

Omfattning och verifiering

Implementerat: uttryckliga tillåtelselistor för verktyg, bindning till konto och användare, konvertering av scheman, versionslåsning, avbrytning, gränser för svarsstorlek och OHarness behörighetsspärrar.
Implementerat: uttryckligt, människostyrt skapande av hostade autentiseringslänkar och kontostatus.
Inte implementerat: Pipedream, webhooks, ACL:er för delade konton, automatisk verifiering av callback-identitet för OAuth i OHarness Cloud, installation av fjärrplugins, automatisering av filuppladdning och -nedladdning eller hot reload under körning.
Testerna använder mockade HTTP-svar och kräver inga inloggningsuppgifter. Ett rökprov mot ett riktigt konto måste göras separat, med dina egna inloggningsuppgifter och ditt samtycke.

Composio rekommenderar Sessions för nya agentintegrationer och betecknar direkt körning som äldre. Den här första adaptern använder medvetet de direkta endpoints som fortfarande är dokumenterade, så att OHarness befintliga verktygsregister och behörigheter per verktyg behåller kontrollen. Bara uttryckligen valda verktyg exponeras, inte en generisk router som kan anropa vilken åtgärd som helst. Se den officiella guiden för direkt körning.

Den här direkta adaptern är till för uttryckligen konfigurerad utveckling och egenhostad användning. I den hostade produkten tillhör plattformens Composio-nyckel Cloud, inte varje klient. Använd molnkopplingen för den hostade produkten: den ger auktoriseringskort, serververifierad användarbindning och fortsättning av uppgifter.

1. Ange projektets API-nyckel

Sätt COMPOSIO_API_KEY i miljön för processen som kör OHarness. Lägg den inte i ditt repository, i chattmeddelanden eller i plugin-JSON. Konfigurationen kan ange en annan miljövariabel via apiKeyEnv.

Transporten skickar bara den här nyckeln till https://backend.composio.dev, avvisar HTTP-omdirigeringar och accepterar inget konfigurerbart API-ursprung. Alla fjärranrop är uttryckliga klientförfrågningar; att skapa eller importera pluginen gör inget anrop.

2. Se vad som redan är anslutet

Varje toolkit-post i konfigurationen behöver ett connectedAccountId, och den första frågan är om du redan har ett:

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

Endast läsning, avgränsat till den användaren och paginerat — skicka med --toolkit SLUG för att smalna av, --limit N (1–100, standard 50) för att ange sidstorlek, och --cursor med den cursor som ett tidigare anrop returnerade. Kommandot skriver ut id, toolkit, status och disabled per konto och inget annat: raderna från Composio innehåller fält för inloggningsuppgifter och tillstånd, och kommandot tar bort dem på samma sätt som kontogranskningen gör.

Ett konto som listas under en annan användare avvisas i stället för att döljas, eftersom ett svar som blandar användare inte går att lita på ens för de rader som matchade.

3. Anslut ett konto

Om listan är tom, eller om det toolkit du behöver saknas, skapar du en autentiseringskonfiguration för appen i Composio och begär sedan uttryckligen en hostad Connect Link från repot:

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

Kommandot gör en POST mot fjärrservern och skriver ut redirectUrl, connectedAccountId och eventuellt ett utgångsdatum. Öppna URL:en själv och slutför samtycket. Behandla den som en privat auktoriseringslänk: dela den inte med någon annan användare. Kommandot öppnar ingen webbläsare, godkänner ingen åtkomst, sparar ingen konfiguration och exponerar inget verktyg för att skapa länkar för agenten.

Granska den resulterande anslutningen med en läsförfrågan:

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

Fortsätt när statusen är ACTIVE, toolkit stämmer och disabled är false. Använd samma användar-id för länkning och körning. Adaptern avvisar medvetet ett konto som tillhör en annan användare, även om projektets API-nyckel skulle kunna nå det. Kontogranskning returnerar aldrig fält för inloggningsuppgifter eller tillstånd.

För en hostad produkt med flera användare härleder du userId från autentiserat apptillstånd och skapar Harness-instanser som är isolerade på lämpligt sätt. Acceptera det inte som indata från modellen. Composios valfria verifiering av callback-identitet kräver en autentiserad HTTPS-verifierare i din app; den här lokala adaptern implementerar inte den servern. Se den officiella dokumentationen om anslutningar och callback-identitet.

4. Aktivera pluginen

Bygg arbetsytan (npm run build) och lägg till en post i din användarpluginfil för OHarness, normalt ~/.oharness/plugins.json (eller $OHARNESS_HOME/plugins.json). Byt ut modulsökvägen, användar-id:t och konto-id:t; kopiera inte platshållarna som de är.

{
  "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 låter OHarness fortsätta fungera om den här valfria kopplingen inte kan starta; felet syns i /plugins och i webbens pluginlista. Sätt den till true bara om uppstarten måste misslyckas utan kopplingen. Projektkonfiguration kan inte aktivera körbara plugins eller ersätta deras betrodda kontokonfiguration.

Vid inbäddning använder du samma implementation 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().

Körningssemantik

Vid uppstart verifieras att varje konfigurerat konto tillhör den konfigurerade användaren, har det konfigurerade toolkit och är aktivt och inte avstängt.
Bara namngivna verktygs-slugs hämtas; högst 40 verktyg fördelade på 20 toolkits.
Den returnerade slugen och toolkit måste matcha tillåtelselistan. latest löses vid uppstart till en konkret daterad version, som återanvänds vid körning. En konfigurerad daterad version måste exakt matcha schemats returnerade version.
Verktyg registreras som composio__SLUG. Namn längre än 64 tecken kortas med ett stabilt hashsuffix. De exakta namnen syns i ToolRegistry.
Anrop går genom OHarness vanliga behörighetsmotor. Alla Composio-verktyg har readOnly: false och sessionLocal: false, även läsoperationer på fjärrsidan. Godkännande hoppas bara över när din vanliga, uttryckliga behörighetspolicy tillåter det.
Före varje körning kontrolleras kontots ägarskap, status och toolkit igen. POST-kuvertet använder den betrodda användaren, det betrodda kontot och den låsta versionen; modellens parametrar ligger under arguments och kan inte ersätta de fälten.
Lyckad data konverteras till ett ToolResult och går in i det vanliga agentflödet och körningsgranskningen. HTTP- och API-fel blir verktygsfel.

Verktygets indata måste vara ett objekt. Detaljerad validering mot argumentschemat görs av Composio; det returnerade JSON Schema ges till modellen. Bara uttryckliga verktygsimplementationer stöds, inte proxykörning, egna åsidosättningar av autentisering, körning via naturligt språk eller godtyckliga fjärr-URL:er. Adaptern läser eller laddar inte upp några lokala filer.

Inget HTTP-anrop görs om automatiskt. En avbruten eller misslyckad POST kan redan ha utfört åtgärden på fjärrsidan: granska den externa tjänsten eller Composios logg innan du försöker igen. Tidsgränsen per förfrågan är som standard 30 sekunder och kan ställas in från 100 ms till 120 sekunder. Svar begränsas till 2 MiB. Råa felmeddelanden och API-nycklar skickas inte vidare till loggar; lyckad data är fortfarande känslig appdata och är synlig för agenten, som avsett.

De första konto- och metadataförfrågningarna görs när pluginen aktiveras vid uppstart; initieringen skapar inget nytt konto och kör ingen åtgärd på tillåtelselistan.

Officiellt API-kontrakt som används

Adaptern riktar sig mot de dokumenterade /api/v3-routerna på backend.composio.dev. De kontrollerades mot den officiella dokumentationen den 2026-09-02; tester av HTTP-kontraktet bevisar inte auktorisering av ett riktigt konto eller att leverantören är tillgänglig.

← Plugins Molnkopplingar →