Construire des agents IA qui utilisent 300+ applications avec Composio et TypeScript

La partie la plus difficile pour livrer un agent IA utile en 2026 n'est pas le modèle — c'est tout ce qui l'entoure. Flux OAuth, refresh tokens, limites de débit, signatures de webhooks, dérive de schémas sur des centaines d'APIs SaaS. Composio absorbe tout cela et donne à votre agent une surface unique et typée : 300+ outils pré-construits couvrant Gmail, Slack, GitHub, Notion, Linear, Google Calendar, Stripe, HubSpot, Salesforce et bien plus.

Dans ce tutoriel, vous allez câbler Composio dans un agent TypeScript bâti sur le Vercel AI SDK, authentifier un vrai utilisateur contre Gmail et GitHub, laisser le modèle choisir le bon outil, et déployer le tout derrière une route Next.js.

Ce que vous apprendrez

À la fin de ce tutoriel, vous serez capable de :

• Installer et configurer le SDK TypeScript Composio
• Créer des auth configs et exécuter un flux OAuth côté utilisateur
• Lister et filtrer les outils par toolkit, action ou cas d'usage
• Passer les outils Composio au Vercel AI SDK et à l'OpenAI Agents SDK
• Écouter des déclencheurs temps réel (nouvel email, nouveau ticket GitHub, message Slack)
• Emballer le tout derrière un endpoint Next.js App Router
• Appliquer les patterns de production : outils restreints, comptes par utilisateur, observabilité

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Node.js 20+ installé (node --version)
• Une bonne maîtrise de TypeScript et async/await
• Un compte Composio sur app.composio.dev (le tier gratuit suffit)
• Une clé OpenAI (ou tout modèle supporté par le Vercel AI SDK)
• Un compte Gmail de test et un compte GitHub que vous contrôlez
• Un éditeur de code — VS Code ou Cursor recommandés

Où Composio s'insère dans la stack agent

Une boucle d'agent typique ressemble à ceci :

Prompt utilisateur → LLM → appel d'outil → exécution → résultat → LLM → réponse

Sans Composio, « exécution » signifie que vous avez écrit l'intégration : danse OAuth, refresh du token, mise en forme de la requête, mapping d'erreurs. Avec Composio, « exécution » est un seul appel SDK. Le modèle choisit GMAIL_SEND_EMAIL, votre runtime d'agent transmet l'appel, Composio l'exécute sous le compte de l'utilisateur connecté, et vous récupérez un résultat structuré.

Architecture

┌──────────────────────────────────────────────┐
│  Votre service Next.js / Node                │
│  ┌────────────────────────────────────────┐  │
│  │ Vercel AI SDK / OpenAI Agents SDK      │  │
│  │   ↑   fournit les outils               │  │
│  │   │                                    │  │
│  │   SDK Composio                         │  │
│  └─────────────┬──────────────────────────┘  │
└────────────────┼─────────────────────────────┘
                 │ HTTPS
        ┌────────▼─────────┐
        │   API Composio   │
        │ - Auth configs   │
        │ - Connexions     │
        │ - Exécution      │
        │ - Déclencheurs   │
        └────────┬─────────┘
                 │
   ┌─────────────┼──────────────────┐
   ▼             ▼                  ▼
 Gmail        GitHub             Notion  ... +300

L'unité d'identité dans Composio est le compte connecté — un enregistrement par utilisateur par toolkit. Votre agent passe toujours un userId pour que Composio sache quel compte utiliser.

Étape 1 : Mise en place du projet

Créez un projet vierge et installez le SDK.

mkdir composio-agent && cd composio-agent
npm init -y
npm install composio @ai-sdk/openai ai zod dotenv
npm install -D typescript tsx @types/node
npx tsc --init --target es2022 --module nodenext --moduleResolution nodenext --esModuleInterop true --strict true

Ajoutez un fichier .env :

COMPOSIO_API_KEY=ak_xxx_from_app_composio_dev
OPENAI_API_KEY=sk-xxx

Récupérez la clé Composio sur app.composio.dev/developers.

Créez src/composio.ts :

import "dotenv/config";
import { Composio } from "composio";
import { VercelProvider } from "composio/providers/vercel";
 
export const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY!,
  provider: new VercelProvider(),
});

