Deep Agents Einführungstutorial

Deep Agents ist ein voll ausgestattetes Agent-Entwicklungsframework, das offiziell von LangChain eingeführt wurde und speziell für komplexe Aufgaben, lang laufende Prozesse, mehrstufige Planung und Multi-Agent-Kollaborationsszenarien entwickelt wurde.

Im Vergleich zu traditionellen Agents, bei denen Entwickler Komponenten wie Prompt, Tool, Memory und Workflow manuell zusammenstellen müssen, bringt Deep Agents bereits Kernfähigkeiten wie Aufgabenplanung, Dateisystem, Sub-Agent-Orchestrierung, Kontextkomprimierung und Speicherverwaltung mit. Dadurch können sich Entwickler stärker auf die Geschäftslogik konzentrieren statt auf die Einrichtung der zugrunde liegenden Architektur.

Dieses Tutorial richtet sich an Entwickler ohne Vorkenntnisse. Es führt Sie Schritt für Schritt von der Installation und Konfiguration über die zentralen Funktionsmechanismen von Deep Agents und verwendet die DeepSeek-API, um ein echtes, ausführbares KI-Agent-Projekt zu erstellen.

Was sind Deep Agents?

Deep Agents kann als erweitertes Agent-Framework (Agent Harness) verstanden werden, das für Produktionsumgebungen entwickelt wurde.

Es wird offiziell definiert als: ein Agent-Runtime-Framework mit vollständiger Infrastruktur, nicht nur eine einfache LLM + Tool-Aufrufschleife.

Nach der Installation können Sie die folgenden Fähigkeiten direkt nutzen, ohne zusätzliche Entwicklung:

Automatische Aufgabenplanung (Planning)
Dateisystem-Lese-/Schreibzugriff (Filesystem)
Sub-Agent-Zusammenarbeit (Sub Agents)
Kontextkomprimierung und -verwaltung (Context Management)
Ausführung lang laufender Aufgaben (Long Running Tasks)
Menschliche Genehmigung (Human-in-the-Loop)
Persistentes Gedächtnis (Memory)
Streaming-Ausgabe (Streaming)

Designziele von Deep Agents

Traditionelle Agents verwenden typischerweise das ReAct-Muster: Benutzereingabe → LLM-Reasoning → Tool aufrufen → LLM-Reasoning → Tool aufrufen → Ergebnis ausgeben.

Wenn der Aufgabenumfang klein ist, funktioniert dieses Muster gut. Doch mit steigender Aufgabenkomplexität (zum Beispiel automatisches Erstellen von Marktforschungsberichten, Analysieren von Finanzberichten mehrerer Unternehmen oder Schreiben einer vollständigen Projekt-Codebasis) treten nach und nach die folgenden Probleme auf:

Das Kontextfenster wächst schnell und überschreitet die Modellgrenzen
] Übermäßig lange Reasoning-Ketten führen zu Leistungseinbußen
Der Agent vergisst leicht zuvor abgeschlossene Arbeit
Fehlende Isolation zwischen mehreren Aufgaben, was zu gegenseitiger Beeinträchtigung führt
Die Tool-Aufruflogik wird zunehmend komplex und schwer wartbar

Das Kernziel von Deep Agents ist es, diese Engineering-Probleme in komplexen Aufgabenszenarien zu lösen.

Beziehung zu LangChain und LangGraph

] Viele Anfänger verwechseln leicht die Positionierung dieser drei Projekte; tatsächlich befinden sie sich auf unterschiedlichen Abstraktionsebenen.

Framework	Ebenen-Einordnung	Kernaufgaben	Anwendbare Szenarien
LangChain	Basiskomponentenschicht.	Stellt KI-Basiskomponenten wie Model, Prompt, Tool, Retriever und Output Parser bereit	Grundlegende Fähigkeit zum Erstellen einzelner Agents oder KI-Anwendungen
LangGraph	Laufzeitschicht	Bietet Zustandsverwaltung, Workflow-Orchestrierung, Knoten und Kanten sowie Checkpoint-Persistenzfähigkeiten	Für komplexe Szenarien, die benutzerdefinierte Graphstrukturen und Ausführungsabläufe erfordern
Deep Agents	Anwendungsframework-Schicht.	Kapselt produktionsreife Fähigkeiten auf Basis von LangGraph, wie Planung, Dateisystem, Sub-Agents, Memory und Kontextkomprimierung	Komplexe mehrstufige Agents schnell erstellen, ohne die Architektur von Grund auf neu zu entwerfen

Die drei schließen sich nicht gegenseitig aus, sondern können zusammen verwendet werden: LangChain stellt Bausteine bereit, LangGraph ist das Engineering-Framework, das die Bausteine organisiert, und Deep Agents ist eine sofort einsatzbereite High-Level-Anwendungsschicht darüber. Jeder LangGraphCompiledStateGraphkann als Subagent an Deep Agents übergeben werden, und die drei Ebenen können flexibel gemischt werden.

