Agent IA DeepSeek Harness : guide de développement

Ce guide s’adresse aux développeurs qui veulent créer leur premier agent IA DeepSeek Harness sans commencer par une architecture multi-agents difficile à contrôler. Nous suivons une progression concrète : définir une tâche minimale, exécuter la première boucle, connecter un outil, conserver l’état, puis préparer un environnement distant et réinitialisable.

Dernière mise à jour : 17 août 2026. Vérification effectuée à partir du dépôt officiel DeepSeek Harness, de sa page des versions et de la documentation officielle de l’API DeepSeek. En septembre 2026, le dépôt officiel deepseek-ai/deepseek-harness et la CLI dsh sont publics. Pour installer le runtime officiel et lancer Web / headless, lisez le Tutoriel d’installation DeepSeek Harness (dsh). Cet article reste sur la boucle maison et l’acceptation des outils ; il ne remplace pas la documentation CLI officielle.

Un dépôt public peut déjà afficher plus de 130 000 étoiles tout en restant en aperçu développeur. C’est le cas de DeepSeek Harness au moment de notre vérification : le projet évolue rapidement et le dépôt officiel avertit que des changements incompatibles sont possibles. (github.com)

Notre jugement : adapté pour valider rapidement un agent IA orienté outils ou développement, mais pas adapté à un lancement directement complexe. Commencez par une boucle minimale avec un seul outil, un état contrôlé et une condition d’arrêt explicite. Ajoutez ensuite les extensions, la mémoire et l’exécution parallèle.

Cette méthode évite de confondre une démonstration réussie avec un système exploitable. Elle permet aussi de savoir à quel moment un poste local suffit et quand il devient préférable de déplacer l’environnement vers une machine distante, isolée et réinitialisable.

Cet article s’adresse :

• aux développeurs qui découvrent DeepSeek Harness et veulent créer leur premier agent ;
• aux équipes qui doivent transformer un prototype local en service exécuté de façon continue ;
• aux responsables techniques qui veulent mesurer la fiabilité des appels d’outils, la récupération après erreur et le taux de réussite sur de vraies tâches.

Avant le premier lancement : réduire la tâche à une frontière vérifiable

Le premier piège consiste à demander à l’agent de « gérer un projet complet ». Cette consigne mélange analyse, planification, accès aux fichiers, exécution de commandes, validation et communication avec l’utilisateur. Lorsqu’un résultat est incorrect, il devient difficile de savoir quelle partie a échoué.

Nous recommandons de définir quatre éléments avant d’installer quoi que ce soit :

1. L’entrée : une demande précise, avec son format attendu.
2. Les outils disponibles : idéalement un seul outil pour le premier test.
3. La sortie attendue : un fichier, une réponse structurée ou un état de tâche.
4. La condition d’arrêt : succès, erreur bloquante, demande de confirmation ou limite atteinte.

Un bon premier scénario peut être la lecture d’un fichier de configuration et la production d’un rapport JSON. Un mauvais premier scénario serait la modification automatique d’un dépôt, l’installation de dépendances et le lancement de tests sans validation intermédiaire.

Le dépôt officiel présente DeepSeek Harness comme un agent où tout est organisé sous forme de modules et de greffons. Il s’appuie sur Cordis et reste indiqué comme une version d’aperçu développeur. (github.com) Cette architecture est intéressante pour composer un environnement, mais elle augmente aussi le nombre de frontières à vérifier : installation, compatibilité des greffons, permissions, état et cycle de vie.

DeepSeek Harness permet-il de créer un premier agent IA sans construire une plateforme complète ?

Oui, à condition de limiter l’objectif. Le premier agent doit démontrer qu’une requête entre, qu’un modèle choisit ou non un outil, que le programme exécute cet outil, que son résultat revient dans l’historique, puis que l’agent s’arrête. Tout ce qui n’est pas nécessaire à cette chaîne peut attendre.

Première étape : préparer l’environnement sans masquer les dépendances

Le dépôt officiel indique deux chemins de lancement : l’exécution depuis le gestionnaire de paquets avec npx, ou la récupération du code source suivie d’une installation et d’une compilation avec pnpm. Le lancement de l’interface Web utilise par défaut une adresse locale et un port local documenté dans le dépôt. (github.com)

Nous procédons ainsi :

1. Créer un répertoire de travail isolé.
2. Vérifier la version de Node.js demandée par le dépôt et les fichiers de verrouillage.
3. Installer DeepSeek Harness depuis le dépôt ou le paquet officiel.
4. Injecter la clé API par variable d’environnement, jamais dans le code source.
5. Lancer l’interface ou le point d’entrée minimal.
6. Tester une requête sans outil.
7. Tester ensuite une seule fonction contrôlée.

