Technical Tutorials

Construire des agents IA évolutifs est un équilibre délicat. Il vous faut l'orchestration robuste d'un framework, la faible latence du calcul edge et l'efficacité en coûts des architectures serverless. C'est là que la combinaison de Mastra et des Edge Functions Vercel brille. Mastra fournit une boîte à outils complète pour construire des applications alimentées par des LLM, tandis que le runtime Edge de Vercel garantit que vos agents s'exécutent à l'échelle mondiale avec un surcoût minimal.

Dans ce guide, nous explorerons comment construire un agent IA étatique en utilisant Mastra et le déployer en tant qu'Edge Function Vercel. Nous aborderons les défis courants, tels que la gestion de l'état dans les environnements serverless et l'optimisation des démarrages à froid.

Pourquoi Mastra + Vercel Edge ?

Mastra est un framework open source conçu spécifiquement pour la construction d'agents IA et de workflows. Il offre :

Agents : Capacités LLM encapsulées avec des outils et des mémoires.
Workflows : Processus déterministes, multi-étapes, avec une logique de branchement.
Évaluateurs : Métriques de test et d'évaluation intégrées pour la sortie IA.

Les Edge Functions Vercel s'exécutent à la périphérie, près de vos utilisateurs. Elles offrent :

Faible latence : Exécution en millisecondes dans des régions mondiales.
Efficacité en coûts : Modèle de facturation à la demande.
Support des langages : Support complet de TypeScript et JavaScript.

La combinaison de ces technologies vous permet de construire des agents IA sophistiqués qui répondent en moins de 100 ms, quel que soit l'emplacement de vos utilisateurs.

Mise en place de votre projet

D'abord, initialisez un nouveau projet Vercel avec le runtime Edge. Ensuite, installez Mastra :


npm create vercel@latest
cd your-project
npm install mastra

Créez un fichier nommé edge.ts à la racine de votre projet. Ce fichier définira le point d'entrée de votre Edge Function.

Construction d'un agent étatique avec Mastra

L'un des défis des Edge Functions est leur nature éphémère. L'état doit être géré de manière externe ou dans le contexte de la requête. Mastra simplifie cela avec sa classe Agent, qui peut gérer la mémoire et la gestion du contexte.


import { Agent } from 'mastra';
import { generateText } from 'ai';
import { openai } from '@ai-sdk/openai';

// Définissez votre agent avec des capacités de mémoire
const myAgent = new Agent({
  name: 'SupportAgent',
  description: 'Un agent qui gère les demandes de support client.',
  model: openai('gpt-4o'),
  tools: {
    // Exemple d'outil : lookup_order
    lookup_order: {
      description: 'Recherche une commande par ID',
      execute: async ({ orderId }: { orderId: string }) => {
        // Dans une application réelle, cela interrogerait une base de données
        return { status: 'shipped', trackingId: '1Z999AA10123456784' };
      },
    },
  },
});

export async function GET(request: Request) {
  const { message, userId } = await request.json();

  try {
    // Mastra gère la boucle de l'agent, l'exécution des outils et le formatage de la réponse
    const result = await myAgent.generate({
      messages: [
        { role: 'user', content: message },
      ],
      // Passez userId pour la gestion de l'état si vous utilisez les fonctionnalités de mémoire de Mastra
      metadata: { userId },
    });

    return new Response(JSON.stringify({
      text: result.text,
      usage: result.usage,
    }), {
      headers: { 'Content-Type': 'application/json' },
    });
  } catch (error) {
    return new Response(JSON.stringify({ error: error.message }), {
      status: 500,
      headers: { 'Content-Type': 'application/json' },
    });
  }
}

Gestion de l'état dans les environnements serverless

Les Edge Functions sont sans état par conception. Si votre agent a besoin de mémoire (par exemple, l'historique de la conversation), vous avez deux options :

État côté client : Envoyez l'historique complet de la conversation avec chaque requête. C'est simple, mais cela peut entraîner des charges utiles volumineuses.
Stockage externe : Utilisez une base de données adaptée au serverless comme Vercel KV, Upstash Redis, ou une instance Postgres (par exemple, Neon) pour stocker l'état de la conversation. Mastra peut s'intégrer à ceux-ci via des outils personnalisés ou des middlewares.

Pour les applications à grande échelle, l'utilisation d'un cache externe avec une durée de vie (TTL - Time-To-Live) est recommandée pour maintenir les coûts bas et la latence élevée.

Optimisation des démarrages à froid

Les démarrages à froid peuvent ajouter de la latence à votre agent IA. Voici quelques bonnes pratiques :

Taille du bundle : Gardez le bundle de votre Edge Function petit. N'importez que les composants Mastra spécifiques dont vous avez besoin.
Préchauffage : Utilisez la fonctionnalité keepAlive de Vercel ou des invocations planifiées pour maintenir votre fonction chaude pendant les heures de pointe.
Mise en cache des modèles : Si vous utilisez des modèles locaux ou des LLM plus petits, envisagez de mettre en cache les poids du modèle en mémoire (si pris en charge par votre runtime) ou d'utiliser les fournisseurs du SDK ai de Vercel qui gèrent le pooling de connexions.

Déploiement sur Vercel

Le déploiement est simple :


vercel deploy

Assurez-vous que votre vercel.json configure le runtime Edge pour votre fonction :


{
  "functions": {
    "edge.ts": {
      "runtime": "edge"
    }
  }
}

Conclusion

Le déploiement d'agents IA étatiques sur les Edge Functions Vercel avec Mastra offre une puissante combinaison de performance, d'évolutivité et d'expérience développeur. En exploitant l'orchestration d'agents de Mastra et le réseau edge mondial de Vercel, vous pouvez construire des applications IA réactives et économiques qui s'échalent sans effort. Commencez petit avec un seul agent, surveillez votre latence et vos coûts, et itérez pour construire des fonctionnalités robustes alimentées par l'IA pour vos utilisateurs.