Überblick über Kernkompetenzen

Deep Agents wird mit der folgenden integrierten Middleware geliefert, die ohne zusätzliche Konfiguration sofort einsatzbereit ist:

Fähigkeit	Beschreibung	Kernkomponenten
Aufgabenplanung	Verwende integrierte`write_todos`Tools, um komplexe Aufgaben in geordnete Schritte zu zerlegen	TodoListMiddleware
Virtuelles Dateisystem	Dateien lesen und schreiben, große Tool-Ausgaben auf die Festplatte auslagern und so das Kontextfenster sparen	FilesystemMiddleware
Sub-Agent	Teilaufgaben an dedizierte Sub-Agenten mit unabhängigen Kontextfenstern delegieren	SubAgentMiddleware
Kontextkomprimierung	Historische Nachrichten automatisch zusammenfassen, um das Kontextlimit des Modells nicht zu überschreiten	SummarizationMiddleware
Human-in-the-loop	Vor kritischen Tool-Aufrufen pausieren, um auf menschliche Genehmigung zu warten	HumanInTheLoopMiddleware
Langzeitgedächtnis	Sitzungsübergreifender persistenter Speicher auf Basis von LangGraph Store	MemoryMiddleware
Skills	Wiederverwendbares Domänenwissen und Anweisungssätze bei Bedarf laden	SkillsMiddleware

Installation

Deep Agents wird auf PyPI unter dem Paketnamendeepagents veröffentlicht。

Empfohlen wird die Verwendung vonuv-Installation, die schneller ist; du kannst auch das traditionellepip verwenden。

Mit uv installieren (empfohlen)

uv init
uv add deepagents tavily-python
uv sync

Mit pip installieren.

pip install deepagents tavily-python

Mit DeepSeek API installieren

DeepSeek ist mit der OpenAI-Schnittstelle kompatibel, daher musst du zusätzlichlangchain-openai installieren。

pip install deepagents langchain-openai

Die einzige Anforderung, die Deep Agents an das Modell stellt, ist, dass das ModellTool Callingunterstützt. Die Serien DeepSeek V3 und DeepSeek R1 unterstützen es beide, du kannst es also bedenkenlos verwenden.

Konfigurationsanleitung

create_deep_agentEs ist die Kernfunktion zum Erstellen eines Agenten und unterstützt die folgende Parameterkonfiguration.

Parameters	Type	Erforderlich	Beschreibung	Standardwert
`model`	str oder Modellinstanz	nein	Modell-String, im Format`provider:model-name`, oder übergib direkt ein initialisiertes Modellobjekt	`anthropic:claude-sonnet-4-6`
`tools`	Liste	nein	Liste benutzerdefinierter Tool-Funktionen oder LangChain-Tool-Objekte	Keine
`system_prompt`	str oder SystemMessage	nein	Benutzerdefinierter System-Prompt, der die Rolle und das Verhalten des Agenten definiert	Keine
`backend`	BackendProtocol	nein	Backend des virtuellen Dateisystems, bestimmt den Dateispeicherort	StateBackend
`subagents`	Liste	nein	Liste der Sub-Agent-Definitionen, die für die Aufgaben-Delegation verwendet werden	Keine
`memory`	Liste	nein	Liste der beim Start geladenen AGENTS.md-Dateipfade	Keine
`skills`	Liste	nein	Liste der bei Bedarf geladenen Skills-Verzeichnispfade	Keine
`permissions`	Liste	nein	Regeln zur Zugriffssteuerung auf Ebene der Dateisystempfade	Keine
`interrupt_on`	dict	nein	Gibt an, welche Tool-Aufrufe eine manuelle Genehmigung erfordern; muss mit Checkpointer verwendet werden	Keine
`checkpointer`	Checkpointer	nein	Checkpointer für Zustandspersistenz, muss für mehrstufige Konversationen oder HITL festgelegt werden	Keine
`store`	BaseStore	nein	Sitzungsübergreifendes Langzeitspeicher-Backend	Keine
`response_format`	ResponseFormat	nein	Schema-Definition für strukturierte Ausgabe	Keine
`middleware`	Liste	nein	Benutzerdefinierte Middleware, die am Ende des Standard-Middleware-Stapels angehängt wird	()
`debug`	bool	nein	Debug-Modus aktivieren, detaillierte Protokolle ausgeben	False

Vergleich der Dateisystem-Backends

Deep Agents bietet mehrere Backends, um zu steuern, wie der Agent Dateien liest und schreibt.

