Créer un agent IA durable avec Vercel eve : guide TypeScript complet

La plupart des frameworks d'agents vous demandent de tout câbler dans le code : enregistrer les outils dans un tableau, configurer un runtime, brancher une file d'attente pour le travail en arrière-plan, puis ajouter l'observabilité après coup. eve, le framework d'agents open source annoncé par Vercel le 17 juin 2026, adopte l'approche inverse. Il est orienté système de fichiers : vous décrivez un agent avec des fichiers à des emplacements conventionnels, et eve les découvre, compile un manifeste et sert un backend durable qui s'exécute sur Vercel Functions.

Si vous avez déjà créé une application Next.js, le modèle mental vous semblera familier — eve a été qualifié de « Next.js pour les agents ». Un fichier dans tools/ devient un outil appelable. Un fichier dans schedules/ devient une tâche cron. Un fichier dans channels/ devient un point d'entrée Slack ou HTTP. Il n'y a presque aucun code d'enregistrement supplémentaire.

Dans ce tutoriel, vous allez créer de A à Z un agent assistant de recherche petit mais complet, puis y ajouter des outils, une compétence, la durabilité, un sous-agent et une planification. À la fin, vous comprendrez toute la forme d'un projet eve et serez prêt à déployer.

Prérequis

Avant de commencer, assurez-vous d'avoir :

