Comment utiliser Agent-Native ? Tutoriel d’installation et de développement d’un framework d’agents IA en TypeScript

Agent-Native est un choix adapté aux équipes TypeScript qui veulent faire utiliser à leur agent les mêmes actions, données et états que l’interface ; il convient moins à un produit qui a seulement besoin d’ajouter une fenêtre de discussion. Commencez par le projet minimal du Quickstart officiel, puis vérifiez les entrées, les droits et la cohérence UI-agent avant d’ajouter des fonctions métier ou de retenir un hôte de production.

Ce tutoriel s’adresse aux développeurs qui construisent une application d’agent en TypeScript et souhaitent créer puis tester une première action partagée.
Il concerne aussi les équipes produit qui doivent rendre les opérations de l’agent visibles, modifiables et contrôlables depuis l’interface.
Les responsables d’environnement de développement y trouveront les vérifications à mener avant d’exécuter le projet à distance.

Dernière vérification le 25 septembre 2026, à partir du dépôt officiel, du Quickstart et de la documentation Agent-Native et des pages officielles citées ci-dessous. Les commandes, interfaces de programmation et capacités d’hébergement peuvent évoluer : le Quickstart et les documents de déploiement restent les références à contrôler avant une nouvelle installation.

Décider si le modèle Agent-Native correspond au produit

Agent-Native est un framework d’agents IA pensé pour les applications où l’agent ne doit pas agir dans un espace séparé de l’application. Le point décisif n’est donc pas la présence d’une conversation, mais le fait que les actions métier, les données et l’état de l’application puissent être liés aux interactions de l’interface. La documentation des concepts clés d’Agent-Native expose cette orientation.

Ce modèle peut convenir à un outil de création où un agent prépare un projet que l’utilisateur ajuste ensuite dans une interface visuelle. Il peut également être pertinent pour un produit audio ou vidéo, par exemple si une opération lancée par l’agent modifie une liste de pistes, un montage ou des métadonnées que la personne doit ensuite examiner. Dans les deux cas, l’action de l’agent doit produire un changement compréhensible et contrôlable, plutôt qu’une réponse textuelle sans conséquence dans l’application.

À l’inverse, l’approche est moins justifiée si le produit ne fait que répondre à des questions sans modifier d’objet métier, si un composant conversationnel existant répond déjà au besoin, ou si l’équipe ne veut pas maintenir de logique d’application, de stockage et d’autorisations. Un cadre qui rapproche interface et agent n’efface pas les coûts de conception : il les rend plus importants, car le même chemin d’action doit être valable pour des utilisateurs et des appels agent potentiellement différents.

Situation du projet	Pertinence d’Agent-Native	Décision à prendre
L’agent et l’interface modifient les mêmes objets métier	Forte si les actions et l’état doivent rester inspectables	Prototyper une action réversible et vérifier les droits des deux chemins
L’agent suggère du contenu que l’utilisateur retouche dans l’interface	Intéressante pour un éditeur, un outil de conception ou un flux audio/vidéo	Définir clairement ce qui est une suggestion et ce qui est une modification persistée
Le besoin se limite à une conversation sans action applicative	Faible si le framework ajoute une architecture que le produit n’utilisera pas	Comparer avec une intégration plus légère avant d’adopter ce cadre
L’équipe n’a pas encore défini l’identité, le stockage ou l’autorisation	À différer : le partage d’action ne résout pas ces sujets	Établir les règles métier avant de connecter l’agent aux données

Le risque principal est de confondre une capacité partagée avec un contrôle partagé. Une action accessible à l’interface et à l’agent peut uniformiser le point d’entrée vers une opération ; elle ne garantit pas que les deux appelants disposent des mêmes droits, que l’état sera correctement persisté, ni que l’erreur sera compréhensible.

Point de vigilance : une démonstration où l’agent et l’interface modifient le même objet prouve seulement que ce parcours précis fonctionne. Elle ne constitue pas une vérification générale de l’isolation des données ou des autorisations.

Avant le démarrage, relever les dépendances réelles

