OHarness
Télécharger

Plugin Composio

connector-composio est un RuntimePlugin OHarness ordinaire. Il utilise l'API REST officielle de Composio pour l'inspection des comptes, la découverte des schémas et l'exécution des outils. Il n'introduit ni MCP, ni une autre boucle d'agent, ni un second hôte de plugins, ni une dépendance à un SDK. createConnectorPlugin reste l'assistant d'adaptation indépendant du fournisseur.

Périmètre et vérification

  • Implémenté : listes d'autorisation d'outils explicites, liaison compte/utilisateur, conversion des schémas, épinglage de version, annulation, limites de taille des réponses et contrôles de permission OHarness.
  • Implémenté : création explicite, par un humain, de liens d'authentification hébergés, et état des comptes.
  • Non implémenté : Pipedream, webhooks, ACL pour comptes partagés, vérification automatique de l'identité au callback OAuth dans OHarness Cloud, installation de plugins à distance, automatisation de l'envoi/du téléchargement de fichiers ou rechargement à chaud du runtime.
  • Les tests utilisent des réponses HTTP simulées et ne nécessitent aucun identifiant. Un test de fumée sur un compte réel doit être effectué séparément, avec vos propres identifiants et votre consentement.

Composio recommande les Sessions pour les nouvelles intégrations d'agents et qualifie l'exécution directe d'ancienne méthode. Ce premier adaptateur utilise volontairement les endpoints directs, toujours documentés, pour garder le registre d'outils OHarness existant et les permissions par outil aux commandes. Seuls les outils explicitement sélectionnés sont exposés, plutôt qu'un routeur générique capable d'invoquer une action arbitraire. Consultez le guide officiel d'exécution directe.

Cet adaptateur direct est destiné à un usage de développement ou auto-hébergé explicitement configuré. Dans le produit hébergé, la clé Composio de la plateforme appartient à Cloud, pas à chaque client. Utilisez le connecteur Cloud pour le produit hébergé : il fournit les cartes d'autorisation, la liaison d'utilisateur vérifiée par le serveur et la poursuite des tâches.

1. Définir la clé API du projet

Définissez COMPOSIO_API_KEY dans l'environnement du processus qui exécute OHarness. Ne la mettez ni dans votre dépôt, ni dans des messages de chat, ni dans le JSON du plugin. La configuration peut désigner une autre variable d'environnement via apiKeyEnv.

Le transport n'envoie cette clé qu'à https://backend.composio.dev, refuse les redirections HTTP et n'accepte pas d'origine d'API configurable. Tous les appels distants sont des requêtes explicites du client ; construire ou importer le plugin n'effectue aucun appel.

2. Voir ce qui est déjà connecté

Chaque entrée de toolkit dans la configuration a besoin d'un connectedAccountId, et la première question est de savoir si vous en avez déjà un :

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

En lecture seule, limité à cet utilisateur et paginé — passez --toolkit SLUG pour filtrer, --limit N (1-100, 50 par défaut) pour dimensionner la page, et --cursor avec le cursor renvoyé par un appel précédent. La commande affiche id, toolkit, status et disabled pour chaque compte, et rien d'autre : les lignes renvoyées en amont contiennent des champs d'identifiants et d'état, et cette commande les supprime comme le fait l'inspection des comptes.

Un compte listé sous un autre utilisateur est refusé plutôt que masqué : une réponse qui mélange des utilisateurs n'est pas digne de confiance, même pour les lignes qui correspondaient.

3. Connecter un compte

Si la liste est vide, ou si le toolkit dont vous avez besoin n'y figure pas, créez une configuration d'authentification pour l'application dans Composio, puis demandez explicitement un Connect Link hébergé depuis le dépôt :

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

La commande effectue un POST distant et affiche redirectUrl, connectedAccountId et une éventuelle date d'expiration. Ouvrez vous-même cette URL et donnez votre consentement. Traitez-la comme un lien d'autorisation privé : ne la partagez pas avec un autre utilisateur. La commande n'ouvre pas de navigateur, n'approuve pas l'accès, n'enregistre pas de configuration et n'expose pas d'outil de création de lien à l'agent.

Inspectez la connexion obtenue avec une requête en lecture seule :

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

Continuez lorsque l'état est ACTIVE, que le toolkit est le bon et que disabled vaut false. Utilisez le même identifiant d'utilisateur pour la liaison et l'exécution. L'adaptateur rejette volontairement un compte appartenant à un autre utilisateur, même si la clé API du projet pourrait y accéder. L'inspection des comptes ne renvoie jamais de champs d'identifiants ou d'état.