Cette séparation est importante. Si le premier test échoue déjà sans outil, le problème se situe probablement dans l’adaptateur de modèle, la clé, l’URL de l’API ou la configuration du projet. Si le test sans outil réussit mais que l’appel de fonction échoue, il faut examiner le schéma, la validation des arguments et la boucle d’exécution.

La documentation officielle de l’API DeepSeek décrit une interface compatible avec le format des appels de discussion courants. Elle distingue les messages utilisateur, assistant et outil, ce qui donne une base claire pour reconstruire l’historique d’une tâche. (api-docs.deepseek.com)

Nous vous conseillons de conserver dès le départ un fichier de configuration séparé :

DEEPSEEK_API_KEY=clé_non_versionnée
AGENT_WORKDIR=répertoire_de_tâche
AGENT_LOG_LEVEL=info

Ce fichier ne doit pas être ajouté au dépôt. Pour une équipe, ajoutez également une procédure de rotation de clé et un contrôle indiquant quelles commandes l’agent peut exécuter.

Deuxième étape : faire fonctionner la boucle minimale

Un agent IA n’est pas seulement un appel au modèle. La boucle minimale comporte généralement quatre responsabilités :

• L’adaptateur de modèle prépare la requête et reçoit la réponse.
• L’entrée de tâche transforme la demande utilisateur en objectif exploitable.
• L’exécuteur d’outils valide et lance la fonction demandée.
• L’historique conserve les messages nécessaires pour permettre une décision suivante.

Le flux de base ressemble à ceci :

demande utilisateur
        ↓
appel au modèle avec la liste des outils
        ↓
réponse textuelle ou demande d’outil
        ↓
validation des arguments
        ↓
exécution de l’outil
        ↓
retour du résultat dans l’historique
        ↓
nouvel appel au modèle
        ↓
réponse finale ou arrêt

La documentation officielle précise que le modèle ne réalise pas lui-même la fonction externe : le programme doit exécuter l’outil, puis renvoyer son résultat dans un message associé à l’identifiant de l’appel. (api-docs.deepseek.com)

Pour un premier essai, choisissez une fonction sans effet destructeur :

def lire_statut(projet: str) -> dict:
    return {
        "projet": projet,
        "etat": "pret",
        "source": "fichier_local"
    }

Le test doit vérifier quatre événements distincts :

• la requête est acceptée ;
• l’agent produit un appel avec le bon nom ;
• les arguments sont valides ;
• la réponse finale arrive après le retour de l’outil.

Ne mesurez pas seulement la qualité du texte final. Un agent peut produire une réponse convaincante après avoir appelé le mauvais outil. Conservez donc l’identifiant d’appel, le nom de fonction et les arguments bruts.

Comment DeepSeek Harness intègre-t-il un outil personnalisé ?

Pour connecter un outil personnalisé, définissez d’abord son contrat avant son implémentation. Le modèle doit comprendre ce que fait la fonction, quand l’utiliser et quelles données sont obligatoires. Le programme, lui, doit vérifier les arguments indépendamment de la description fournie au modèle.

L’API DeepSeek accepte les outils de type fonction. Chaque fonction possède un nom, une description et un schéma de paramètres. La documentation indique également une limite maximale de 128 fonctions dans la requête, ainsi qu’un mode strict expérimental pour mieux respecter le schéma JSON. (api-docs.deepseek.com)

Le contrat d’un outil utile doit préciser :

• les paramètres obligatoires ;
• les valeurs autorisées ;
• les unités ;
• les effets de bord ;
• les erreurs possibles ;
• le format de retour.

Par exemple, un outil lancer_tests ne devrait pas accepter une commande shell libre si une liste de scénarios suffit. Réduire la liberté du paramètre réduit la surface de risque et simplifie l’analyse des échecs.

Le modèle peut toutefois produire un JSON invalide ou inventer un paramètre non prévu. La documentation officielle recommande donc de valider les arguments avant toute exécution. (api-docs.deepseek.com)

Nous enregistrons au minimum les champs suivants pour chaque appel :

task_id
tool_call_id
tool_name
arguments_received
arguments_validated
started_at
finished_at
result_status
error_reason

Cette trace répond à trois questions essentielles :

1. L’agent a-t-il choisi le bon outil ?
2. A-t-il fourni des paramètres corrects ?
3. L’échec vient-il du modèle, du validateur ou de l’outil ?

Sans ces données, le débogage devient une lecture subjective des journaux.

Le premier vrai arbitrage : prototype local ou environnement distant ?

Un poste local est pratique pour modifier rapidement le code, observer les journaux et réinitialiser manuellement une tâche. Il devient moins confortable lorsque l’agent doit rester actif, exécuter des opérations longues ou être partagé par plusieurs personnes.

La décision ne dépend donc pas uniquement de la puissance de calcul. Les coûts cachés sont souvent ailleurs :