Pour installer Agent-Native, il faut éviter de choisir les versions de mémoire ou de recopier une commande issue d’un article ancien. Le Quickstart officiel et le modèle qu’il demande de créer sont les références pour la commande de génération, le gestionnaire de paquets et les scripts effectivement présents dans le projet. La documentation disponible ne justifie pas de présenter ici un seuil de version universel : celui-ci doit être vérifié dans les instructions actuelles et dans les fichiers du modèle.

Voici les paramètres à relever avant de lancer le développement. Ils sont plus utiles qu’une liste de versions supposées, puisqu’ils décrivent le projet effectivement installé et l’environnement dans lequel il sera exécuté.

Paramètre à contrôler	Où relever la valeur	Pourquoi cela compte
Commande de création et modèle généré	Quickstart officiel, puis fichiers du projet	Un modèle peut déterminer les scripts, les dépendances et la structure à suivre
Moteur d’exécution et gestionnaire de paquets	Instructions du Quickstart et fichiers de configuration produits	Une différence entre la machine locale et l’environnement distant peut empêcher l’installation ou le démarrage
Actions et forme des données d’entrée	Documentation de définition des actions	Le schéma doit exprimer les données attendues et permettre une validation cohérente
Autorisation et contexte d’appel	Documentation de contrôle d’accès	L’agent ne doit pas hériter implicitement des droits de la personne connectée
Base, variables et persistance	Documentation de base de données et variables d’environnement de production	Le stockage et les secrets doivent survivre au déploiement sans être intégrés au code source

Créer le projet sans figer une commande périmée

Ouvrez le Quickstart officiel et copiez la commande de création depuis sa version actuelle. Exécutez-la dans un répertoire dédié, puis inspectez le résultat avant d’ajouter vos dépendances. Le nom d’un modèle ou les options d’une interface en ligne de commande peuvent changer ; inventer une commande plausible rendrait le tutoriel moins fiable qu’une référence directe à la documentation maintenue.

Une fois le squelette généré, suivez ces opérations dans l’ordre :

• Vérifiez que le répertoire contient les fichiers de configuration attendus par le gestionnaire de paquets indiqué par le Quickstart.
• Installez les dépendances avec le gestionnaire correspondant au modèle, sans mélanger plusieurs fichiers de verrouillage.
• Examinez les scripts disponibles avant de démarrer l’application ; utilisez le script défini dans le projet plutôt que de supposer son nom.
• Lancez le projet sans modification et confirmez que l’interface répond.
• Consultez les messages de démarrage et corrigez d’abord les dépendances ou variables manquantes, avant d’introduire une action métier.
• Conservez les fichiers de verrouillage et les versions réellement générées afin de pouvoir reproduire l’installation dans l’environnement de test.

Le contrôle de l’installation ne se limite pas à voir une page dans un navigateur. Il faut aussi vérifier que le processus peut joindre ses dépendances, que les erreurs sont visibles dans la sortie de démarrage et que la structure obtenue correspond bien aux instructions consultées. Pour les écarts propres au développement du dépôt, les consignes de développement du projet sont un complément à consulter ; elles ne remplacent pas les instructions d’installation du Quickstart.

Démarrer par une action métier simple et commune

Une action partagée doit représenter une opération métier précise, pas un accès général à la base. Par exemple, une application peut autoriser le renommage d’un espace de travail. L’interface peut proposer un formulaire pour cette opération ; l’agent peut demander le même changement après une instruction de l’utilisateur. Le résultat attendu, la validation et les autorisations doivent rester définis au niveau de la logique métier.

La documentation Agent-Native décrit la manière de définir les actions et de les rendre disponibles dans le cadre du projet. Il faut reprendre l’API exacte depuis cette documentation, plutôt que de supposer qu’un nom de fonction, une méthode d’enregistrement ou une forme de retour trouvée dans un exemple externe est encore compatible. Le fragment ci-dessous illustre seulement une règle TypeScript de domaine : il ne prétend pas être une API d’enregistrement Agent-Native.

type RenameInput = {
  workspaceId: string;
  name: string;
};

type Actor = {
  userId: string;
  canRenameWorkspace: boolean;
};

