Appel du SDK Python de DeepSeek Harness

L’interface Web est faite pour que les humains la regardent, mais si vous devez l’appeler depuis un programmedshÀ ce moment-là, ce qu’il faut, c’est le SDK.

Ce chapitre couvre le SDK Python : comment l’installer, comment exécuter les exemples intégrés du dépôt et comment l’appeler dans vos propres programmes.

Quel problème le SDK Python résout-il ?

Le SDK transforme dsh en un appel d’une seule ligne dans votre programme, plutôt qu’en une page dans un navigateur.

DeepSeekHarnessC’est la classe centrale du SDK Python, qui utilise un gestionnaire de contexte pour gérer le cycle de vie du runtime.

L’entrée dans le bloc with démarre paresseusement le runtime intégré ; la sortie le libère automatiquement, et run peut être appelé de façon répétée entre les deux.

Scénarios adaptés : tâches de traitement par lots, intégration de dsh dans votre propre produit et pilotage d’agents dans des tests.

Une fois le SDK installé, le runtime n’exige pas que le système fournisse Node.js — le processus Python embarque sa propre copie.

Prérequis

Le SDK a des exigences système explicites — vérifiez-les d’abord.

Installer le SDK

Clonez le dépôt pour obtenir des exemples exécutables, créez un environnement virtuel, puis installez le SDK et le runtime intégré de la même version.

$ 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

Un environnement virtuel isole le SDK des autres paquets Python du système — l'approche officiellement recommandée.

Après l'installation, le runtime ne nécessite pas que le système fournisse Node.js.

Exécuter les exemples intégrés du dépôt

Le dépôt inclut un exemple minimal.py ; parvenir à le faire fonctionner équivaut à vérifier l'ensemble du pipeline du SDK.

Définissez d'abord les identifiants dans l'environnement.

$ export DEEPSEEK_API_KEY=sk-your-key-here
# export DEEPSEEK_BASE_URL=http://127.0.0.1:8000/v1
# export DSH_MODEL=deepseek-v4-flash
# export DSH_SYSTEM_PROMPT='You are a helpful software engineer assistant.'

Si le modèle n'est pas fourni par le point de terminaison DeepSeek par défaut, mais via un proxy compatible OpenAI, vous devez également définir DEEPSEEK_BASE_URL.

Exécutez ensuite une tâche dans un espace de travail isolé et un répertoire de session.

$ 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 affichera la réponse finale de l'assistant.

Le répertoire de session reçoit des journaux JSONL qui incluent les requêtes de modèle assemblées et les appels d'outils.

Utiliser le SDK dans votre propre programme

L'exemple intégré dans le dépôt est en réalité un wrapper léger autour de l'appel SDK ci-dessous ; le cœur ne compte que deux étapes.

DeepSeekHarness démarre paresseusement le runtime intégré et continue de le réutiliser jusqu'à ce que le gestionnaire de contexte soit quitté.

Le même harness peut appeler run plusieurs fois à l'intérieur du bloc with, et le runtime ne démarre qu'une seule fois.

Réutiliser l'ID de session : préserver les processus Bash

C'est la règle du SDK la plus facile à négliger et la plus utile.

Réutiliser le même harness et le même ID de session préserve les processus Bash associés à cette session.

Y compris son répertoire de travail, ses variables exportées et ses fonctions shell — tout est conservé pour l'appel suivant.

Les tâches indépendantes doivent utiliser un nouvel identifiant de session ; ne réutilisez l'identifiant d'origine que lorsque l'appel suivant doit poursuivre la même conversation persistante.

Aperçu des combinaisons d'exemples

La combinaison derrière minimal.py est une configuration délibérément minimale ; passons en revue chaque élément pour voir ce qu'il fait.

Cette combinaison omet des plugins tels que l'identité du harness, le texte d'invite de l'espace de travail, les compétences, Bash one-shot, les outils de tâches et la compression du contexte.

Le flux d'appel global est le suivant.

Périmètre de danger-full-access

Cette combinaison d'exemple utilise le préréglage d'autorisation danger-full-access, et vous devez bien comprendre ses limites.

danger-full-access ne peut s'exécuter que dans une copie de travail jetable ou un conteneur.

Bash et l'éditeur peuvent modifier n'importe quel chemin accessible au processus d'exécution ; il n'y a pas de bac à sable comme filet de sécurité.

Le backend PTY persistant nécessite un environnement de terminal POSIX, donc cette combinaison ne prend pas en charge les agents Windows.

En d'autres termes, avant de l'utiliser pour exécuter de vrais projets, confirmez d'abord que cela ne vous dérange pas si cet environnement est cassé.

Auto-test du résumé

Résumé en une phrase : le SDK Python encapsule le runtime avec le gestionnaire de contexte DeepSeekHarness et envoie des tâches via run(prompt, session_id).

Testez votre compréhension avec trois questions rapides.

1. Qu'est-ce qui est préservé lorsqu'on réutilise le même ID de session ?
2. Dans quelles situations devez-vous utiliser un nouvel ID de session ?
3. Quels outils minimal.py active-t-il par défaut pour le modèle ?

Réponse de référence : le processus Bash de cette session est préservé, y compris le répertoire de travail, les variables exportées et les fonctions shell.

Utilisez un nouvel ID pour les tâches indépendantes ; ne le réutilisez que lorsque vous devez poursuivre la même conversation persistante.

Ne persister que les deux outils : bash et str_replace_editor