Guide DeepSeek Harness pour débutants : de zéro à votre premier agent IA

Ce que couvre ce tutoriel

DeepSeek Harness (dsh) est une plateforme d'agents IA open-source créée par DeepSeek, construite sur le système de plugins Cordis. En clair : elle vous permet

de diriger une IA qui lit et modifie des fichiers sur votre ordinateur, exécute des commandes et travaille sur de vrais projets — tout en étant guidée par vous.

Ce tutoriel part du principe que vous ne savez rien : ni terminal, ni Node.js, ni agents IA. Nous expliquons chaque concept avant de l'utiliser. À la fin, vous aurez le Web UI en marche, votre modèle configuré et votre première tâche d'agent accomplie. Nous couvrons aussi le mode ligne de commande (CLI) et le SDK Python pour un usage avancé.

Quelle version ? L'aperçu public pour développeurs sorti en août 2026 (0.1.0-rc.5) — le même code que deepseek.com/harness et le paquet npm @deepseek-ai/dsh.

Temps : 30–45 minutes   Difficulté : Débutant

Avant de commencer

Combien ça coûte ? Le logiciel est gratuit et open-source (licence MIT). Vous ne payez que le fournisseur du modèle pour l'usage d'IA, mesuré par token (un token est environ une fraction de mot).

Qu'est-ce qu'« un agent IA » ?

Un chatbot normal : vous posez une question, il répond. Un agent va plus loin — il peut *faire* des choses : lire des fichiers, les modifier, exécuter des commandes, chercher sur le web, et enchaîner de nombreuses petites étapes pour accomplir l'objectif que vous décrivez en langage naturel. DeepSeek Harness est le « corps » qui donne des mains au modèle ; le modèle est le « cerveau ».

Qu'est-ce qu'« un modèle » ?