• une session locale fermée interrompt l’agent ;
• un répertoire de travail partagé mélange les fichiers de plusieurs tâches ;
• une clé API présente dans l’environnement devient difficile à auditer ;
• une commande lancée avec des permissions trop larges peut modifier des données hors du projet ;
• des journaux non persistants empêchent de reproduire un incident.

Pour les essais créatifs en audio, vidéo ou design, l’environnement distant peut aussi être pertinent lorsque l’agent doit manipuler un projet volumineux, accéder à des outils graphiques ou être repris depuis un autre poste. Dans ce cas, nous séparons toujours le code source, les fichiers temporaires, les rendus et les journaux.

Vous pouvez comparer les options de système et de disponibilité dans les pages de location de Mac cloud aux États-Unis ou examiner les variantes régionales de location de Mac cloud au Japon. Ces pages ne remplacent pas une validation technique : elles servent à cadrer le choix de l’environnement avant le déploiement.

Troisième étape : conserver l’état sans remplir tout le contexte

Comment l’agent conserve-t-il l’état pendant l’exécution d’une tâche ?

Il faut distinguer trois catégories :

1. État de session : messages récents, outil appelé, étape en cours.
2. Artefacts de tâche : fichiers produits, rapport, journal, résultat de test.
3. Connaissances durables : règles du projet, documentation validée, conventions d’équipe.

Mettre ces trois catégories dans l’historique du modèle crée un contexte inutilement lourd et rend les reprises difficiles. Nous préférons un état explicite :

{
  "task_id": "tache-unique",
  "phase": "validation",
  "last_successful_step": "generation",
  "artifacts": ["rapport.json", "journal.txt"],
  "requires_confirmation": false,
  "retry_count": 1
}

Chaque étape doit pouvoir être inspectée. Pour une tâche de codage, la progression peut être :

• analyser le dépôt ;
• proposer un plan ;
• modifier un fichier ;
• exécuter les tests ciblés ;
• examiner l’échec ;
• demander une confirmation ;
• produire un résumé final.

Les règles de reprise doivent également être écrites avant le lancement :

• réessayer si l’erreur est temporaire et que l’opération est idempotente ;
• suspendre si une ressource externe est indisponible ;
• demander confirmation avant une modification destructive ;
• reprendre depuis le dernier artefact validé ;
• abandonner après une limite d’échecs définie par le projet.

Cette organisation est particulièrement importante pour un agent de codage. Une nouvelle tentative complète peut réappliquer une modification, remplacer un fichier déjà corrigé ou créer plusieurs résultats incompatibles.

Quatrième étape : tester un agent de codage avec des limites explicites

DeepSeek Harness convient-il au déploiement d’un agent de codage ?

Oui pour un prototype contrôlé ou une équipe qui accepte de construire ses propres garde-fous. Il ne faut toutefois pas traiter la présence d’un terminal ou d’un outil de fichier comme une garantie de fiabilité.

Nous définissons une zone de travail par tâche. Les permissions sont minimales. Les commandes autorisées sont listées. Les résultats sont enregistrés. Les opérations sensibles passent par une confirmation humaine.

Pour un agent de codage, vérifiez au moins :

• qu’il distingue la branche de travail de la branche de référence ;
• qu’il n’écrase pas un fichier modifié depuis le dernier état ;
• qu’il lance les tests associés à la modification ;
• qu’il signale un test non exécuté ;
• qu’il s’arrête lorsqu’une dépendance manque ;
• qu’il restitue les fichiers produits et les erreurs rencontrées.

Un agent qui modifie correctement un petit projet ne prouve pas qu’il saura gérer une tâche longue. Nous préparons donc un jeu de tâches réelles : correction ciblée, ajout d’une fonction, refactorisation limitée, mise à jour de tests et génération d’un artefact.

Pour chaque tâche, nous notons :

• réussite complète ;
• outil incorrect ;
• paramètres incorrects ;
• arrêt prématuré ;
• boucle inutile ;
• erreur récupérée ;
• erreur non récupérée ;
• intervention humaine nécessaire.

Nous attribuons ensuite une note simple sur cinq axes :

Une moyenne élevée ne suffit pas si un seul critère critique reste faible. Un agent qui obtient une bonne note de progression mais exécute des commandes avec des permissions excessives ne doit pas être déployé.

Quand faut-il ajouter des greffons, de la mémoire ou plusieurs agents ?

Nous ajoutons une extension seulement lorsqu’un test montre un manque précis. Par exemple :

• un greffon de stockage si les artefacts doivent survivre à la session ;
• un greffon de notification si une validation humaine est nécessaire ;
• une mémoire documentaire si les mêmes règles sont relues sur plusieurs tâches ;
• une exécution parallèle si plusieurs actions indépendantes ont été mesurées comme sûres.