Backend	Speicherort	Sitzungsübergreifende Persistenz	Anwendungsfall
StateBackend	Innerhalb des LangGraph-Graphzustands	Nein (gültig innerhalb desselben Threads)	Standard, für lokale Entwicklung und einfache Szenarien
FilesystemBackend	Lokale Festplatte	Ja	Erfordert echtes Lesen/Schreiben lokaler Dateien, mit Vorsicht verwenden
StoreBackend	LangGraph Store	Ja	Persistenz von Multi-Turn-Konversationen, Thread-übergreifende Freigabe
LocalShellBackend	Lokale Festplatte + Shell	Ja	Erfordert die Ausführung von Shell-Befehlen, nur in vertrauenswürdigen Umgebungen
CompositeBackend	Leitet an mehrere Backends weiter	Hängt vom untergeordneten Backend ab	Feingranulare Steuerung der Speicherrichtlinien für verschiedene Verzeichnisse

Für Anfänger ist die einfache Verwendung des Standard-StateBackendausreichend.FilesystemBackendundLocalShellBackendErmöglicht dem Agenten, direkt auf Ihrem lokalen Dateisystem zu arbeiten; konfigurieren Sie die Berechtigungen vor der Verwendung streng.

Schnellstart

Dieser Abschnitt zeigt, wie Sie mit minimalem Code einen ausführbaren Deep Agent erstellen.

DeepSeek-API-Schlüssel konfigurieren

DeepSeek ist mit dem API-Format von OpenAI kompatibel, und sowohl der API-Schlüssel als auch die Basis-URL müssen festgelegt werden.

export OPENAI_API_KEY="sk-your-deepseek-api-key"
export OPENAI_BASE_URL="https://api.deepseek.com"
export TAVILY_API_KEY="your-tavily-api-key"

DeepSeek-API-Schlüssel kann beiplatform.deepseek.combeantragt werden. Legen Sie die UmgebungsvariableOPENAI_BASE_URLso fest, dass sie auf die Adresse von DeepSeek zeigt, und LangChain leitet Anfragen automatisch dorthin weiter.

TAVILY_API_KEY muss auf der offiziellen Tavily-Websitehttps://www.tavily.com/ beantragt werden, um einen Schlüssel im Format tvly-xxxxxxxx zu generieren.

Einfachstes Beispiel: Hello-World-Agent

Erstellen Sie einen Agenten mit einem benutzerdefinierten Tool und senden Sie die erste Nachricht an DeepSeek.

example

# Dateipfad: hello_agent.py

import os
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

# ChatOpenAI verwenden und base_url auf DeepSeek setzen; das ist der direkteste Weg zur Verbindung
model = ChatOpenAI(
model="deepseek-v4-flash", # Erforderlich: Modellname
api_key=os.environ["OPENAI_API_KEY"], # Erforderlich: DeepSeek-API-Schlüssel
base_url="https://api.deepseek.com", # Erforderlich: DeepSeeks OpenAI-kompatibler Endpunkt
)

# Ein einfaches benutzerdefiniertes Tool definieren; der Docstring der Funktion dient als Tool-Beschreibung
def get_weather(city: str) -> str:
"""Fragt das Wetter für eine angegebene Stadt ab."""
# In einem echten Projekt würden Sie hier eine echte Wetter-API aufrufen
return f"{city} ist heute sonnig, 25°C, geeignet für einen Ausflug."

# Einen Agenten erstellen und die Modellinstanz und Tool-Liste übergeben
agent = create_deep_agent(
model=model,
tools=[get_weather],
system_prompt="Du bist ein freundlicher Assistent, der Wetterinformationen abfragen kann.",
)

# Den Agenten aufrufen; messages akzeptiert das Nachrichtenformat im OpenAI-Stil
result = agent.invoke({
"messages": [{"role": "user", "content": "Wie ist das Wetter heute in Peking?"}]
})

# Die endgültige Antwort des Agenten ausgeben
print(result["messages"][-1].content)

# 运行脚本
python hello_agent.py

Ausgabe:

Peking ist heute **sonnig**, mit einer Temperatur von **25°C**, sehr gut für einen Ausflug geeignet. ☀️

Hinweis: Der Agent gibt eine vollständige Liste von Nachrichten zurück (messages), und die endgültige Antwort befindet sich am Ende der Liste, d. h.,result["messages"][-1].content。

Detaillierte Verwendung

Dieser Abschnitt verwendet mehrere reale Szenarien, um die Kernfähigkeiten von Deep Agents schrittweise zu demonstrieren.

Verwenden Sie DeepSeek R1 für Reasoning-Aufgaben.

DeepSeek R1 ist ein reasoning-optimiertes Modell, geeignet für Aufgaben, die komplexe Analyse erfordern.

Beispiel

# Dateipfad: reasoning_agent.py

import os
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

# DeepSeek R1: Entwickelt für komplexes Reasoning
model = ChatOpenAI(
model="deepseek-v4-pro", # DeepSeek-Denkmodell
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
)

