Wtyczka Composio

connector-composio to zwykły RuntimePlugin OHarness. Korzysta z oficjalnego REST API Composio do sprawdzania kont, poznawania schematów i wykonywania narzędzi. Nie wprowadza MCP, drugiej pętli agenta, drugiego hosta wtyczek ani zależności od SDK. createConnectorPlugin pozostaje neutralnym wobec dostawców pomocnikiem do adapterów.

Zakres i weryfikacja

Zaimplementowane: jawne listy dozwolonych narzędzi, powiązanie konta z użytkownikiem, konwersja schematów, przypinanie wersji, anulowanie, limity rozmiaru odpowiedzi i bramki uprawnień OHarness.
Zaimplementowane: jawne, obsługiwane przez człowieka tworzenie hostowanych linków autoryzacyjnych i status konta.
Niezaimplementowane: Pipedream, webhooki, ACL dla kont współdzielonych, automatyczna weryfikacja tożsamości w callbacku OAuth w OHarness Cloud, zdalna instalacja wtyczek, automatyzacja wysyłania i pobierania plików ani przeładowywanie w trakcie działania.
Testy używają zasymulowanych odpowiedzi HTTP i nie wymagają poświadczeń. Test dymny na prawdziwym koncie trzeba wykonać osobno, z własnymi poświadczeniami i za własną zgodą.

Composio zaleca Sessions dla nowych integracji agentów, a bezpośrednie wykonywanie oznacza jako starsze rozwiązanie. Ten pierwszy adapter celowo używa nadal udokumentowanych bezpośrednich endpointów, aby kontrolę zachowały istniejący rejestr narzędzi OHarness i uprawnienia na poziomie narzędzi. Udostępniane są tylko jawnie wybrane narzędzia, a nie ogólny router zdolny wywołać dowolną akcję. Zobacz oficjalny poradnik bezpośredniego wykonywania.

Ten bezpośredni adapter służy do jawnie skonfigurowanego użycia deweloperskiego lub hostowanego samodzielnie. W produkcie hostowanym platformowy klucz Composio należy do Cloud, a nie do każdego klienta. W produkcie hostowanym używaj konektora w chmurze: zapewnia karty autoryzacji, powiązanie użytkownika weryfikowane przez serwer i kontynuację zadania.

1. Ustaw klucz API projektu

Ustaw COMPOSIO_API_KEY w środowisku procesu, w którym działa OHarness. Nie umieszczaj go w repozytorium, wiadomościach czatu ani w JSON-ie wtyczki. Konfiguracja może wskazać inną zmienną środowiskową przez apiKeyEnv.

Warstwa transportowa wysyła ten klucz wyłącznie do https://backend.composio.dev, odrzuca przekierowania HTTP i nie przyjmuje konfigurowalnego originu API. Wszystkie zdalne wywołania to jawne żądania klienta; samo utworzenie lub zaimportowanie wtyczki niczego nie wywołuje.

2. Sprawdź, co jest już połączone

Każdy wpis zestawu narzędzi w konfiguracji potrzebuje connectedAccountId, a pierwsze pytanie brzmi, czy już takie masz:

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

Tylko do odczytu, zawężone do tego użytkownika i stronicowane — podaj --toolkit SLUG, aby zawęzić wynik, --limit N (1-100, domyślnie 50), aby ustalić rozmiar strony, oraz --cursor z wartością cursor zwróconą przez poprzednie wywołanie. Dla każdego konta wypisuje id, toolkit, status i disabled i nic więcej: wiersze z serwera zawierają pola poświadczeń i stanu, a to polecenie je odrzuca, tak samo jak sprawdzanie kont.

Konto przypisane do innego użytkownika jest odrzucane, a nie ukrywane, bo odpowiedzi mieszającej użytkowników nie można ufać także w wierszach, które pasowały.

3. Połącz konto

Jeśli lista jest pusta albo brakuje w niej potrzebnego zestawu narzędzi, utwórz w Composio konfigurację autoryzacji dla aplikacji, a następnie jawnie zażądaj z repozytorium hostowanego Connect Link:

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

Polecenie wykonuje zdalny POST i wypisuje redirectUrl, connectedAccountId oraz opcjonalny czas wygaśnięcia. Otwórz ten URL samodzielnie i udziel zgody. Traktuj go jak prywatny link autoryzacyjny: nie udostępniaj go innemu użytkownikowi. Polecenie nie otwiera przeglądarki, nie zatwierdza dostępu, nie zapisuje konfiguracji ani nie udostępnia agentowi narzędzia do tworzenia linków.

Sprawdź powstałe połączenie żądaniem tylko do odczytu:

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

Kontynuuj, gdy status to ACTIVE, zestaw narzędzi się zgadza, a disabled ma wartość false. Do łączenia i wykonywania używaj tego samego identyfikatora użytkownika. Adapter celowo odrzuca konto należące do innego użytkownika, nawet jeśli klucz API projektu miałby do niego dostęp. Sprawdzanie konta nigdy nie zwraca pól poświadczeń ani stanu.