• Node.js 20+ installé
• pnpm (ou npm) disponible dans votre PATH
• De l'aisance avec TypeScript et async/await
• Un compte Vercel gratuit (nécessaire uniquement pour l'étape de déploiement)
• Un éditeur de code (VS Code recommandé)

Vous n'avez besoin d'aucune clé API de fournisseur de modèles pour suivre le tutoriel en local avec le squelette généré. Sur Vercel, les chaînes de modèles sont résolues via AI Gateway en utilisant OIDC, vous ne gérez donc jamais directement les clés des fournisseurs.

Ce que vous allez créer

Un agent assistant de recherche capable de :

1. Répondre à des questions avec un outil web_search typé et un outil save_note.
2. Charger une compétence « rapport de recherche » en plusieurs étapes uniquement lorsqu'une tâche approfondie l'exige.
3. Fonctionner comme une session durable qui survit aux démarrages à froid et aux redéploiements.
4. Déléguer des sous-tâches ciblées à un sous-agent.
5. Publier un récapitulatif hebdomadaire selon une planification.

Nous le construirons de façon incrémentale pour que chaque concept tienne de lui-même.

Étape 1 : générer le projet

Le chemin le plus rapide est l'interface en ligne de commande (CLI) d'eve. Elle crée le dossier, installe les dépendances, initialise Git et lance le serveur de développement :

npx eve@latest init research-agent

Une fois terminé, arrêtez le serveur de développement (pour pouvoir éditer les fichiers proprement) et ouvrez le projet :

cd research-agent

Vous verrez un dossier agent/ au cœur du projet. Tout ce qui définit votre agent vit sous agent/. Voici la structure qu'eve découvre automatiquement :

research-agent/
├─ agent/
│  ├─ agent.ts          # configuration runtime (modèle, options)
│  ├─ instructions.md   # le prompt système permanent
│  ├─ tools/            # un outil typé par fichier
│  ├─ skills/           # procédures chargées à la demande
│  ├─ subagents/        # agents enfants pour la délégation
│  ├─ channels/         # points d'entrée (HTTP, Slack, ...)
│  ├─ schedules/        # tâches cron
│  └─ sandbox/          # environnement de calcul isolé
├─ package.json
└─ README.md

Pour ajouter eve à une application existante à la place, exécutez npx eve@latest init . dans ce projet, ou installez les paquets manuellement :

pnpm add eve ai zod

Étape 2 : définir l'agent

Un agent minimal, ce sont seulement deux fichiers. D'abord, le prompt système dans agent/instructions.md. C'est le contexte permanent — gardez-le court et comportemental :

Vous êtes un assistant de recherche concentré.
 
- Utilisez les outils disponibles lorsqu'ils aident à répondre à une question.
- Pour une rédaction approfondie, chargez la compétence de rapport de recherche.
- Citez toujours la source de chaque fait. En cas de doute, dites-le.

Ensuite, la configuration runtime dans agent/agent.ts. Le réglage le plus important est le modèle :

import { defineAgent } from 'eve';
 
export default defineAgent({
  model: 'anthropic/claude-opus-4.8',
});

Cette chaîne de modèle est résolue via AI Gateway, donc changer de fournisseur plus tard est une modification d'une seule ligne — par exemple openai/gpt-5.4-mini pour une option par défaut moins chère et plus rapide. AI Gateway gère aussi les bascules entre fournisseurs, ce qui maintient votre agent réactif quand un fournisseur connaît une mauvaise journée.

Lancez le serveur de développement pour confirmer que tout compile :

pnpm dev

Étape 3 : ajouter votre premier outil

Les outils sont des actions typées que le modèle peut appeler pendant un tour (turn). La règle est simple : chaque fichier dans agent/tools/ est un outil, et le nom du fichier devient le nom de l'outil vu par le modèle. Aucun registre central.

Créez agent/tools/web_search.ts. Le modèle le verra comme un outil nommé web_search :

import { defineTool } from 'eve/tools';
import { z } from 'zod';
 
export default defineTool({
  description: "Rechercher sur le web des informations récentes sur un sujet.",
  inputSchema: z.object({
    query: z.string().min(1).describe('La requête de recherche'),
    limit: z.number().int().min(1).max(10).default(5),
  }),
  async execute({ query, limit }) {
    // Remplacez ceci par un vrai fournisseur de recherche en production.
    const results = Array.from({ length: limit }, (_, i) => ({
      title: `Résultat ${i + 1} pour "${query}"`,
      url: `https://example.com/${encodeURIComponent(query)}/${i + 1}`,
    }));
    return { query, results };
  },
});

Remarquez quelques points :

• Le inputSchema est un schéma Zod. eve l'utilise pour valider les arguments du modèle et pour générer le schéma JSON que le modèle voit, donc les descriptions de chaque champ guident le modèle vers des appels corrects.
• execute reçoit l'entrée validée comme premier argument. Ce que vous renvoyez est sérialisé et renvoyé au modèle comme résultat de l'outil.
• Il n'y a pas de champ name — le nom de fichier web_search.ts est le nom. C'est pourquoi eve privilégie les noms de fichiers en snake_case.

Ajoutez un second outil pour que l'agent puisse conserver ses trouvailles. Créez agent/tools/save_note.ts :

import { defineTool } from 'eve/tools';
import { z } from 'zod';
 
export default defineTool({
  description: 'Enregistrer une courte note de recherche pour référence ultérieure.',
  inputSchema: z.object({
    title: z.string(),
    body: z.string(),
  }),
  async execute({ title, body }, ctx) {
    // Le second argument est le contexte de l'outil. Il expose la sandbox,
    // la journalisation et les métadonnées de session. Ici, on écrit dans la sandbox.
    await ctx.sandbox.writeFile(
      `notes/${title.replace(/\s+/g, '-').toLowerCase()}.md`,
      `# ${title}\n\n${body}\n`,
    );
    return { saved: true, title };
  },
});

Le second paramètre, ctx, est le contexte de l'outil. Il vous donne la sandbox de l'agent — un système de fichiers isolé de style bash que chaque agent eve reçoit — ainsi que la journalisation et les métadonnées de session. Les outils du framework comme bash, read_file et write_file ciblent cette même sandbox, donc vos outils écrits et ceux intégrés partagent un seul environnement.

Étape 4 : dialoguer avec votre agent

eve expose des routes HTTP pour démarrer et diffuser des sessions durables. Démarrez une session avec un POST :

curl -X POST http://127.0.0.1:3000/eve/v1/session \
  -H 'content-type: application/json' \
  -d '{"message":"Qu'\''est-ce que Vercel eve et pourquoi est-ce important ?"}'

Le corps de la réponse contient un continuationToken, et la réponse inclut un en-tête x-eve-session-id. Utilisez cet identifiant de session pour vous attacher au flux en direct, qui émet des événements de cycle de vie au format NDJSON pendant que l'agent réfléchit, appelle des outils et produit sa sortie :

curl http://127.0.0.1:3000/eve/v1/session/<sessionId>/stream

Chaque message utilisateur ou événement externe crée un tour (turn). Pendant un tour, l'agent peut appeler des outils, charger des compétences, lire et écrire des fichiers de la sandbox, déléguer à des sous-agents et renvoyer des événements en flux. Comme l'identifiant de session est durable, vous pouvez vous reconnecter au même flux après une déconnexion et reprendre là où vous vous étiez arrêté.

Étape 5 : comprendre la durabilité

C'est la fonctionnalité phare d'eve, et son activation ne vous coûte rien. Les sessions s'exécutent au-dessus de Vercel Workflows, qui persistent la progression sous forme de journal d'événements et le rejouent de façon déterministe pour reconstruire l'état. Résultat concret :

• Une session survit aux démarrages à froid — si la fonction s'arrête entre deux messages, le message suivant rejoue le journal et continue.
• Une session survit aux redéploiements — vous pouvez livrer du nouveau code pendant que des agents de longue durée sont au milieu d'une tâche.
• Une session survit aux longues pauses — un agent peut attendre des heures une approbation humaine ou un résultat d'outil lent sans maintenir un processus ouvert.

Sur Vercel, l'agent compilé s'exécute depuis Vercel Functions, et comme les tours sont longs et diffusés de manière incrémentale, eve bénéficie de Fluid Compute, activé par défaut pour les nouveaux projets. Vous écrivez des fonctions d'outils async ordinaires ; le runtime gère la durabilité.

Étape 6 : ajouter une compétence pour les tâches approfondies

Les outils sont de petites actions typées. Les compétences sont des procédures plus larges ou du matériel de référence que le modèle charge à la demande — des workflows en plusieurs étapes ou des connaissances métier qui alourdiraient le prompt permanent si vous les colliez dans instructions.md.

Créez agent/skills/research-report.md :

---
name: research-report
description: Produire un rapport de recherche structuré et sourcé sur un sujet.
---
 
# Procédure de rapport de recherche
 
Suivez ces étapes lorsque l'utilisateur demande un rapport approfondi :
 
1. Appelez `web_search` deux ou trois fois sous différents angles du sujet.
2. Regroupez les trouvailles en 3 à 5 thèmes.
3. Pour chaque thème, rédigez un court paragraphe et citez les URL sources.
4. Appelez `save_note` avec le rapport final pour que l'utilisateur le récupère.
5. Terminez par un résumé exécutif d'un paragraphe en haut.

Comme la compétence est séparée, le modèle ne la tire dans le contexte que lorsqu'un tour en a réellement besoin — gardant le prompt par défaut léger et l'agent rapide pour les questions simples. Vous installez des compétences communautaires dans agent/skills/ avec la CLI de compétences d'eve, mais écrire les vôtres revient simplement à déposer un fichier Markdown ici.

Étape 7 : déléguer avec un sous-agent

Parfois, un tour a besoin d'un travail ciblé réalisé en isolation — rechercher une sous-question avec un jeu d'outils plus restreint, ou exécuter quelque chose en parallèle sans polluer la conversation principale. C'est un sous-agent : un agent enfant avec son propre historique de conversation et son propre état, vierges.

eve propose deux types. L'outil intégré agent délègue à une copie de l'agent courant. Pour un spécialiste, déclarez un sous-agent sous agent/subagents/. Créez agent/subagents/fact-checker/agent.ts :

import { defineAgent } from 'eve';
 
export default defineAgent({
  model: 'anthropic/claude-opus-4.8',
});

Donnez-lui ses instructions plus restreintes dans agent/subagents/fact-checker/instructions.md :

Vous êtes un vérificateur de faits. Étant donné une affirmation et ses sources,
vérifiez si les sources soutiennent réellement l'affirmation. Répondez par :
CONFIRMÉ, RÉFUTÉ ou INCERTAIN, suivi d'une phrase de justification. Ne spéculez pas.

L'agent principal peut désormais déléguer une sous-tâche de vérification à fact-checker, qui s'exécute comme un agent distinct. Contrairement à une compétence — qui ajoute des instructions à l'agent en cours d'exécution — un sous-agent possède sa propre identité, son historique et son jeu d'outils. Utilisez les sous-agents pour paralléliser le travail, isoler une sous-tâche risquée ou confier à un spécialiste une mission étroitement définie.

Étape 8 : exécuter du travail selon une planification

Les agents ne font pas que réagir aux messages. Une planification est une expression cron plus un gestionnaire ; sur Vercel, elle se déploie comme une tâche Vercel Cron. Créez agent/schedules/weekly-recap.ts :

import { defineSchedule } from 'eve/schedules';
 
// S'exécute chaque lundi à 09:00 UTC.
export default defineSchedule({
  cron: '0 9 * * 1',
  async run(ctx) {
    await ctx.startSession({
      message:
        'Résume les notes de recherche enregistrées ces 7 derniers jours et publie un récapitulatif.',
    });
  },
});

Le gestionnaire démarre une nouvelle session durable, exactement comme le ferait une requête HTTP — donc tous vos outils, compétences et la durabilité s'appliquent aussi aux exécutions planifiées. C'est ainsi que vous transformez un assistant réactif en un assistant proactif qui, par exemple, envoie un digest le lundi ou rafraîchit un cache la nuit.

Étape 9 : ajouter un canal

Jusqu'ici, vous avez parlé à l'agent via HTTP brut. Les canaux sont des points d'entrée vers le même runtime d'agent — ils démarrent des sessions, acheminent les événements de plateforme vers des tours et appliquent l'authentification et le formatage propres à la plateforme. HTTP est intégré ; les canaux de plateforme sont une commande CLI chacun. Pour ajouter Slack :

npx eve@latest channels add slack

Cela écrit agent/channels/slack.ts, un petit adaptateur qui mappe les événements Slack vers des tours d'agent. Slack, Discord, Teams, Telegram, Twilio, GitHub et Linear sont fournis par défaut, et defineChannel depuis eve/channels couvre les canaux personnalisés. L'idée clé : le même agent dessert toutes les surfaces. Vous ne reconstruisez pas la logique par plateforme — chaque canal n'est qu'un fin fichier adaptateur, et les secrets des canaux vivent dans les variables d'environnement.

Étape 10 : déployer sur Vercel

eve est conçu pour s'exécuter sur Vercel sans infrastructure supplémentaire. Le chemin le plus simple est basé sur Git :

1. Poussez le projet vers un dépôt Git connecté à Vercel.
2. Vercel détecte le projet eve et construit l'agent compilé comme Vercel Functions.
3. AI Gateway résout vos chaînes de modèles via OIDC — aucune clé de fournisseur à définir.

Vous préférez la CLI ? Installez-la et déployez directement :

npm i -g vercel
vercel deploy

Une fois déployé, ouvrez Agent Runs dans le tableau de bord Vercel. Chaque projet eve obtient l'observabilité sans configuration : sessions, tours, appels d'outils, raisonnement, timing et consommation de tokens sont tous visibles. Si vous voulez aussi les traces de l'AI SDK dans un backend OpenTelemetry externe, ajoutez un fichier agent/instrumentation.ts.

Tester votre implémentation

Vérifiez chaque couche en local avant de déployer :

1. L'agent démarre : pnpm dev démarre sans erreur et affiche l'URL locale.
2. Les outils s'enregistrent : démarrez une session demandant « recherche des actualités sur le framework eve » et confirmez que le flux montre un appel à l'outil web_search.
3. La compétence se charge : demandez « un rapport de recherche complet sur X » et confirmez que la compétence research-report est tirée (visible dans les événements de cycle de vie).
4. La durabilité : tuez le serveur de développement au milieu d'une session, redémarrez-le et rattachez-vous au flux avec le même identifiant de session — la session reprend.
5. Le sous-agent : demandez à l'agent de « vérifier cette affirmation par rapport à ses sources » et confirmez la délégation à fact-checker.

Dépannage

Un outil n'est jamais appelé. Vérifiez le texte de description et des champs .describe() — le modèle s'en sert pour décider quand appeler un outil. Des descriptions vagues mènent à des outils inutilisés.

Erreurs de modèle concernant les identifiants en local. En local, vous pourriez avoir besoin d'une clé de fournisseur dans votre environnement ; sur Vercel, AI Gateway + OIDC s'en charge. Consultez le README du squelette pour la variable d'environnement locale exacte.

Incohérence entre nom de fichier et nom d'outil. Rappelez-vous que le nom de fichier est le nom de l'outil. Renommez le fichier, pas un champ name, et utilisez le snake_case.

La planification ne se déclenche jamais en local. Les planifications cron se déploient comme des tâches Vercel Cron — elles s'exécutent dans l'environnement déployé, pas nécessairement à chaque exécution de dev locale. Déclenchez le gestionnaire manuellement en dev pour le tester.

Étapes suivantes

• Remplacez le web_search fictif par un vrai fournisseur (par exemple une API de recherche ou Firecrawl) et câblez les identifiants via Vercel Connect.
• Ajoutez une intégration connections/ pour un service externe typé afin que les identifiants restent hors de votre prompt et du code de vos outils.
• Explorez davantage la sandbox — exécutez du code généré par le modèle dans une microVM éphémère via l'outil intégré bash.
• Comparez le modèle orienté système de fichiers d'eve aux frameworks orientés code comme le Vercel AI SDK pour décider lequel convient à votre équipe.

Conclusion

eve recadre le développement d'agents autour du système de fichiers : outils, compétences, sous-agents, canaux et planifications ne sont que des fichiers dans des dossiers conventionnels, et eve les compile en un backend durable qui s'exécute sur Vercel Functions. Vous avez obtenu un assistant de recherche fonctionnel avec des outils typés, une compétence à la demande, des sessions durables, un sous-agent spécialiste, une planification hebdomadaire et un chemin de déploiement — sans gérer vous-même les files d'attente, les runtimes ou les clés de fournisseurs.

Le plus grand changement mental est la séparation outils / compétences : des actions typées que le modèle appelle contre des procédures que le modèle lit. Maîtrisez cela et vos agents restent rapides sur les tours simples tout en restant capables sur les tours approfondis. À partir de là, intégrez de vrais services, ajoutez des canaux pour les surfaces où vivent réellement vos utilisateurs, et laissez la durabilité de Vercel porter le travail de longue durée.

Sources

• eve — documentation Vercel
• Concepts eve — documentation Vercel
• Introducing eve — blog Vercel
• vercel/eve sur GitHub
• eve.dev — Getting Started