# Beispiel für ein Mathematik-Berechnungswerkzeug
def calculate(expression: str) -> str:
"""Berechne sicher einen mathematischen Ausdruck und gib das Berechnungsergebnis zurück."""
try:
# Hinweis: In Produktionsumgebungen sollte eine sicherere Bibliothek zur Ausdrucksauswertung verwendet werden.
result = eval(expression, {"__builtins__": {}}, {})
return f"Berechnungsergebnis: {expression} = {result}"
except Exception as e:
return f"Berechnungsfehler: {str(e)}"

agent = create_deep_agent(
model=model,
tools=[calculate],
system_prompt="Du bist ein Experte für mathematische Analyse und geschickt darin, komplexe Probleme zu zerlegen und sie Schritt für Schritt zu lösen.",
)

result = agent.invoke({
"messages": [{"role": "user", "content": "Berechne die Summe aller ungeraden Zahlen von 1 bis 100 und überprüfe das Ergebnis."}]
})

print(result["messages"][-1].content)

Ausgabe der Ausführung:

再换一种方法做交叉验证：

- 1 到 100 所有整数之和：\( \frac{100 \times 101}{2} = 5050 \)
- 1 到 100 的偶数之和：\( 2 + 4 + \cdots + 100 = 2 \times \frac{50 \times 51}{2} = 2550 \)
- 奇数之和：\( 5050 - 2550 = 2500 \)

两种方法结果一致。

---

**结论**：1 到 100 的所有奇数之和为 **2500**。

**推导回顾**：
- 奇数序列首项 1，末项 99，项数 \( \frac{99-1}{2}+1 = 50 \)
- 等差数列求和：\( S = \frac{n(a_1 + a_n)}{2} = \frac{50 \times (1+99)}{2} = 2500 \)

Benutzerdefinierter System-Prompt

Durchsystem_promptDie Parameter definieren die Rolle des Agenten, die Aufgabenziele und die Verhaltensnormen.

Beispiel

# Dateipfad: custom_prompt_agent.py

import os
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
model="deepseek-v4-flash",
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
)

# Benutzerdefinierter System-Prompt: Definieren Sie die Identität, Verantwortlichkeiten und Verhaltensrichtlinien des Agenten.
code_review_instructions = """Du bist ein leitender Python-Ingenieur mit Fokus auf Code-Review.

Ihre Verantwortlichkeiten:
- Prüfen Sie die Lesbarkeit, Leistung und Sicherheit des Codes
- Weisen Sie auf potenzielle Fehler und Verbesserungsvorschläge hin
- Geben Sie konkrete Änderungsbeispiele an

Antwortformat:
1. Gesamtbewertung (1-10)
2. Liste der Hauptprobleme
3. Konkrete Verbesserungsvorschläge (mit geänderten Codeausschnitten)
"""

agent = create_deep_agent(
model=model,
system_prompt=code_review_instructions,
)

# Reichen Sie ein Stück Code zur Überprüfung ein
code_to_review = """
def find_user(users, name):
for i in range(len(users)):
if users[i]['name'] == name:
return users[i]
return None
"""

result = agent.invoke({
"messages": [{"role": "user", "content": f"Bitte überprüfen Sie den folgenden Code:\n```python{code_to_review}```"}]
})

print(result["messages"][-1].content)

Streaming-Ausgabe

Für Szenarien, die eine Echtzeit-Fortschrittsanzeige erfordern, können SiestreamDie Methode empfängt die Agent-Ausgabe Stück für Stück.

Beispiel

# Dateipfad: streaming_agent.py

import os
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

model = ChatOpenAI(
model="deepseek-v4-flash",
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
)

agent = create_deep_agent(
model=model,
system_prompt="Du bist ein Experte für technisches Schreiben und geschickt darin, klare und verständliche technische Dokumentation zu verfassen.",
)

# Die stream-Methode gibt einen Generator zurück und liefert jeweils einen Event-Chunk.
for chunk in agent.stream({
"messages": [{"role": "user", "content": "Schreibe eine kurze Einführung in Python-Dekoratoren."}]
}):
# chunk ist ein Dictionary, das inkrementelle Nachrichten enthält
if "messages" in chunk:
for msg in chunk["messages"]:
if hasattr(msg, "content") and msg.content:
print(msg.content, end="", flush=True)

print() # Abschließender Zeilenumbruch

Multi-Turn-Dialog (mit Checkpoints)

Zusammen mitMemorySaverCheckpoints können Sie einen zustandsbehafteten Dialog über mehrere Turns hinweg erreichen.

example

# Dateipfad: multi_turn_agent.py

import os
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import MemorySaver # In-Memory-Checkpoint, Daten gehen nach einem Neustart verloren.

model = ChatOpenAI(
model="deepseek-v4-flash",
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
)

# MemorySaver speichert den Konversationszustand im Speicher, der nach Prozessende verloren geht.
# In der Produktion wird die Verwendung von SqliteSaver oder PostgresSaver empfohlen
checkpointer = MemorySaver()