W wieloużytkownikowym produkcie hostowanym wyprowadzaj userId z uwierzytelnionego stanu aplikacji i twórz odpowiednio odizolowane instancje Harness. Nie przyjmuj go od modelu. Opcjonalna weryfikacja tożsamości w callbacku Composio wymaga uwierzytelnionego weryfikatora HTTPS w twojej aplikacji; ten lokalny adapter nie implementuje takiego serwera. Zobacz oficjalną dokumentację połączeń i tożsamości w callbacku.

4. Włącz wtyczkę

Zbuduj obszar roboczy (npm run build) i dodaj wpis do swojego pliku wtyczek OHarness użytkownika, zwykle ~/.oharness/plugins.json (lub $OHARNESS_HOME/plugins.json). Podmień ścieżkę modułu, identyfikator użytkownika i identyfikator konta; nie kopiuj symboli zastępczych bez zmian.

{
  "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 pozostawia OHarness w działaniu, jeśli ten opcjonalny konektor nie wystartuje; błąd jest widoczny w /plugins i na liście wtyczek w Web. Ustaw true tylko wtedy, gdy start ma się nie powieść bez konektora. Konfiguracja projektu nie może włączać wtyczek wykonywalnych ani podmieniać ich zaufanej konfiguracji kont.

Przy osadzaniu użyj tej samej implementacji bezpośrednio:

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

Semantyka wykonania

Przy starcie sprawdzane jest, czy każde skonfigurowane konto należy do skonfigurowanego użytkownika, ma skonfigurowany zestaw narzędzi i jest aktywne oraz niewyłączone.
Pobierane są tylko nazwane slugi narzędzi; maksymalnie 40 narzędzi w 20 zestawach.
Zwrócony slug i zestaw narzędzi muszą zgadzać się z listą dozwolonych. latest jest przy starcie rozwiązywane do konkretnej wersji z datą, używanej potem przy wykonywaniu. Skonfigurowana wersja z datą musi dokładnie odpowiadać wersji zwróconego schematu.
Narzędzia są rejestrowane jako composio__SLUG. Nazwy dłuższe niż 64 znaki są skracane ze stałym sufiksem z hasha. Dokładne nazwy widać w ToolRegistry.
Wywołania przechodzą przez zwykły silnik uprawnień OHarness. Wszystkie narzędzia Composio mają readOnly: false i sessionLocal: false, nawet zdalne operacje odczytu. Zatwierdzenie jest pomijane tylko wtedy, gdy pozwala na to twoja zwykła, jawna polityka uprawnień.
Przed każdym wykonaniem własność konta, jego status i zestaw narzędzi są sprawdzane ponownie. Koperta POST używa zaufanego użytkownika i konta oraz przypiętej wersji; parametry modelu są zagnieżdżone w arguments i nie mogą zastąpić tych pól.
Dane z udanego wywołania są zamieniane na ToolResult i trafiają do zwykłego przepływu agenta oraz audytu wykonania. Błędy HTTP i API stają się błędami narzędzia.

Wejście narzędzia musi być obiektem. Szczegółową walidację schematu argumentów przeprowadza Composio; zwrócony JSON Schema trafia do modelu. Obsługiwane są tylko jawne implementacje narzędzi, a nie wykonywanie przez proxy, własne nadpisania autoryzacji, wykonywanie na podstawie języka naturalnego czy dowolne zdalne URL-e. Ten adapter nie czyta ani nie wysyła żadnych plików lokalnych.

Żadne wywołanie HTTP nie jest automatycznie ponawiane. Anulowany lub nieudany POST mógł już wykonać zdalną akcję: przed ponowieniem sprawdź usługę zewnętrzną lub log Composio. Limit czasu na żądanie wynosi domyślnie 30 sekund i można go ustawić w zakresie od 100 ms do 120 sekund. Odpowiedzi są ograniczone do 2 MiB. Surowe treści błędów i klucze API nie trafiają do logów; dane z udanych wywołań pozostają wrażliwymi danymi aplikacji i zgodnie z założeniem są widoczne dla agenta.

Pierwsze żądania dotyczące kont i metadanych następują, gdy wtyczka jest włączana przy starcie; inicjalizacja nie tworzy nowego konta ani nie wykonuje żadnej akcji z listy dozwolonych.

Wykorzystany oficjalny kontrakt API

Adapter korzysta z udokumentowanych tras /api/v3 na backend.composio.dev. Sprawdzono je z oficjalną dokumentacją 2026-09-02; testy kontraktu HTTP nie dowodzą autoryzacji na prawdziwym koncie ani dostępności dostawcy.

← Wtyczki Konektory w chmurze →