Le « cerveau » de l'IA s'appelle un modèle. Les modèles DeepSeek sont fabriqués par la même entreprise que ce harness. Pour utiliser un modèle vous avez besoin de deux choses : un endpoint API (l'« adresse » à laquelle le logiciel parle) et une clé API (votre « mot de passe personnel » vers cette adresse, lié à votre compte de facturation).

Qu'est-ce qu'« un terminal » ?

Le terminal (appelé PowerShell sur Windows, Terminal sur macOS, et Konsole/GNOME Terminal etc. sur Linux) est une fenêtre où vous tapez des commandes au lieu de cliquer sur des boutons. Toutes les étapes d'installation de ce tutoriel s'y déroulent. Si vous n'en avez jamais utilisé, suivez la section juste en dessous.

Comment ouvrir un terminal (pas à pas)

Étape 1 — Vérifiez Node.js et installez-le si nécessaire

Le moyen le plus rapide d'installer DeepSeek Harness utilise une commande appelée npx, fournie avec Node.js. Vérifions d'abord si Node.js est déjà installé.

Dans votre terminal, tapez ceci et appuyez sur Entrée :

node --version

• Si vous voyez quelque chose comme v20.x.x ou v22.x.x — Node.js est installé. Passez à l'étape 2.
• Si vous voyez command not found (ou node is not recognized sur Windows) — pas installé. Continuez ci-dessous.

Installer Node.js

Allez sur nodejs.org et téléchargez la version LTS (la « support à long terme » — l'option sûre et recommandée). Installez-la comme n'importe quel programme : ouvrez le fichier téléchargé et cliquez, en gardant les options par défaut. Après l'installation, fermez et rouvrez votre terminal pour qu'il prenne le nouveau logiciel, puis exécutez node --version à nouveau.

Qu'est-ce que Node.js ? C'est un runtime gratuit qui permet d'exécuter des programmes JavaScript sur votre ordinateur. Beaucoup d'outils de développement comme Harness sont distribués via son gestionnaire de paquets, npm. Pas besoin d'apprendre JavaScript pour ce tutoriel — Node.js alimente simplement les outils en arrière-plan.

Étape 2 — Installez et lancez le Web UI

La ligne magique. Dans votre terminal, exécutez :

npx @deepseek-ai/dsh web

Qu'est-ce que `npx` ? Quand vous exécutez npx <paquet>, il télécharge ce paquet (cela prend une ou deux minutes la première fois) et l'exécute. Cette ligne télécharge donc DeepSeek Harness et le démarre.

Ce qui devrait se passer : vous verrez des lignes de journal, et une ligne qui dit quelque chose comme :

DeepSeek Harness is running at: http://127.0.0.1:3080

Ce http://127.0.0.1:3080 est l'adresse du Web UI de Harness sur votre propre ordinateur. Gardez cette fenêtre de terminal ouverte — le serveur continue de tourner tant qu'elle est ouverte.

Ouvrez maintenant votre navigateur (Chrome, Edge, Safari…) et allez sur cette adresse : http://127.0.0.1:3080. Vous verrez l'écran d'accueil de DeepSeek Harness.

Que signifie `127.0.0.1` ? C'est l'adresse universelle de « cet ordinateur » — comme un numéro de téléphone pour votre propre machine. La partie :3080 est le port, comme une extension. Cette adresse ne fonctionne que sur votre machine ; personne d'autre ne peut y accéder.

Alternative : exécuter depuis les sources

Si vous préférez le code le plus récent, clonez le dépôt GitHub et construisez (nécessite pnpm, le frère rapide de npm) :

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
pnpm install
pnpm run build
pnpm dsh web

Étape 3 — Obtenez une clé API DeepSeek (si vous n'en avez pas)

Pour que Harness parle à un vrai modèle, il vous faut une clé. Une clé est une longue chaîne secrète — pensez-y comme un mot de passe pour l'usage d'IA.

1. 1Allez sur platform.deepseek.com (la plateforme développeurs de DeepSeek) et connectez-vous ou créez un compte.
2. 2Trouvez la page API Keys dans votre compte.
3. 3Cliquez sur Create API key (ou similaire), copiez la clé et rangez-la en lieu sûr — vous ne pourrez plus voir la clé complète après avoir quitté la page.

Gardez cette clé privée. Quiconque l'a peut dépenser votre quota (et dans la plupart des cas, votre argent).

Étape 4 — Configurez le modèle dans le Web UI

Le Web UI démarre sans aucun modèle configuré. Les changements de modèle prennent effet à la demande suivante — sans redémarrer le serveur.

1. 1Dans le Web UI de Harness (http://127.0.0.1:3080), ouvrez Paramètres → Modèles.
2. 2Trouvez la carte DeepSeek et collez votre clé API DeepSeek.
3. 3Cliquez sur Enregistrer.

La route DeepSeek devient utilisable immédiatement.

Pour la sécurité, la clé est stockée en écriture seule : après enregistrement, l'interface ne montre qu'un descripteur masqué, et le secret réel vit dans $DSH_HOME/.credentials.yaml (un fichier privé dans votre répertoire personnel).

Ajouter d'autres fournisseurs

Vous pouvez aussi utiliser des modèles d'autres entreprises — Anthropic ou OpenAI par exemple :

• Fournisseurs de catalogue — cliquez sur Ajouter un fournisseur et choisissez Anthropic, OpenAI ou un autre du catalogue installé. L'endpoint, le protocole et la liste de modèles sont préconfigurés.
• Fournisseurs personnalisés — cliquez sur Ajouter un fournisseur personnalisé pour une passerelle d'entreprise, un serveur auto-hébergé ou un endpoint compatible OpenAI. Fournissez un Provider ID en minuscules (permanent), une URL de base, un protocole API, une credential et au moins un modèle. Utilisez Récupérer les modèles disponibles pour sonder l'endpoint avant d'enregistrer.

Fournisseurs à credential native — Bedrock, Vertex, Azure et Codex nécessitent leurs propres credentials natives (clé AWS + région, projet ADC, api-version, OAuth). Saisir une clé API dans le champ générique ne les configure pas.

Modèles de vision sur un fournisseur personnalisé

Un modèle saisi à la main est traité comme texte seul jusqu'à preuve du contraire. Pour déclarer le support d'image sur un fournisseur personnalisé, éditez $DSH_HOME/settings.yaml :

llm-pi-ai:
  providers:
    my-gateway:
      apiKeyEnv: GATEWAY_API_KEY
      api: openai-completions
      baseURL: https://gateway.example/v1
      models:
        - id: legacy-chat
        - id: vision-preview
          input: [text, image]

input accepte text et image et s'applique à ce modèle uniquement. Pour un fallback sur toute la route, utilisez defaultInput: [text, image] au niveau du fournisseur. La route chat-completions de DeepSeek est texte seul et ne peut être configurée autrement.

Étape 5 — Choisissez un espace de travail

Un Web UI frais démarre sans espace de travail sélectionné — jusqu'à ce que vous en choisissiez un, la zone où vous tapez votre tâche est désactivée.

Qu'est-ce qu'un « espace de travail » ? C'est le dossier de votre ordinateur que l'agent est autorisé à toucher. Tout ce qu'il contient — fichiers, code, documents — peut être lu, modifié ou exécuté. Gardez-le sur un dossier de projet de confiance, pas tout votre ordinateur.

1. 1Cliquez sur Choisir l'espace de travail dans l'interface.
2. 2Ajoutez le répertoire du projet où vous avez lancé dsh.
3. 3Sélectionnez-le.

La zone de saisie s'allume et vous êtes prêt.

Étape 6 — Exécutez votre première tâche d'agent

1. 1Cliquez sur Démarrer une session (ou utilisez directement la zone de saisie).
2. 2Envoyez un prompt. Une bonne première tâche pour un dossier tout neuf :

> Summarize this repository and identify its main packages.

(Si votre dossier est vide ou n'est pas un projet, essayez quelque chose comme : *Créez un fichier hello.txt avec « Hello from DeepSeek Harness! » dedans.*)

1. 1Observez l'agent travailler. Il peut :

• Lire et modifier des fichiers de l'espace de travail
• Exécuter des commandes shell (avec un processus Bash persistant)
• Déléguer du travail à des sous-agents
• Maintenir un plan au fur et à mesure

Sous la politique de permissions active, le Web UI demandera une approbation avant toute opération qui l'exige — supprimer un fichier, installer un paquet, etc. C'est normal et conçu ainsi ; approuvez une par une.

Les quatre modes d'agent

Utilisez le sélecteur de modes de la composition de session :

La vue Trajectory

Chaque interaction du modèle — prompt du système, pensée, appels d'outils, résultats, dispatch de sous-agents, injections de contexte — est enregistrée comme un flux d'événements append-only dans le journal de session. La vue Trajectory permet de l'inspecter par source, et le même journal alimente la récupération, le fork, la recherche et la relecture complète. Parfaite pour savoir exactement ce que l'agent a fait et pourquoi.

Étape 7 — Aller plus loin : CLI headless

Outre le Web UI, dsh expose un mode d'entrée headless pour le scripting et le CI — une commande qui exécute une tâche de bout en bout sans navigateur, imprime la réponse finale et se termine :

dsh --profile headless "Inspect the repository and fix the failing tests."

Le profil headless s'auto-initialise au premier usage depuis le modèle livré.

Le launcher prend en charge quatre modes d'entrée :

Qu'est-ce qu'un « profil » ? Une configuration nommée : quels plugins, modèles et réglages utiliser. Le répertoire de profil contient un package.json (avec dépendances de plugins hors-arbre et le manifeste dsh.profile) et un cordis.patch.yml (votre propre couche de patch). L'arbre composé fusionne, dans l'ordre :

1. 1le patch de chaque bundle dans l'ordre de dsh.profile.bundles
2. 2le cordis.patch.yml du profil
3. 3le $DSH_HOME/cordis.patch.yml de niveau home
4. 4les surcouches --patch

Utilisez --dump-default-config et --dump-config pour inspecter l'arbre composé sans le démarrer.

Étape 8 — SDK Python (pour les programmeurs)

Si vous écrivez en Python et voulez intégrer un agent dans votre propre programme, DeepSeek publie un SDK officiel.

Prérequis

• Python 3.10 ou supérieur
• Linux x64/arm64 ou macOS 14+ en arm64
• Git (pour obtenir l'exemple)

Installer

git clone https://github.com/deepseek-ai/deepseek-harness.git
cd deepseek-harness
python -m venv .venv
. .venv/bin/activate
python -m pip install deepseek-harness-sdk

Le runtime installé inclut son propre Node.js — pas besoin de Node.js système.

Définir les credentials

export DEEPSEEK_API_KEY="sk-…"
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1     # avec un proxy
# export DSH_MODEL=deepseek-v4-flash
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

Exécuter l'exemple intégré

python examples/jsonrpc-agent/minimal.py \
  --workspace /absolute/path/to/workspace \
  --session-root /absolute/path/to/sessions \
  --session-id example-001 \
  "Inspect the repository and fix the failing tests."

Le script imprime la réponse finale de l'assistant. Le session-root reçoit un journal JSONL avec les requêtes de modèle et appels d'outils assemblés.

Utiliser le SDK dans votre propre programme

from pathlib import Path
from deepseek_harness import DeepSeekHarness

config    = Path("examples/jsonrpc-agent/minimal.cordis.yml").resolve()
workspace = Path("/absolute/path/to/workspace").resolve()
sessions  = Path("/absolute/path/to/sessions").resolve()

with DeepSeekHarness(
    provider     = "deepseek-official",
    model        = "deepseek-v4-flash",
    max_tokens   = 49_152,
    cwd          = str(workspace),
    session_root = str(sessions),
    cordis       = str(config),
) as harness:
    result = harness.run(
        "Inspect the repository and fix the failing tests.",
        session_id="example-001",
    )

print(result.final_response)

DeepSeekHarness démarre le runtime intégré paresseusement et le réutilise jusqu'à la sortie du gestionnaire de contexte. Réutiliser le même harness et le même session id préserve le processus Bash de la session, son répertoire de travail, ses variables exportées et ses fonctions shell. Utilisez un session id nouveau pour des tâches indépendantes ; réutilisez un id uniquement pour continuer la même conversation persistante.

Comprendre la composition de l'exemple

Note : cette composition omet l'identité du harness, le texte de prompt de l'espace de travail, les compétences, Bash à usage unique, les outils de tâche, la compaction et tous les autres plugins face au modèle. Elle utilise danger-full-access, donc exécutez-la uniquement dans un clon jetable ou un conteneur. Le backend PTY persistant nécessite un substrat de terminal POSIX, donc cette composition ne supporte pas les agents Windows.

Dépannage

Étapes suivantes

• Ajoutez plus de fournisseurs — Bedrock, Vertex, Azure, Codex et toute passerelle compatible OpenAI via Paramètres → Modèles
• Développez un plugin — la documentation docs/user/develop/basic/ vous guide pour créer votre propre plugin Cordis
• Référence du SDK Python — python/sdk/README.md couvre cycle de vie, résultats, notifications, sélection de runtime et configuration
• Cordis primer — docs/cordis-primer.md explique la syntaxe de composition au cœur de Harness

Résumé

Vous êtes passé de zéro à avoir votre propre agent d'IA en marche. Dans ce guide :

1. 1Vous avez appris ce que sont vraiment un terminal, Node.js, une clé API, un modèle et un agent
2. 2Vous avez installé dsh via npx (ou depuis les sources)
3. 3Vous avez créé une clé API DeepSeek et l'avez configurée dans Paramètres → Modèles
4. 4Vous avez choisi un espace de travail pour votre agent
5. 5Vous avez exécuté votre première tâche d'agent en session
6. 6Vous avez exploré les quatre modes et la vue Trajectory
7. 7Vous avez exécuté une session headless via CLI
8. 8Vous avez installé et utilisé le SDK Python

Tout dans DeepSeek Harness est un plugin — et tout est MIT et gratuit. Bienvenue dans le monde des agents.