agent = create_deep_agent(
model=model,
system_prompt="Du bist ein hilfsbereiter Programmierassistent.",
checkpointer=checkpointer, # Muss übergeben werden, sonst können Multi-Turn-Konversationen sich nicht an den Kontext erinnern
)

# thread_id ist die eindeutige Kennung eines Konversations-Threads; derselbe thread_id teilt denselben Kontext
config = {"configurable": {"thread_id": "example-session-001"}}

# Erste Runde
result1 = agent.invoke(
{"messages": [{"role": "user", "content": "Mein Name ist EXAMPLE, und ich lerne Python."}]},
config=config,
)
print("Antwort der ersten Runde:", result1["messages"][-1].content)

# Zweite Runde: Der Agent kann sich an die Informationen der vorherigen Runde erinnern
result2 = agent.invoke(
{"messages": [{"role": "user", "content": "Wie ist mein Name? Was lerne ich?"}]},
config=config,
)
print("Antwort der zweiten Runde:", result2["messages"][-1].content)

First reply:你好，EXAMPLE！很高兴认识你，Python 是一门非常适合初学者的语言...
Second reply:你叫 EXAMPLE，你正在学习 Python！...

Die Rolle von thread_id:Dieselbethread_idAlle Aufrufe darunter teilen dieselbe Konversationshistorie. Unterschiedlichethread_idsind voneinander isoliert und stören sich nicht. Man kann es sich wie eine "Konversations-Raumnummer" vorstellen.

Umfassende Demo: Recherchebericht-Agent

Dieser Abschnitt demonstriert einen vollständigen Recherchebericht-Agenten, der DeepSeek V3 als Hauptmodell verwendet, benutzerdefinierte Suchwerkzeuge integriert und die Verwendung von Sub-Agenten demonstriert.

Szenariobeschreibung

Wir werden einen Agenten erstellen, der das Recherchethema des Benutzers entgegennimmt, Aufgaben automatisch aufteilt, Suchwerkzeuge aufruft, um Informationen zu sammeln, und schließlich einen strukturierten Bericht ausgibt.

Beispiel

# Dateipfad: research_agent_demo.py
# Demo: Aufbau eines Recherchebericht-Agenten mit DeepSeek API + Deep Agents
# Abhängigkeitsinstallation: pip install deepagents langchain-openai requests

import os
import json
from tavily import TavilyClient
from typing import Literal
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import MemorySaver

# ──────────────────────────────────────────
# 1. DeepSeek-Modell initialisieren
# ──────────────────────────────────────────
main_model = ChatOpenAI(
model="deepseek-v4-flash", # Starke umfassende Fähigkeiten, geeignet für Planung und Schreiben
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
temperature=0.3, # Optional: Zufälligkeit verringern, um den Bericht präziser zu machen
)
# Tavily-Client initialisieren (für Suchwerkzeuge)
tavily_client = TavilyClient(
api_key=os.environ["TAVILY_API_KEY"]
)
# ──────────────────────────────────────────
# 2. Tavily-Suchwerkzeug definieren
# ──────────────────────────────────────────
def web_search(
query: str,
max_results: int = 5,
) -> str:
"""Tavily nutzen, um Internetinformationen zu durchsuchen"""

try:
response = tavily_client.search(
query=query,
max_results=max_results,
search_depth="advanced",
include_answer=True,
include_raw_content=False,
)

lines = []

# KI-zusammengefasste Antwort
if response.get("answer"):
lines.append(f"Zusammenfassung: {response['answer']}\n")

# Suchergebnisse
for idx, item in enumerate(response.get("results", []), start=1):
lines.append(
f"""
[{idx}] {item.get('title', '')}
URL: {item.get('url', '')}
Inhalt: {item.get('content', '')}
""".strip()
)

return "\n\n".join(lines)

def format_report(title: str, sections: str) -> str:
"""Organisieren Sie den Rechercheinhalt in einem Bericht im Markdown-Format.

Argumente:
title: Berichtstitel
sections: Inhalt jedes Abschnitts, als JSON-String dargestellt, Format: {"Kapitelname": "Inhalt"}
"""
try:
data = json.loads(sections)
lines = [f"# {title}\n"]
for section_name, content in data.items():
lines.append(f"## {section_name}\n")
lines.append(f"{content}\n")
return "\n".join(lines)
except Exception as e:
return fFormatierungsfehler: {str(e)}

