Créer un harness package pour l'AI SDK Vercel

Ajouter un nouveau package harness

Ce guide couvre la création d'un nouveau package @ai-sdk/harness-<name> pour un harness d'agent.

Un harness peut être piloté par l'hôte, où le runtime s'exécute dans le processus hôte et utilise le sandbox à distance, ou adossé à un bridge, où un petit bridge s'exécute à l'intérieur du sandbox car le runtime a besoin d'un accès local au système de fichiers ou à l'environnement de processus du sandbox. Préférez piloté par l'hôte quand le runtime le supporte.

Harnesses propriétaires vs tiers

Packages tiers : N'importe quel runtime peut publier un package harness externe.
Packages propriétaires @ai-sdk/harness-<name> : Créez d'abord un problème pour discuter si le runtime appartient à ce dépôt.

Architecture du harness

Le SDK AI utilise une architecture harness en couches suivant le pattern adaptateur :

Spécification du harness (@ai-sdk/harness) : Définit les interfaces comme HarnessV1 et HarnessV1Session
Utilitaires (@ai-sdk/harness/utils) : Code partagé pour implémenter les harnesses
Implémentations du harness (@ai-sdk/harness-<name>) : Adaptateurs concrets pour les harnesses
Agent harness (@ai-sdk/harness/agent) : L'API HarnessAgent orientée utilisateur de haut niveau

Guide étape par étape

1. Créer la structure du package

Créez packages/harness-<name> avec cette structure de base :

packages/harness-<name>/
├── src/
│   ├── index.ts
│   ├── <name>-harness.ts
│   ├── <name>-harness.test.ts
│   └── <name>-auth.ts              # si le runtime nécessite une résolution d'authentification
├── package.json
├── tsconfig.json
├── tsconfig.build.json
├── tsup.config.ts
├── turbo.json
├── vitest.node.config.js
└── README.md

Si le runtime doit s'exécuter à l'intérieur du sandbox, ajoutez également les fichiers de bridge :

src/
├── <name>-bridge-protocol.ts
├── <name>-bridge-protocol.test.ts
└── bridge/
    ├── index.ts
    ├── package.json
    └── pnpm-lock.yaml

Ne créez pas manuellement un fichier CHANGELOG.md.

2. Configurer package.json

Utilisez les packages harness existants comme source de vérité pour les scripts, exports, métadonnées du dépôt et paramètres de publication.

Éléments de base requis du package :

"name": "@ai-sdk/harness-<name>"
"type": "module"
"license": "Apache-2.0"
"sideEffects": false
dépendance sur @ai-sdk/harness via workspace:*
dépendance sur @ai-sdk/provider-utils via workspace:* lors de l'utilisation d'utilitaires sandbox/auth/schema
dépendances du SDK/CLI du runtime requises par le harness
dépendances de développement correspondant aux packages harness existants
"engines": { "node": ">=22" }

Pour les packages de bridge, ajoutez toute étape de copie d'assets de bridge requise pour les fichiers sous src/bridge/.

3. Créer les configs TypeScript, build et test

Copiez les fichiers de config du package harness existant le plus proche et ajustez les chemins/noms de package :

tsconfig.json
tsconfig.build.json
tsup.config.ts
turbo.json
vitest.node.config.js

Les packages harness utilisent actuellement uniquement des tests Node sauf si l'implémentation a une raison spécifique d'ajouter un autre runtime.

4. Implémenter l'adaptateur harness

Exportez une factory depuis <name>-harness.ts et réexportez-la depuis src/index.ts.

Utilisez le document d'architecture pour les détails du contrat. Au moment de l'implémentation, vérifiez :

retourner un HarnessV1 avec specificationVersion: 'harness-v1' ;
utiliser un harnessId stable en kebab-case ;
exposer les outils natifs intégrés de l'adaptateur via builtinTools ;
garder la construction synchrone et sans effets secondaires ;
utiliser startOpts.sandboxSession et startOpts.sessionWorkDir ; ne créez jamais un sandbox séparé ;
levez HarnessCapabilityUnsupportedError depuis la méthode qui nécessite une capacité de runtime non supportée.