function validateRenameInput(value: unknown): RenameInput {
  if (typeof value ! "object" || value = null) {
    throw new Error("Entrée invalide");
  }

  const input = value as Record<string, unknown>;

  if (
    typeof input.workspaceId ! "string" ||
    typeof input.name ! "string" ||
    input.name.trim().length === 0
  ) {
    throw new Error("Identifiant ou nom invalide");
  }

  return {
    workspaceId: input.workspaceId,
    name: input.name.trim(),
  };
}

async function renameWorkspace(
  actor: Actor,
  value: unknown,
  save: (id: string, name: string) => Promise<void>,
) {
  const input = validateRenameInput(value);

  if (!actor.canRenameWorkspace) {
    throw new Error("Opération non autorisée");
  }

  await save(input.workspaceId, input.name);
  return { workspaceId: input.workspaceId, name: input.name };
}

Dans le projet, l’adaptateur conforme à l’API officielle doit recevoir les données, établir le contexte d’appel, appliquer la validation et l’autorisation, puis appeler cette logique ou son équivalent. Le composant d’interface et l’agent doivent être raccordés à l’action selon la documentation, mais ne doivent pas chacun réimplémenter le renommage de façon indépendante. Ce partage évite que des règles métier divergentes s’installent dans deux chemins d’exécution.

Une validation de type TypeScript ne suffit pas, à elle seule, à valider une entrée à l’exécution : les données reçues du navigateur ou de l’agent doivent être contrôlées au point d’entrée. De même, l’exemple d’autorisation montre une décision métier simplifiée, pas une solution complète de gestion d’identité. Le contexte réel doit être établi par le mécanisme d’authentification de l’application ; l’action doit vérifier les droits sur l’objet concerné et ne pas se fier à un identifiant ou à un rôle déclaré par le client.

À retenir : « même action » signifie que les deux parcours peuvent converger vers une capacité métier commune. Cela ne signifie ni « même utilisateur », ni « mêmes droits », ni « même degré de confiance ».

Vérifier l’état commun et les limites d’accès

Après la création de l’action, vérifiez les interactions à partir de scénarios explicites. Le but est de constater si les changements apparaissent dans le bon contexte, si l’état est conservé et si un refus d’accès ne devient pas une réussite apparente. La documentation sur la base et la synchronisation précise le rôle des mécanismes de données propres au framework ; consultez-la avant de décider qu’un état visible dans l’interface est nécessairement persistant.

Pour un premier parcours de contrôle :

• Connectez-vous dans l’interface avec un contexte utilisateur autorisé, modifiez l’objet, puis demandez à l’agent de relire ce même objet.
• Demandez ensuite à l’agent de faire une modification autorisée, puis rechargez l’interface pour observer si elle reflète l’état sauvegardé.
• Envoyez une entrée vide, mal formée ou faisant référence à un objet auquel l’appelant n’a pas accès ; le résultat doit être un refus explicite, sans modification partielle.
• Répétez les essais avec un contexte non autorisé et vérifiez que la règle est appliquée par l’action, pas uniquement masquée dans l’interface.
• Provoquez une erreur de stockage ou de dépendance dans un environnement de test contrôlé, puis examinez le retour présenté à l’utilisateur et les traces côté serveur.
• Contrôlez que les données d’un utilisateur ne deviennent pas visibles à un autre par le biais d’une recherche, d’une conversation ou d’un identifiant manipulé.

Les règles d’accès des actions doivent servir de référence à ce travail. Une action disponible dans un contexte conversationnel ne devrait pas être considérée comme autorisée simplement parce qu’elle figure dans le catalogue d’actions de l’agent. L’application doit déterminer qui fait la demande, quelles données sont concernées et quelles opérations sont permises, puis appliquer la décision à chaque appel.

Les erreurs méritent la même attention que les opérations réussies. Si l’agent reçoit un message de succès après un refus, l’utilisateur risque de croire que l’objet a été modifié. Si le serveur révèle dans l’erreur des données d’un autre compte, l’échec devient une fuite. Le retour doit donc distinguer les problèmes de saisie, les refus d’accès et les défaillances techniques sans exposer des secrets ni des données hors périmètre.

Relier le stockage et les capacités externes avec prudence