# ──────────────────────────────────────────
# 3. Definieren Sie einen dedizierten Sub-Agenten (Experte für Informationsintegration)
# Der Sub-Agent hat ein unabhängiges Kontextfenster und vermeidet eine Aufblähung des Kontexts des Haupt-Agenten
# ──────────────────────────────────────────
report_writer_subagent = {
"name": "report-writer", # Erforderlich: eindeutiger Name des Sub-Agenten
"description": Ein professioneller Assistent zum Verfassen von Berichten, zuständig für die Integration von Recherchematerialien in klar strukturierte Berichte., # Erforderlich: Der Haupt-Agent verwendet diese Beschreibung, um zu entscheiden, wann Aufgaben delegiert werden
"system_prompt": Sie sind ein professioneller Experte für das Verfassen von Berichten. Nach Erhalt der Recherchematerialien organisieren Sie diese bitte zu einem Bericht, der aus drei Teilen besteht: Zusammenfassung, Hauptinhalt und Fazit, in klarer und prägnanter Sprache.,
"tools": [format_report], # Optional: spezifische Tools des Sub-Agenten
# Wenn kein Modell angegeben ist, wird das Modell des Haupt-Agenten geerbt.
}

# ──────────────────────────────────────────
# 4. Deep Agent konfigurieren und erstellen
# ──────────────────────────────────────────
checkpointer = MemorySaver()

research_instructions = Sie sind ein professioneller Rechercheassistent mit Spezialisierung auf tiefgehende Recherche und Berichterstellung.

Wenn der Benutzer ein Recherchethema angibt, sollten Sie:
1. Verwenden Sie das Tool web_search, um nach relevanten Informationen zu suchen (suchen Sie mindestens 2-3 Mal, aus verschiedenen Blickwinkeln).
2. Organisieren Sie die gesammelten Daten und fassen Sie sie zusammen
3. Delegieren Sie das Schreiben des endgültigen Berichts an den report-writer Sub-Agenten
4. Geben Sie den vollständigen Bericht an den Benutzer aus.