Le provider indique à Composio comment formater les schémas d'outils pour votre runtime d'agent. Composio fournit des providers pour le Vercel AI SDK, l'OpenAI Agents SDK, LangChain, LlamaIndex, CrewAI, et plus.

Étape 2 : Créer un auth config

Un auth config est l'identité de votre application auprès d'un service tiers (le client ID OAuth, les scopes, l'URI de redirection). Vous le créez généralement une fois par toolkit dans le dashboard Composio, mais vous pouvez aussi le scripter.

Ouvrez app.composio.dev, choisissez le toolkit Gmail, cliquez sur Setup, et sélectionnez Use Composio's OAuth app pour le développement. Composio génère un auth config ID du type ac_xxx. Sauvegardez-le.

Faites pareil pour GitHub. Vous devriez maintenant avoir :

GMAIL_AUTH_CONFIG_ID=ac_gmail_xxx
GITHUB_AUTH_CONFIG_ID=ac_github_xxx

Étape 3 : Connecter un compte utilisateur

Connecter un compte signifie faire passer l'utilisateur par OAuth. Composio vous donne une URL de redirection.

Créez src/connect.ts :

import { composio } from "./composio.js";
 
const USER_ID = "user_demo_123"; // votre ID interne d'utilisateur
 
async function connectGmail() {
  const connection = await composio.connectedAccounts.initiate(
    USER_ID,
    process.env.GMAIL_AUTH_CONFIG_ID!,
  );
 
  console.log("Ouvrez cette URL dans un navigateur :");
  console.log(connection.redirectUrl);
 
  const account = await connection.waitForConnection(120_000);
  console.log("Connecté :", account.id, account.status);
}
 
connectGmail().catch(console.error);

Lancez-le :

npx tsx src/connect.ts

Ouvrez l'URL affichée, accordez l'accès, et le script se résout avec une connexion status: "ACTIVE". Composio détient maintenant le refresh token pour user_demo_123 contre le toolkit Gmail.

Répétez pour GitHub en changeant l'auth config ID.

Étape 4 : Découvrir les bons outils

Composio expose plus de 9 000 actions. Toutes les passer au modèle déchirerait votre fenêtre de contexte. Filtrez agressivement.

import { composio } from "./composio.js";
 
const tools = await composio.tools.get("user_demo_123", {
  toolkits: ["gmail", "github"],
  limit: 20,
});
 
for (const tool of Object.values(tools)) {
  console.log(tool.name);
}

Vous pouvez aussi filtrer par cas d'usage en langage naturel, ce qui utilise la recherche de Composio pour faire remonter les actions les plus pertinentes :

const tools = await composio.tools.get("user_demo_123", {
  useCase: "répondre au dernier email non lu et créer un ticket GitHub de suivi",
  limit: 8,
});

Ou par noms d'actions exacts quand vous savez ce que vous voulez :

const tools = await composio.tools.get("user_demo_123", {
  tools: [
    "GMAIL_FETCH_EMAILS",
    "GMAIL_SEND_EMAIL",
    "GITHUB_CREATE_AN_ISSUE",
  ],
});

Règle pratique : restez sous 20 outils par appel d'agent. Au-delà, précision et latence se dégradent toutes les deux.

Étape 5 : Lancer un agent avec le Vercel AI SDK

Composez maintenant tout cela dans un véritable agent. Créez src/agent.ts :

import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";
import { composio } from "./composio.js";
 
const USER_ID = "user_demo_123";
 
async function run(prompt: string) {
  const tools = await composio.tools.get(USER_ID, {
    toolkits: ["gmail", "github"],
    limit: 12,
  });
 
  const result = await generateText({
    model: openai("gpt-4.1"),
    tools,
    stopWhen: stepCountIs(8),
    system: [
      "Tu es un assistant qui aide l'utilisateur à gérer son email et GitHub.",
      "Confirme toujours les actions destructrices en langage clair avant de les exécuter.",
      "Quand tu envoies un email, utilise un ton court et professionnel.",
    ].join("\n"),
    prompt,
  });
 
  console.log("\n--- ASSISTANT ---\n");
  console.log(result.text);
  console.log("\n--- ÉTAPES ---\n");
  for (const step of result.steps) {
    for (const call of step.toolCalls ?? []) {
      console.log(`  ↳ ${call.toolName}`);
    }
  }
}
 
run("Trouve les trois emails non lus les plus récents dans ma boîte et résume-les.").catch(
  console.error,
);

Lancez-le :

npx tsx src/agent.ts

Ce que vous devriez voir : le modèle appelle GMAIL_FETCH_EMAILS, reçoit un résultat structuré, et produit un résumé en langage naturel. Notez que vous n'avez écrit aucun code Gmail — pas de client API, pas de gestion d'auth, pas de logique de pagination.

Exemple multi-étapes

Changez le prompt :

run(
  "Trouve l'email client le plus récent qui parle d'un bug, puis ouvre un ticket GitHub " +
  "dans le dépôt 'noqta/example-app' avec le sujet comme titre et le corps de l'email " +
  "cité dans la description.",
).catch(console.error);

L'agent va chaîner GMAIL_FETCH_EMAILS → GITHUB_CREATE_AN_ISSUE en deux étapes et retourner l'URL du ticket créé.

Étape 6 : Mêmes outils, OpenAI Agents SDK

Si vous préférez l'OpenAI Agents SDK, changez juste de provider — votre logique métier reste identique.

npm install @openai/agents

import { Agent, run } from "@openai/agents";
import { Composio } from "composio";
import { OpenAIAgentsProvider } from "composio/providers/openai-agents";
 
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY!,
  provider: new OpenAIAgentsProvider(),
});
 