Pour un produit hébergé multi-utilisateur, déduisez userId de l'état authentifié de l'application et créez des instances de Harness isolées comme il convient. Ne l'acceptez pas comme entrée du modèle. La vérification d'identité facultative de Composio au callback nécessite un vérificateur HTTPS authentifié dans votre application ; cet adaptateur local n'implémente pas ce serveur. Consultez la documentation officielle sur les connexions et la vérification d'identité au callback.

4. Activer le plugin

Compilez l'espace de travail (npm run build) et ajoutez une entrée à votre fichier de plugins OHarness utilisateur, normalement ~/.oharness/plugins.json (ou $OHARNESS_HOME/plugins.json). Remplacez le chemin du module, l'identifiant d'utilisateur et l'identifiant de compte ; ne copiez pas les valeurs fictives telles quelles.

{
  "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 laisse OHarness utilisable si ce connecteur facultatif ne peut pas démarrer ; l'échec est visible dans /plugins et dans la liste des plugins du Web. Ne le passez à true que si le démarrage doit échouer sans le connecteur. La configuration de projet ne peut pas activer de plugins exécutables ni remplacer leur configuration de compte de confiance.

Pour l'intégration dans une application, utilisez directement la même implémentation :

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

Sémantique d'exécution

  1. Au démarrage, chaque compte configuré est vérifié : il doit appartenir à l'utilisateur configuré, posséder le toolkit configuré et être actif/non désactivé.
  2. Seuls les slugs d'outils nommés sont récupérés ; au maximum 40 outils répartis sur 20 toolkits.
  3. Le slug/toolkit renvoyé doit correspondre à la liste d'autorisation. latest est résolu au démarrage en une version datée concrète, réutilisée pour l'exécution. Une version datée configurée doit correspondre exactement à la version du schéma renvoyé.
  4. Les outils sont enregistrés sous la forme composio__SLUG. Les noms de plus de 64 caractères sont raccourcis avec un suffixe de hash stable. Les noms exacts apparaissent dans ToolRegistry.
  5. Les appels passent par le moteur de permissions habituel d'OHarness. Tous les outils Composio ont readOnly: false et sessionLocal: false, même les opérations de lecture distantes. L'approbation n'est sautée que lorsque votre politique de permission explicite habituelle l'autorise.
  6. Avant chaque exécution, la propriété, l'état et le toolkit du compte sont vérifiés à nouveau. L'enveloppe POST utilise l'utilisateur/compte de confiance et la version épinglée ; les paramètres du modèle sont imbriqués sous arguments et ne peuvent pas remplacer ces champs.
  7. Les données obtenues sont converties en ToolResult et entrent dans le flux habituel de l'agent et dans l'audit d'exécution. Les échecs HTTP/API deviennent des erreurs d'outil.

L'entrée d'un outil doit être un objet. La validation détaillée du schéma des arguments est effectuée par Composio ; le JSON Schema renvoyé est fourni au modèle. Seules les implémentations d'outils explicites sont prises en charge, pas l'exécution par proxy, les surcharges d'authentification personnalisées, l'exécution en langage naturel ni les URL distantes arbitraires. Cet adaptateur ne lit ni n'envoie aucun fichier local.

Aucun appel HTTP n'est relancé automatiquement. Un POST annulé ou en échec peut avoir déjà effectué l'action distante : vérifiez le service externe ou le journal Composio avant de réessayer. Le délai par requête est de 30 secondes par défaut et se configure de 100 ms à 120 secondes. Les réponses sont plafonnées à 2 Mio. Les corps d'erreur bruts et les clés API ne sont pas transmis aux journaux ; les données obtenues restent des données applicatives sensibles et sont visibles par l'agent, comme prévu.

Les premières requêtes de compte et de métadonnées ont lieu lorsque le plugin est activé au démarrage ; l'initialisation ne crée pas de nouveau compte et n'exécute aucune action de la liste d'autorisation.

Contrat d'API officiel utilisé

L'adaptateur cible les routes /api/v3 documentées sur backend.composio.dev. Elles ont été vérifiées par rapport à la documentation officielle le 2026-09-02 ; les tests de contrat HTTP ne prouvent ni l'autorisation d'un compte réel ni la disponibilité du fournisseur.

← PluginsConnecteurs cloud →