Avant d’ajouter un modèle, un outil tiers ou une base de données, identifiez ce qui est pris en charge par la version du projet créée. La page officielle sur la base de données côté serveur sert à comprendre comment la couche de données s’insère dans l’application et dans la synchronisation de l’état. Elle ne doit pas être interprétée comme une garantie que tout fournisseur ou toute architecture de stockage externe est interchangeable.

Pour chaque intégration, consignez le rôle de la dépendance, son mode de configuration, les données qu’elle reçoit et les erreurs qu’elle peut produire. Les secrets de connexion ne doivent pas être livrés dans le navigateur ni enregistrés dans le dépôt. Quand la documentation ne décrit pas explicitement un fournisseur de modèle ou un outil, traitez son intégration comme un travail à tester : validez l’appel, les délais d’attente, les erreurs, les permissions et le comportement en cas d’indisponibilité, sans annoncer une compatibilité officielle non documentée.

Les conversations et les objets métier doivent également avoir des responsabilités distinctes. Une réponse produite dans un échange ne prouve pas que l’objet correspondant a été sauvegardé ; inversement, un changement persistant peut nécessiter une actualisation ou une lecture explicite pour être visible dans l’interface. Lors du prototype, inspectez le flux de données depuis l’appel de l’action jusqu’à la couche de stockage, puis du stockage vers l’état affiché. Cette vérification aide à repérer les interfaces qui montrent une valeur optimiste sans confirmation du serveur.

Préparer le déploiement sans extrapoler le support

Le projet minimal qui démarre localement n’établit pas, à lui seul, que l’application peut être déployée sur n’importe quel hôte. Consultez la page déployer une application et la documentation de périmètre de déploiement et exigences de base de données, puis vérifiez que l’hôte visé correspond aux contraintes effectivement décrites. Ne déduisez pas la prise en charge d’un environnement à partir du seul fait que le code TypeScript peut y être compilé.

Avant un déploiement pilote, cochez les points suivants :

• [ ] Le projet démarre depuis une installation propre en utilisant les fichiers de verrouillage conservés.
• [ ] Le moteur d’exécution et le gestionnaire de paquets concordent avec le modèle créé et l’environnement cible.
• [ ] Les variables nécessaires sont recensées à partir de la documentation des variables d’environnement de production, puis configurées hors du code source.
• [ ] La base et son mode de persistance répondent aux besoins réels de l’application ; la disparition éventuelle de données temporaires est comprise.
• [ ] Les journaux permettent de distinguer une erreur d’action, un refus d’accès et un échec de dépendance sans exposer de secret.
• [ ] Les essais de lecture, d’écriture, de refus et de cohérence d’état sont rejoués sur l’environnement pilote.
• [ ] Le comportement d’une intégration externe est vérifié séparément si la documentation officielle consultée ne la garantit pas.
• [ ] Une procédure de retour arrière ou de restauration est définie avant d’utiliser des données importantes.

Ces vérifications sont particulièrement importantes pour une équipe qui évalue un environnement de développement distant. Il faut confirmer la compatibilité du système, la disponibilité des dépendances requises, l’accès aux journaux et la capacité du processus à rester actif selon le mode de déploiement choisi. Une session de développement interrompue et un service déployé en continu ne sont pas le même besoin ; l’environnement doit être choisi en fonction du second si l’objectif est de tester un service durable.

Pour comparer les contraintes d’un poste local, d’une machine distante et d’un hôte de déploiement, ne partez pas d’une promesse générale de performance. Relevez plutôt le système requis, les dépendances du projet, l’accès au stockage et la méthode de gestion des secrets. Si le développement suppose un environnement macOS, les options disponibles sur la page des Mac mini en location peuvent être examinées en regard des dépendances du projet ; pour vérifier les modalités et les limites de service avant de choisir, consultez le centre d’aide de Zutcloud.

FAQ sur l’installation et la mise en production

Quelle démarche suivre pour créer un projet Agent-Native en TypeScript ?

Utilisez la commande de génération indiquée dans le Quickstart officiel au moment de l’installation, puis examinez les scripts et les fichiers du modèle créé. Installez les dépendances avec le gestionnaire prévu par ce modèle et démarrez l’application sans personnalisation. Cette séquence permet d’isoler les problèmes de dépendances et de configuration avant d’introduire une action ou une intégration supplémentaire.