const tools = await composio.tools.get("user_demo_123", {
  toolkits: ["linear", "slack"],
  limit: 10,
});
 
const agent = new Agent({
  name: "ops-assistant",
  instructions: "Trier les messages Slack entrants et créer des tickets Linear quand pertinent.",
  tools,
});
 
const result = await run(agent, "Vérifie les 10 derniers messages du canal #support et crée des tickets Linear pour tout ce qui ressemble à un bug.");
console.log(result.finalOutput);

Le provider Composio retourne les outils dans le format attendu par le runtime. Vous ne réimplémentez jamais les schémas.

Étape 7 : Déclencheurs temps réel

Sonder les emails, c'est bien. Y réagir en temps réel, c'est mieux. Les déclencheurs Composio transforment les événements tiers en webhooks auxquels votre agent peut s'abonner.

Activez un déclencheur pour un utilisateur :

const trigger = await composio.triggers.enable("user_demo_123", {
  triggerName: "GMAIL_NEW_GMAIL_MESSAGE",
  config: { labelIds: ["INBOX"], userId: "me" },
});
 
console.log("Déclencheur actif :", trigger.id);

Pointez maintenant votre projet Composio vers une URL de webhook (Settings → Webhooks). Chaque nouvel email POST un JSON sur cette URL. Un handler minimal dans un Route Handler Next.js :

// app/api/composio/webhook/route.ts
import { NextResponse } from "next/server";
import { composio } from "@/lib/composio";
 
export async function POST(req: Request) {
  const event = await req.json();
 
  if (event.triggerName !== "GMAIL_NEW_GMAIL_MESSAGE") {
    return NextResponse.json({ ok: true });
  }
 
  const userId = event.connectedAccount.userId;
  const tools = await composio.tools.get(userId, {
    toolkits: ["gmail", "linear"],
    limit: 6,
  });
 
  // ... appelez votre agent ici avec le payload de l'événement en entrée ...
 
  return NextResponse.json({ ok: true });
}

Couplez ceci avec le Vercel AI SDK et vous obtenez un agent de tri de boîte mail entièrement piloté par événements, qui ne se réveille que quand il y a du travail.

Étape 8 : Livraison derrière une route Next.js

Rassemblez les morceaux dans un seul endpoint App Router.

// app/api/agent/route.ts
import { generateText, stepCountIs } from "ai";
import { openai } from "@ai-sdk/openai";
import { Composio } from "composio";
import { VercelProvider } from "composio/providers/vercel";
import { NextResponse } from "next/server";
 
const composio = new Composio({
  apiKey: process.env.COMPOSIO_API_KEY!,
  provider: new VercelProvider(),
});
 
export async function POST(req: Request) {
  const { prompt, userId } = await req.json();
 
  const tools = await composio.tools.get(userId, {
    toolkits: ["gmail", "github", "linear"],
    limit: 15,
  });
 
  const result = await generateText({
    model: openai("gpt-4.1-mini"),
    tools,
    stopWhen: stepCountIs(6),
    system: "Tu es le copilote ops de l'utilisateur. Sois concis. N'envoie jamais d'email sans confirmation explicite.",
    prompt,
  });
 
  return NextResponse.json({
    text: result.text,
    steps: result.steps.length,
    usage: result.usage,
  });
}

