Composio ======== Composio fournit plus de 1 000 intégrations pré-construites, appelées **toolkits**, pour les plateformes SaaS populaires. Activez un toolkit, connectez votre compte — via OAuth managé, ou en saisissant directement des identifiants (clé API, token Bearer ou authentification Basic) — puis assignez ses actions à un agent. Pas de code webhook, pas de gestion de clés API, pas de logique HTTP personnalisée. Toolkits disponibles (exemples) ------------------------------- HubSpot Créer des contacts, journaliser les appels, mettre à jour les deals Salesforce Interroger des comptes, créer des leads, mettre à jour des opportunités Google Calendar Vérifier la disponibilité, créer des événements, lister les prochains Zendesk Créer et mettre à jour des tickets, ajouter des commentaires Slack Envoyer des messages, créer des canaux, mentionner des utilisateurs Linear Créer des issues, assigner, mettre à jour le statut Notion Créer des pages, interroger des bases, mettre à jour des blocs Airtable Créer et mettre à jour des enregistrements, lister les bases Gmail Envoyer des emails, chercher dans la boîte, créer des brouillons Et 990+ autres. Parcourez le catalogue complet dans **Dashboard → Comptes → \[compte\] → Connexions → Composio**. Cycle de vie d'une connexion ---------------------------- Une intégration Composio suit ce flux : activer le toolkit → connecter votre compte → assigner les actions à un agent. PENDING ACTIVE ou : EXPIRED ERROR Étape 1, Activer un toolkit --------------------------- Activer un toolkit le rend disponible pour connexion et assignation d'actions dans votre organisation. Depuis le dashboard : **Dashboard → Comptes → \[compte\] → Connexions → Composio → Browse catalog → Enable**. Via l'API : Les endpoints `/api/composio/*` utilisent l'authentification de session (credentials du dashboard), pas la clé API v1 Bearer. Pour la gestion par programme, utilisez le dashboard. Ces exemples montrent les requêtes HTTP sous-jacentes pour référence. ``` curl -X POST https://www.manivox.ai/api/composio/toolkits/enable \ -H "Content-Type: application/json" \ -b "laravel_session=YOUR_SESSION_COOKIE" \ -H "X-XSRF-TOKEN: YOUR_XSRF_TOKEN" \ -d '{ "toolkit_slug": "hubspot", "toolkit_name": "HubSpot", "description": "CRM, créer des contacts et journaliser les résultats d'\''appels" }' ``` Étape 2, Connecter votre compte ------------------------------- La connexion authentifie votre compte SaaS auprès de Composio. Il existe deux voies de connexion ; celle qu'un toolkit utilise dépend du fait qu'il propose ou non un OAuth managé par Composio. La boîte de dialogue de connexion du dashboard le détecte automatiquement et affiche le bon formulaire. ### Toolkits avec OAuth managé Pour les toolkits qui proposent un OAuth managé (Gmail, Slack, HubSpot, Google Calendar…), Composio gère le flux OAuth et stocke les tokens pour vous. Appelez l'endpoint de connexion, puis redirigez l'utilisateur vers l'URL retournée. ``` curl -X POST https://www.manivox.ai/api/composio/toolkits/{toolkit_id}/connect \ -b "laravel_session=YOUR_SESSION_COOKIE" \ -H "X-XSRF-TOKEN: YOUR_XSRF_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "account_id": "acc_01hwz4p3...", "redirect_url": "https://yourapp.com/composio/callback" }' ``` `account_id` est **requis**, il identifie à quel compte de votre organisation la connexion appartient. `redirect_url` est optionnel. ``` { "data": { "id": "clh7v2b3e0000356k26fdmzev", "status": "PENDING", "composio_account_id": "composio_abc123" }, "redirect_url": "https://app.composio.dev/oauth/...?integrationId=..." } ``` Redirigez l'utilisateur vers `redirect_url` pour compléter le flux OAuth. Après autorisation, le statut transite vers `ACTIVE`. Pollez l'endpoint de statut de connexion pour confirmer : ``` curl https://www.manivox.ai/api/composio/accounts/{account_id}/status \ -b "laravel_session=YOUR_SESSION_COOKIE" \ -H "X-XSRF-TOKEN: YOUR_XSRF_TOKEN" ``` ### Toolkits sans OAuth managé (identifiants directs) De nombreux toolkits ne sont pas gérés via un OAuth managé. Pour ceux-là, il n'y a pas de redirection OAuth : vous saisissez directement les identifiants — une **clé API**, un **token Bearer**, ou une **authentification Basic** (nom d'utilisateur et mot de passe), selon ce que le toolkit exige. Transmettez les champs d'identifiants dans un objet `credentials` et le compte se connecte immédiatement à l'état `ACTIVE`. La boîte de dialogue de connexion affiche les noms exacts des champs attendus par chaque toolkit. ``` curl -X POST https://www.manivox.ai/api/composio/toolkits/{toolkit_id}/connect \ -b "laravel_session=YOUR_SESSION_COOKIE" \ -H "X-XSRF-TOKEN: YOUR_XSRF_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "account_id": "acc_01hwz4p3...", "credentials": { "api_key": "sk_live_..." } }' ``` La réponse revient déjà à l'état `ACTIVE` avec `redirect_url` à `null`, il n'y a donc ni étape OAuth ni polling : ``` { "data": { "id": "clh7v2b3e0000356k26fdmzev", "status": "ACTIVE", "composio_account_id": "composio_abc123" }, "redirect_url": null } ``` Étape 3, Assigner des actions à un agent ---------------------------------------- Après la connexion, choisissez quelles actions du toolkit exposer à chaque agent. Seules les actions assignées sont disponibles comme outils que le LLM de l'agent peut invoquer pendant les appels. ``` curl -X POST https://www.manivox.ai/api/composio/agents/{agent_id}/tools \ -b "laravel_session=YOUR_SESSION_COOKIE" \ -H "X-XSRF-TOKEN: YOUR_XSRF_TOKEN" \ -H "Content-Type: application/json" \ -d '{ "tools": [ { "composio_toolkit_id": "ctk_01hwz4p3...", "enabled_actions": ["HUBSPOT_CREATE_CONTACT", "HUBSPOT_LOG_ACTIVITY"] } ] }' ``` Omettez `enabled_actions` pour activer toutes les actions disponibles du toolkit. Utilisation dans les conversations ---------------------------------- Les actions Composio fonctionnent de la même manière que les Web Services : le LLM les invoque comme outils pendant l'appel. Le LLM collecte les entrées requises via la conversation, déclenche l'action, et utilise la réponse dans son prochain énoncé. Pour activer des actions Composio sur un agent : 1. Ouvrez l'éditeur de flux et double-cliquez sur le nœud Welcome (défaut pour tout l'agent) ou sur un nœud Agent (pour le limiter à ce nœud) 2. Allez dans l'onglet **Connections** → section **OAuth Connections**, puis activez le compte toolkit connecté et choisissez les actions à exposer 3. Dans le prompt système de ce nœud, décrivez quand chaque action doit être invoquée **Exemple de prompt système pour la création de ticket Zendesk :** ``` À la fin de chaque appel de support, utilise l'action « ZENDESK_CREATE_TICKET » pour journaliser le problème. Collecte l'email de l'appelant et une brève description du problème avant l'invocation. Confirme le numéro de ticket à l'appelant une fois l'action réussie. ``` L'invocation de l'action, les paramètres, la réponse et le timing sont journalisés dans `call.tool_calls` sur l'enregistrement d'appel. Déconnecter un compte --------------------- Déconnecter révoque le token d'accès Composio et supprime l'enregistrement de compte connecté. Les agents utilisant les actions de ce toolkit recevront un signal d'erreur quand le LLM tentera de les invoquer, incluez une instruction de repli dans votre prompt système pour que l'agent gère cela proprement jusqu'à la reconnexion. ``` curl -X DELETE https://www.manivox.ai/api/composio/accounts/{connected_account_id} \ -b "laravel_session=YOUR_SESSION_COOKIE" \ -H "X-XSRF-TOKEN: YOUR_XSRF_TOKEN" ``` Interrogez les connexions d'un compte par programme (`GET /v1/accounts/{id}/connections` et `/connections/{connectionId}`) — voir la [référence API](https://www.manivox.ai/docs/api/index). Désactiver un toolkit entier (et non simplement déconnecter un compte) retire aussi toutes les assignations d'outils d'agents et tous les comptes connectés pour ce toolkit. Cela ne peut pas être annulé.