Hinweis: Verwenden Sie für jede Suche unterschiedliche Schlüsselwörter, um umfassendere Informationen zu erhalten.
"""

agent = create_deep_agent(
model=main_model,
tools=[web_search], # Für den Haupt-Agenten verfügbare Tools
system_prompt=research_instructions,
subagents=[report_writer_subagent], # Sub-Agent registrieren
checkpointer=checkpointer,
)

# ──────────────────────────────────────────
# 5. Agent ausführen
# ──────────────────────────────────────────
print("Recherche läuft, bitte warten..."\n")

result = agent.invoke(
{
"messages": [{
"role": "user",
"content": Bitte helfen Sie mir zu recherchieren, was LangGraph ist und seine wichtigsten Anwendungsszenarien.
}]
},
config={"configurable": {"thread_id": "example-research-001"}}
)

print("=" * 60)
print("Recherchebericht")
print("=" * 60)
print(result["messages"][-1].content)

正在研究中，请稍候...

============================================================
研究报告
============================================================
# LangGraph 研究报告

## 摘要
LangGraph 是 LangChain 团队推出的一个用于构建有状态、多角色 LLM 应用的框架...

## 主要内容
### 核心概念
LangGraph 将 Agent 的执行流程建模为一张有向图...

### 主要应用场景
1. 多步骤推理任务
2. 人机协作（Human-in-the-loop）工作流
3. 多 Agent 协作系统
...

## 结论
LangGraph 是构建生产级 Agent 应用的重要工具...

Human-in-the-loop-Beispiel

Für sensible Vorgänge (z. B. Löschen von Dateien, Senden von E-Mails) kann der Agent so konfiguriert werden, dass er pausiert und vor der Ausführung auf eine manuelle Bestätigung wartet.

Beispiel

# Dateipfad: hitl_agent.py
# Human-in-the-loop: Lassen Sie den Agenten vor der Ausführung gefährlicher Operationen eine menschliche Genehmigung anfordern

import os
from langchain.tools import tool
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import MemorySaver
from langgraph.types import Command

model = ChatOpenAI(
model="deepseek-v4-flash",
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
)

# Verwenden Sie den @tool-Dekorator, um Tools zu definieren (erfordert das langchain-Paket)
@tool
def delete_file(path: str) -> str:
"""Löscht die Datei am angegebenen Pfad."""
# In tatsächlichen Projekten wird hier os.remove(path) aufgerufen.
return f"Datei {path} wurde gelöscht."

@tool
def read_file(path: str) -> str:
"""Liest den Inhalt der Datei am angegebenen Pfad."""
return fInhalt der Datei {path}: (Beispielinhalt)

# interrupt_on konfiguriert, welche Tools eine manuelle Genehmigung erfordern
# True bedeutet erlauben: Genehmigung, Bearbeiten von Parametern, Ablehnung, Senden benutzerdefinierter Antworten
# False bedeutet, dass keine Genehmigung erforderlich ist
# dict ermöglicht eine feingranulare Steuerung der erlaubten Operationstypen
checkpointer = MemorySaver() # HITL muss mit einem Checkpointer verwendet werden

agent = create_deep_agent(
model=model,
tools=[delete_file, read_file],
interrupt_on={
"delete_file": True, # Löschvorgang: erfordert einen vollständigen Genehmigungsprozess
"read_file": False, # Lesevorgang: keine Genehmigung erforderlich
},
checkpointer=checkpointer,
)

config = {"configurable": {"thread_id": "example-hitl-001"}}

# Erster Aufruf: Agent pausiert bei der Ausführung von delete_file
print("Agent wird gestartet...")
result = agent.invoke(
{"messages": [{"role": "user", "content": "Bitte löschen Sie die Datei /tmp/test.txt."}]},
config=config,
)

# Prüfen, ob eine ausstehende Genehmigungsunterbrechung vorliegt
for msg in result.get("messages", []):
print(fAgent-Nachricht: {msg.content if hasattr(msg, 'content') else msg})

# Ausführung fortsetzen: Genehmigungsentscheidung übergeben
# "approve" bedeutet, die Ausführung des Tools zu genehmigen
# "reject" bedeutet ablehnen; der Agent führt das Tool nicht aus
print("\n"Benutzergenehmigung: Löschvorgang genehmigen")
final_result = agent.invoke(
Command(resume={"decision": "approve"}),
config=config,
)
print("Endergebnis:", final_result["messages"][-1].content)

Wie interrupt_on funktioniert:Wenn der Agent im Begriff ist, ein markiertes Tool aufzurufen, löst LangGraph eine Unterbrechung ausinterrupt, wodurch die Ausführung des Agenten pausiert wird. Sie könnenCommand(resume=...)das Genehmigungsergebnis übergeben, um die Ausführung fortzusetzen.

Häufig gestellte Fragen

Im Folgenden finden Sie häufig gestellte Fragen und Überlegungen zur Verwendung von Deep Agents.

Wie entscheidet man zwischen der Verwendung von Deep Agents oder der direkten Verwendung von LangChain/LangGraph?

Szenario	Empfohlene Wahl	Grund
Benötigt Planung, Dateilesen/-schreiben, Unteragenten, Kontextkomprimierung	Deep Agents	Diese Fähigkeiten sind sofort einsatzbereit, Sie müssen sie nicht selbst zusammenbauen
Benötigt leichtgewichtige Kapselung, nur die Tool-Aufrufschleife	LangChain create_agent	Leichter als Deep Agents, keine integrierte Middleware
Benötigt eine benutzerdefinierte Graphstruktur; die Schleife ist keine Standard-Tool-Aufrufschleife	LangGraph	Logik von Graphknoten und -kanten vollständig anpassen
LangGraph CompiledStateGraph als Unteragent	Gemischte Verwendung	Sie können einen benutzerdefinierten Graph als Unteragenten an Deep Agents übergeben

Empfehlungen zur DeepSeek-Modellauswahl

Modell	Modell-String	Funktionen	Anwendbare Szenarien
deepseek-v4-flash	`deepseek-v4-flash`	Starke Gesamtfähigkeiten, hohe Geschwindigkeit, niedriger Preis	Allgemeine Aufgaben, Alltagsgespräche, Schreiben
deepseek-v4-pro	`deepseek-v4-pro`	Starke Schlussfolgerungsfähigkeit, integrierte Gedankenkette	Mathematik, Code, komplexe logische Schlussfolgerungen

Was ist zu tun, wenn der Agent ein Tool aufruft und kein Ergebnis zurückgegeben wird?

Der Rückgabewert einer Tool-Funktion muss eine Zeichenfolge oder ein Typ sein, der in eine Zeichenfolge serialisiert werden kann.

Wenn ein Tool ein komplexes Objekt zurückgibt (z. B. ein dict oder list), wird empfohlen,json.dumps(result, ensure_ascii=False)es vor der Rückgabe zu konvertieren.

Wie kann der Agent jeweils nur auf bestimmte Dateien zugreifen?

Verwenden SiepermissionsParameter zum Konfigurieren der Dateisystemzugriffsberechtigungen, mit denen präzise gesteuert werden kann, dass der Agent nur angegebene Pfade liest und schreibt.

example

from deepagents import create_deep_agent
from deepagents.permissions import FilesystemPermission
from langchain_openai import ChatOpenAI
import os

model = ChatOpenAI(
model="deepseek-v4-flash",
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
)

agent = create_deep_agent(
model=model,
permissions=[
FilesystemPermission(path="/workspace/", read=True, write=True), # Lesen und Schreiben des Arbeitsverzeichnisses erlauben
FilesystemPermission(path="/secrets/", read=False, write=False), # Zugriff auf sensible Verzeichnisse verbieten
],
)

Wie werden der Standard-Systemprompt des Agenten und mein Prompt zusammengeführt?

Der Prompt von Deep Agents wird in einer festen Reihenfolge aus vier Teilen zusammengesetzt:

USER(Ihr system_prompt) →BASE(SDK-Standardprompt) →SUFFIX(modellherstellerspezifische Anpassungen)

Ihr Prompt steht immer ganz vorne und wird nicht überschrieben. Der Standardprompt des SDK erklärt dem Modell, wie Planungs- und Dateitools verwendet werden, sodass Sie ihn in den meisten Fällen nicht selbst neu schreiben müssen.

Fehler, zu denen Anfänger neigen.

Häufiger Fehler 1:Vergessen, einen Checkpointer zu übergebencheckpointer. Wenn Sie Human-in-the-loop (interrupt_on) oder Multi-Turn-Konversationen verwenden,müssen Sieeinen Checkpointer übergeben, andernfalls kann der Status nicht gespeichert werden und der Agent meldet einen Fehler.

Häufiger Fehler 2:Tool-Funktionen haben keine Docstrings. Deep Agents verwendet den Docstring der Funktion als Tool-Beschreibung, damit das Modell weiß, wann es das Tool aufrufen soll. Bei einem Tool ohne Docstring weiß das Modell möglicherweise nicht, wann es aufgerufen werden soll, oder weigert sich sogar, es zu verwenden.

Häufiger Fehler 3:Direktes Ändernselfvon Attributen in Middleware. Die Sub-Agents und gleichzeitigen Vorgänge des Agents können parallel ablaufen, und die direkte Änderung von Attributen der Middleware-Instanz kann zu Race Conditions führen. Wenn ein Zustand gespeichert werden muss, sollte er über den Zustand des Graphen weitergegeben werden und nicht über Instanzvariablen der Middleware.

Weitere Informationen

Weitere Inhalte finden Sie in der folgenden Dokumentation:

Name	Adresse
Offizielle Dokumentation von Deep Agents (Homepage)	https://docs.langchain.com/deepagents
Deep Agents GitHub-Repository (Quellcode)	https://github.com/langchain-ai/deepagents
Deep Agents Python-Dokumentation (Python-Entwicklungsleitfaden)	https://docs.langchain.com/oss/python/deepagents/overview
Deep Agents JavaScript-Dokumentation (JS/TS-Entwicklungsleitfaden)	https://docs.langchain.com/oss/javascript/deepagents/overview
Deep Agents Python-API-Referenzhandbuch	https://reference.langchain.com/python/deepagents/deepagents
Deep Agents JavaScript-API-Referenz	https://reference.langchain.com/javascript/modules/deepagents.html
Offizielle LangChain-Dokumentation (Basis-Komponentenbibliothek)	https://docs.langchain.com/langchain
Offizielle LangGraph-Dokumentation (Agent-Laufzeitumgebung)	https://docs.langchain.com/langgraph
LangGraph GitHub-Repository (Quellcode)	https://github.com/langchain-ai/langgraph
LangChain GitHub-Repository (Quellcode)	https://github.com/langchain-ai/langchain
Offizielle LangSmith-Website (Agent-Debugging und Monitoring)	https://www.langchain.com/langsmith
Offizielle LangSmith-Dokumentation	https://docs.smith.langchain.com
Offizielle Tavily-Website (Suchwerkzeug)	https://tavily.com
Tavily-API-Dokumentation	https://docs.tavily.com
DeepSeek Open Platform (Modell-Services)	https://platform.deepseek.com
DeepSeek-API-Dokumentation	https://api-docs.deepseek.com

Weitere Erweiterungen

Agenten-Tools

Python-Implementierung von Agenten

Deep Agents Einführungstutorial

Was sind Deep Agents?

Designziele von Deep Agents

Beziehung zu LangChain und LangGraph

Überblick über Kernkompetenzen

Installation

Mit uv installieren (empfohlen)

Mit pip installieren.

Mit DeepSeek API installieren

Konfigurationsanleitung

Vergleich der Dateisystem-Backends

Schnellstart

DeepSeek-API-Schlüssel konfigurieren

Einfachstes Beispiel: Hello-World-Agent

example

Detaillierte Verwendung

Verwenden Sie DeepSeek R1 für Reasoning-Aufgaben.

Beispiel

Benutzerdefinierter System-Prompt

Beispiel

Streaming-Ausgabe

Beispiel

Multi-Turn-Dialog (mit Checkpoints)

example

Umfassende Demo: Recherchebericht-Agent

Szenariobeschreibung

Beispiel

Human-in-the-loop-Beispiel

Beispiel

Häufig gestellte Fragen

Wie entscheidet man zwischen der Verwendung von Deep Agents oder der direkten Verwendung von LangChain/LangGraph?

Empfehlungen zur DeepSeek-Modellauswahl

Was ist zu tun, wenn der Agent ein Tool aufruft und kein Ergebnis zurückgegeben wird?

Wie kann der Agent jeweils nur auf bestimmte Dateien zugreifen?

example

Wie werden der Standard-Systemprompt des Agenten und mein Prompt zusammengeführt?

Fehler, zu denen Anfänger neigen.

Weitere Informationen