La route accepte un userId pour que chaque requête s'exécute contre le bon compte connecté Composio — le multi-tenant est intégré dès le départ.

Patterns de production

Un petit guide de terrain pour aller au-delà de la démo.

Restreignez les outils par intention, pas par toolkit

Charger toutes les actions Gmail pour un agent « résume ma boîte » gaspille des tokens. Construisez un petit registre intention → outils :

const INTENT_TOOLS: Record<string, string[]> = {
  triage: ["GMAIL_FETCH_EMAILS", "GMAIL_REPLY_TO_THREAD", "LINEAR_CREATE_ISSUE"],
  release: ["GITHUB_LIST_PULL_REQUESTS", "SLACK_SEND_MESSAGE", "NOTION_CREATE_PAGE"],
};

Confirmez les actions destructrices

Envoyer un email, supprimer un ticket, débiter une carte — emballez-les dans une étape de confirmation. Soit demandez au modèle de confirmer, soit interposez une UI d'approbation avant de relayer l'appel d'outil.

Mettez en cache les listes d'outils

composio.tools.get tape l'API Composio. Mettez en cache le résultat par utilisateur/toolkit pendant quelques minutes — la liste change rarement, et la latence du prompt baisse nettement.

Observabilité

Loguez chaque entrée toolCalls retournée par generateText. Couplez avec Langfuse ou PostHog pour répondre à « quel outil a le plus échoué la semaine dernière ? » sans deviner.

Budgets

Composio facture par exécution. Plafonnez votre agent avec stepCountIs(n) et refusez les prompts qui demandent des balayages illimités (« lis tous mes emails depuis 2019 »).

Tester votre implémentation

1. Lancez npx tsx src/connect.ts et confirmez que Gmail retourne status: "ACTIVE".
2. Lancez npx tsx src/agent.ts avec le prompt de résumé d'inbox. Vous devriez voir au moins un appel GMAIL_FETCH_EMAILS dans les étapes.
3. Changez le prompt pour l'exemple multi-étapes Gmail vers GitHub et confirmez la création du ticket.
4. Démarrez le serveur dev Next.js, faites un POST sur /api/agent avec un corps JSON, et confirmez la réponse.
5. Activez un déclencheur, envoyez-vous un email de test, et confirmez que votre webhook se déclenche.

Dépannage

Connection not found lors de l'appel d'outils. L'utilisateur n'a pas terminé le flux OAuth, ou vous passez un userId différent de celui utilisé dans initiate. Composio est strict sur l'identité — gardez un ID canonique unique par utilisateur.

Le modèle choisit le mauvais outil. Resserrez votre filtre (moins d'outils par appel) ou affinez le prompt système. Au-delà de 20 outils, la précision chute fortement.

Limites de débit de l'API sous-jacente. Composio remonte l'erreur du tiers telle quelle. Attrapez-la dans votre runtime d'agent et soit faites un back-off, soit remontez-la à l'utilisateur.

Échecs de signature webhook. Vérifiez que le secret dans Composio Settings correspond à celui que votre handler vérifie, et que votre endpoint est joignable depuis l'Internet public (utilisez ngrok en dev).

Étapes suivantes

• Ajoutez HubSpot ou Salesforce pour donner à votre agent des superpouvoirs CRM
• Combinez Composio avec le tutoriel Claude Agent SDK pour une configuration hybride
• Câblez les déclencheurs Composio dans les fonctions durables Inngest pour des workflows réessayables
• Déployez Langfuse pour tracer chaque appel d'outil de bout en bout
• Remplacez les apps OAuth partagées par vos propres clients de marque avant de livrer à de vrais utilisateurs

Conclusion

Composio fait s'effondrer les mois de plomberie qui séparent un agent de démo d'un agent utile. Vous avez câblé l'authentification, choisi les outils intelligemment, les avez exécutés à la fois via le Vercel AI SDK et l'OpenAI Agents SDK, réagi à des événements temps réel, et livré le tout derrière une route Next.js — sans écrire la moindre intégration à la main.

Votre agent parle maintenant aux applications dans lesquelles vos utilisateurs vivent réellement. C'est ça, le déclic.