Comment partager une action entre l’interface et l’agent ?

Définissez l’opération métier avec une entrée contrôlée, un résultat identifiable et un traitement d’autorisation exécuté côté serveur. Raccordez ensuite l’interface et l’agent à cette capacité au moyen de l’API décrite dans la documentation des actions. Il faut conserver une seule règle métier, mais établir les droits selon l’identité et le contexte de chaque appel, sans supposer que le partage de code partage aussi les permissions.

Quels essais permettent de contrôler les états et les permissions ?

Faites modifier un objet par l’interface puis lire son état par l’agent, et inversez le parcours. Vérifiez ensuite les refus d’accès, les entrées incorrectes, les erreurs de stockage et la persistance après rechargement. Contrôlez le retour affiché et les journaux côté serveur. Ces tests couvrent des parcours utiles pour le pilote ; ils ne remplacent pas une analyse de sécurité adaptée aux données et aux risques de l’application.

Que vérifier avant de choisir un environnement de déploiement ?

Relevez les exigences d’exécution du projet, le système de base de données, la persistance, les variables d’environnement et les besoins de journalisation dans les documents officiels. Comparez-les à l’hôte réellement envisagé et testez le processus de déploiement avec la configuration du projet. Pour une dépendance externe non mentionnée dans la documentation, validez le comportement dans un essai isolé plutôt que de présumer sa compatibilité.

Après le prototype, l’arbitrage porte surtout sur le coût de maintenir un environnement cohérent, la continuité des processus et l’accès aux dépendances : un poste local peut nécessiter des ajustements propres à chaque développeur, tandis qu’un hôte générique peut ne pas répondre à un besoin macOS ou rendre certaines vérifications moins représentatives. Si le projet nécessite temporairement un environnement Mac pour développer ou valider ses dépendances, la location auprès de Zutcloud peut constituer une option à évaluer ; si la charge est durable, stable et intensive, comparez d’abord cette option à l’achat et à l’exploitation d’une machine dédiée.

FAQ

Comment démarrer un projet Agent-Native en TypeScript ?

Partez du Quickstart officiel et utilisez la commande de création de projet qu’il publie au moment de votre installation : ne recopiez pas une commande trouvée dans un ancien exemple. Vérifiez ensuite le moteur d’exécution, le gestionnaire de paquets et les scripts définis par le modèle obtenu. Lancez l’application avant d’ajouter une action métier, afin de distinguer un problème de dépendance d’une erreur dans votre code.

Comment rendre une action utilisable à la fois dans l’interface et par l’agent ?

Définissez la capacité métier dans une action dont les données d’entrée et le résultat sont explicites, puis reliez l’interface et l’agent à cette même capacité selon l’API documentée par Agent-Native. La validation doit s’exécuter côté serveur, et l’autorisation doit être contrôlée pour chaque appel. Une interface et un agent qui invoquent la même action ne partagent pas automatiquement une identité ni des droits.

Comment vérifier les droits et l’état partagé d’une application Agent-Native ?

Modifiez un objet depuis l’interface, relisez-le au moyen de l’agent, puis tentez une opération non autorisée avec un compte ou un contexte qui ne devrait pas y accéder. Contrôlez la persistance après rechargement, les erreurs retournées et les journaux disponibles. Ces essais apportent des éléments de validation, mais ne démontrent pas à eux seuls que l’application est sûre dans tous les cas.

Que faut-il vérifier avant de déployer un projet Agent-Native ?

Comparez l’hôte envisagé aux exigences exposées dans les documents de déploiement, puis relevez le moteur d’exécution attendu par le modèle, les variables d’environnement, la configuration de la base et la stratégie de persistance. Vérifiez également les journaux et le traitement des secrets. Si un adaptateur de modèle ou un outil tiers n’est pas décrit dans la documentation consultée, testez-le séparément au lieu de supposer qu’il est pris en charge.

À lire aussi

• Relier les actions d’interface à un rendu contrôlé : guide de dépannage React
• Comprendre les appels d’outils des agents et sécuriser leur exécution