Si le runtime nécessite une configuration dans le sandbox, exposez getBootstrap().

5. Implémenter les préoccupations spécifiques au runtime

Ajoutez uniquement les préoccupations que le runtime nécessite :

résolution d'authentification ;
matérialisation de skill ou de fichier de découverte ;
traduction du protocole natif en flux/contrôle harness ;
schéma d'état du cycle de vie ;
protocole de bridge et diagnostiques.

6. Écrire les tests

Ajoutez des tests Node ciblés pour :

les métadonnées et paramètres de la factory ;
la résolution d'authentification ;
l'utilisation du sandbox et le placement des chemins ;
les opérations distantes pilotées par l'hôte ou le comportement du protocole de bridge ;
la traduction des événements prompt/control ;
le comportement de reprise de session vs continuation de tour ;
les erreurs de capacité non supportée ;
la matérialisation de skill, si supportée.

Utilisez des sessions de sandbox mockées et des limites de bridge/runtime où possible. N'exigez pas de credentials de provider en direct dans les tests unitaires.

7. Ajouter un README

Gardez le README court :

objectif du package ;
commande de configuration ;
utilisation minimale de HarnessAgent ;
capacités de sandbox requises, telles que les ports pour les runtimes adossés à un bridge ;
configuration d'authentification notable.

Faites un lien vers la documentation principale du harness pour les concepts plus larges.

8. Ajouter des exemples

Ajoutez les exemples pertinents pour le nouveau harness.

Ajoutez des exemples API/fonction sous examples/ai-functions quand le package harness nécessite un exemple de comportement de provider scriptable.
Ajoutez des exemples interactifs miroir des exemples harness existants dans examples/harness-e2e-next (Next.js) et examples/harness-e2e-tui (TUI).

9. Ajouter la documentation

Créez la documentation dans content/providers/02-ai-sdk-harnesses/<numéro suivant>-<name>.mdx.

Incluez :

Instructions de configuration
Capacités de sandbox requises
Configuration d'authentification
Options spécifiques au harness
Exemples d'utilisation
Limitations connues

Mettez à jour content/docs/03-ai-sdk-harnesses/05-harness-adapters.mdx pour lister le nouveau harness quand il est prêt à être public.

10. Mettre à jour les références et valider

Exécutez depuis la racine du workspace :

pnpm update-references
pnpm --filter @ai-sdk/harness-<name> build
pnpm --filter @ai-sdk/harness-<name> test
pnpm type-check:full

Exécutez manuellement les exemples harness pertinents quand le runtime peut être testé avec les credentials disponibles.

Checklist

[ ] Structure du package créée dans packages/harness-<name>
[ ] package.json configuré avec les bonnes dépendances
[ ] Configs TypeScript configurées (tsconfig.json, tsconfig.build.json)
[ ] Configuration build (tsup.config.ts)
[ ] Configuration test (vitest.node.config.js)
[ ] Implémentation de l'adaptateur harness complète
[ ] Placement du runtime géré sans créer de sandbox caché
[ ] Assets de bridge copiés pendant le build, si adossé à un bridge
[ ] Résolution d'authentification implémentée, si nécessaire
[ ] Infrastructure harness, skills, code de bridge et secrets tenus hors de sessionWorkDir
[ ] Reprise de session et continuation de tour testées
[ ] Tests unitaires écrits et passants
[ ] README.md écrit
[ ] Exemples ajoutés
[ ] Documentation ajoutée dans content/providers/02-ai-sdk-harnesses/
[ ] Liste des adaptateurs harness mise à jour, si public
[ ] pnpm update-references exécuté
[ ] Build du package passant
[ ] Tests du package passants
[ ] Vérification des types passante (pnpm type-check:full depuis la racine)
[ ] Exemples pertinents exécutés avec succès

Documentation connexe

Architecture d'abstraction du harness
README @ai-sdk/harness
Packages harness existants avec placement de runtime similaire

add-harness-package