Commencer avec plusieurs agents augmente le nombre de communications, d’états intermédiaires et de possibilités de blocage. Pour une petite équipe, un agent principal avec des outils bien définis est souvent plus facile à auditer.

Le dépôt étant encore en aperçu développeur, il faut également verrouiller les dépendances et surveiller les changements de compatibilité. (github.com) La page officielle des versions doit faire partie de la procédure de mise à jour, au même titre que les exemples et les notes de migration. (github.com)

Cinquième étape : déplacer le prototype vers une exécution continue

Lorsque la tâche doit durer longtemps, être reprise à distance ou être partagée, nous préparons l’environnement comme un service contrôlé :

1. Verrouiller les dépendances et conserver le fichier de résolution.
2. Injecter les secrets par le gestionnaire d’environnement.
3. Créer un répertoire de travail par tâche.
4. Séparer journaux, artefacts et fichiers temporaires.
5. Définir une limite de concurrence.
6. Ajouter une politique de redémarrage.
7. Persister l’état après chaque étape validée.
8. Prévoir une réinitialisation complète de l’environnement.
9. Vérifier l’accès distant et les permissions.
10. Tester une interruption volontaire avant la mise en production.

Nous refusons généralement le déploiement immédiat sur une machine personnelle lorsque trois conditions sont réunies : exécution continue, partage entre plusieurs personnes et nécessité de reproduire exactement l’environnement. Une machine distante réinitialisable réduit alors les écarts entre les sessions.

Cela ne signifie pas que la location est toujours préférable. Un projet qui exige une charge stable pendant une longue période peut justifier l’achat et l’administration d’un matériel dédié. À l’inverse, un essai de quelques jours, une validation de compatibilité ou un environnement de démonstration bénéficie souvent d’une solution temporaire.

Pour préparer une migration plus complète, vous pouvez consulter notre guide sur le choix d’un environnement Mac cloud. Nous recommandons de comparer la durée des tâches, le nombre d’utilisateurs, le besoin de réinitialisation et l’accès aux interfaces graphiques avant de choisir une machine.

L’acceptation finale doit porter sur les tâches, pas sur la démonstration

Avant de déclarer l’agent opérationnel, nous exécutons une série de tâches représentatives. Une seule réussite ne permet pas de conclure.

L’acceptation doit vérifier :

• le taux de tâches terminées ;
• la précision des noms et paramètres d’outils ;
• le comportement face à une réponse invalide ;
• la reprise après interruption ;
• la protection des fichiers hors périmètre ;
• la cohérence d’une seconde exécution ;
• la consommation de ressources ;
• la qualité des journaux ;
• la possibilité de réinitialiser l’environnement.

Nous testons aussi volontairement les cas négatifs : outil indisponible, paramètre manquant, fichier verrouillé, commande refusée, réponse vide, délai dépassé et état corrompu. Un bon système ne prétend pas réussir toutes les tâches ; il sait signaler proprement celles qu’il ne peut pas terminer.

L’API DeepSeek expose notamment des raisons de fin permettant de distinguer une réponse terminée, une limite de longueur, un appel d’outil ou une interruption liée aux ressources. Ces informations doivent être conservées dans les journaux plutôt que remplacées par un simple message « échec ». (api-docs.deepseek.com)

Notre règle de décision est la suivante :

• Si la tâche est courte, mono-utilisateur et sans effet de bord, choisissez un environnement local.
• Si la tâche doit rester active pendant une longue période, choisissez un environnement distant.
• Si plusieurs développeurs doivent reprendre la même session, ajoutez une persistance d’état et des journaux centralisés.
• Si l’agent manipule des fichiers sensibles, isolez chaque tâche et limitez les permissions.
• Si le projet exige un système macOS ou des outils graphiques macOS, évaluez une machine Mac distante dédiée.
• Sinon, revenez à une boucle locale plus simple avant d’ajouter de la complexité.

Après cette validation, la différence entre votre montage local et une solution Mac distante devient concrète. Le poste personnel dépend de votre session, de votre réseau, de vos redémarrages et d’un répertoire souvent partagé. Il est également moins pratique pour une reprise par un collègue ou pour conserver une exécution continue. Une location ZekVPS peut offrir un environnement Mac accessible à distance et réinitialisable, ce qui convient mieux aux tests prolongés, aux agents de codage et aux workflows audio, vidéo ou design nécessitant un poste macOS séparé. Elle n’est pas le meilleur choix pour une charge permanente parfaitement prévisible ou pour un besoin d’interface matérielle locale ; dans ces cas, un équipement détenu et administré directement reste plus cohérent. Pour un prototype, une campagne de tests ou une tâche temporaire, nous vous conseillons de commencer par la durée réelle d’exécution et le niveau d’isolation requis, puis de choisir l’environnement qui rend l’échec reproductible plutôt que simplement plus puissant.