Руководство по началу работы с Deep Agents

Deep Agents — это фреймворк для разработки агентов со всем необходимым, официально выпущенный LangChain и специально предназначенный для сложных задач, длительных процессов, многошагового планирования и сценариев многоагентного взаимодействия.

По сравнению с традиционными агентами, которые требуют от разработчиков вручную собирать такие компоненты, как Prompt, Tool, Memory и Workflow, Deep Agents уже включает встроенные ключевые возможности, такие как планирование задач, файловая система, оркестрация субагентов, сжатие контекста и управление памятью, что позволяет разработчикам больше сосредоточиться на бизнес-логике, а не на настройке базовой архитектуры.

Этот учебник предназначен для разработчиков без предварительного опыта. Он шаг за шагом проведёт вас от установки и настройки к основным механизмам работы Deep Agents и с помощью API DeepSeek поможет создать реальный, запускаемый проект AI-агента.

Что такое Deep Agents?

Deep Agents можно понимать как продвинутый фреймворк для агентов (Agent Harness), созданный для production-сред.

Официально он определяется как: фреймворк среды выполнения агентов с полной инфраструктурой, а не просто простой цикл LLM + Tool calling.

После установки вы сразу получаете следующие возможности без дополнительной разработки:

Автоматическое планирование задач (Planning)
Чтение/запись файловой системы (Filesystem)
Совместная работа субагентов (Sub Agents)
Сжатие и управление контекстом (Context Management)
Выполнение длительных задач (Long Running Tasks)
Одобрение человеком (Human-in-the-Loop)
Персистентная память (Memory)
Потоковый вывод (Streaming)

Цели проектирования Deep Agents

Традиционные агенты обычно используют паттерн ReAct: пользовательский ввод → рассуждение LLM → вызов инструмента → рассуждение LLM → вызов инструмента → вывод результата.

Когда масштаб задачи невелик, этот паттерн хорошо работает. Но по мере роста сложности задачи (например, при автоматическом создании отчетов о маркетинговых исследованиях, анализе финансовой отчетности нескольких компаний или написании полной кодовой базы проекта) постепенно возникают следующие проблемы:

Контекстное окно быстро расширяется и превышает лимиты модели
] Слишком длинные цепочки рассуждений приводят к снижению производительности
Агент легко забывает выполненную ранее работу
Отсутствие изоляции между несколькими задачами вызывает взаимные помехи
Логика вызова инструментов становится всё более сложной и трудно поддерживаемой

Основная цель Deep Agents — решить эти инженерные проблемы в сценариях сложных задач.

Связь с LangChain и LangGraph

] Многие новички легко путают позиционирование этих трех проектов; на самом деле они находятся на разных уровнях абстракции.

Фреймворк	Позиционирование по уровню	Основные обязанности	Применимые сценарии
LangChain	Базовый слой компонентов.	Предоставляет базовые компоненты ИИ, такие как Model, Prompt, Tool, Retriever и Output Parser	Базовая возможность для создания отдельных агентов или ИИ-приложений
LangGraph	Слой среды выполнения	Предоставляет возможности управления состоянием, оркестрации рабочих процессов, узлов и рёбер, а также сохранения Checkpoint	Для сложных сценариев, требующих пользовательских структур графов и потоков выполнения
Deep Agents	Слой прикладного фреймворка.	Инкапсулирует возможности промышленного уровня поверх LangGraph, такие как планирование, файловая система, субагенты, память и сжатие контекста	Быстро создавайте сложных многошаговых агентов, не проектируя архитектуру с нуля

Эти три слоя не взаимоисключающие, а могут использоваться вместе: LangChain предоставляет строительные блоки, LangGraph — инженерный фреймворк, который организует эти блоки, а Deep Agents — готовый к использованию высокоуровневый прикладной слой поверх. Любой LangGraphCompiledStateGraphможно передать в Deep Agents в качестве субагента, а три слоя можно гибко комбинировать.

Обзор основных компетенций

Deep Agents поставляется со следующими встроенными middleware, готовыми к использованию без дополнительной настройки:

Способность	Описание	Основные компоненты
Планирование задач	Использовать встроенные`write_todos`инструменты для разбиения сложных задач на упорядоченные шаги	TodoListMiddleware
Виртуальная файловая система	Чтение и запись файлов, выгрузка больших выходных данных инструментов на диск, экономия контекстного окна	FilesystemMiddleware
Субагент	Делегирование подзадач выделенным субагентам с независимыми контекстными окнами	SubAgentMiddleware
Сжатие контекста	Автоматически суммировать исторические сообщения, чтобы не превысить лимит контекста модели	SummarizationMiddleware
Человек в цикле	Приостановка перед критическими вызовами инструментов для ожидания одобрения человеком	HumanInTheLoopMiddleware
Долговременная память	Межсессионная постоянная память на основе LangGraph Store	MemoryMiddleware
Навыки	Загружать переиспользуемые предметные знания и наборы инструкций по требованию	SkillsMiddleware

Установка

Deep Agents публикуется на PyPI под именем пакетаdeepagents。

Рекомендуется использоватьuvустановку, которая быстрее; также можно использовать традиционныйpip。

Установка с помощью uv (рекомендуется)

uv init
uv add deepagents tavily-python
uv sync

Установка с использованием pip.

pip install deepagents tavily-python

Установка с DeepSeek API

DeepSeek совместим с интерфейсом OpenAI, поэтому вам также нужно установитьlangchain-openai。

pip install deepagents langchain-openai

Единственное требование Deep Agents к модели — это то, что модель поддерживаетtool calling. Серии DeepSeek V3 и DeepSeek R1 обе поддерживают это, так что можете использовать его уверенно.

Инструкции по настройке

create_deep_agentЭто основная функция для создания агента, поддерживающая следующую конфигурацию параметров.

Parameters	Type	Обязательный	Описание	Значение по умолчанию
`model`	str или экземпляр модели	нет	Строка модели в формате`provider:model-name`, или напрямую передайте инициализированный объект модели	`anthropic:claude-sonnet-4-6`
`tools`	list	нет	Список пользовательских функций инструментов или объектов LangChain Tool	Отсутствует
`system_prompt`	str или SystemMessage	нет	Пользовательский системный промпт, используемый для определения роли и поведения агента	Отсутствует
`backend`	BackendProtocol	нет	Бэкенд виртуальной файловой системы, определяет расположение хранилища файлов	StateBackend
`subagents`	list	нет	Список определений субагентов, используемых для делегирования задач	Отсутствует
`memory`	list	нет	Список путей к файлам AGENTS.md, загружаемых при запуске	Отсутствует
`skills`	list	нет	Список путей к директориям Skills, загружаемых по требованию	Отсутствует
`permissions`	list	нет	Правила контроля разрешений доступа на уровне пути файловой системы	Отсутствует
`interrupt_on`	dict	нет	Указывает, какие вызовы инструментов требуют ручного подтверждения; должен использоваться с checkpointer	Отсутствует
`checkpointer`	Checkpointer	нет	Чекпоинтер сохранения состояния, должен быть задан для многоходовых диалогов или HITL	Отсутствует
`store`	BaseStore	нет	Бэкенд долговременного хранения между сессиями	Отсутствует
`response_format`	ResponseFormat	нет	Определение схемы для структурированного вывода	Отсутствует
`middleware`	list	нет	Пользовательское middleware, добавляемое в конец стека middleware по умолчанию	()
`debug`	bool	нет	Включить режим отладки, выводить подробные логи	False

Сравнение бэкендов файловой системы

Deep Agents предоставляет несколько бэкендов для управления тем, как Агент читает и записывает файлы.

Бэкенд	Место хранения	Сохранение между сессиями	Применимый сценарий
StateBackend	В состоянии графа LangGraph	Нет (действует в пределах одного потока)	По умолчанию, для локальной разработки и простых сценариев
FilesystemBackend	Локальный диск	Да	Требует реального чтения/записи локальных файлов, использовать с осторожностью
StoreBackend	Хранилище LangGraph	Да	Сохранение многоходовых диалогов, совместное использование между потоками
LocalShellBackend	Локальный диск + Shell	Да	Требует выполнения команд Shell, только в доверенных средах
CompositeBackend	Маршрутизирует на несколько бэкендов	Зависит от дочернего бэкенда	Тонкая настройка политик хранения для разных каталогов

Для начинающих достаточно просто использовать стандартныйStateBackend.FilesystemBackendиLocalShellBackendПозволит агенту напрямую работать с вашей локальной файловой системой; перед использованием строго настройте права доступа.

Быстрый старт

В этом разделе показано, как создать работающего Deep Agent с минимальным объёмом кода.

Настройка API-ключа DeepSeek

DeepSeek совместим с форматом API OpenAI, поэтому необходимо задать как API-ключ, так и Base URL.

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"

API-ключ DeepSeek можноplatform.deepseek.comзапросить. Задайте переменную окруженияOPENAI_BASE_URLчтобы указать адрес DeepSeek, и LangChain автоматически перенаправит туда запросы.

TAVILY_API_KEY нужно запросить на официальном сайте Tavilyhttps://www.tavily.com/ чтобы сгенерировать ключ в формате tvly-xxxxxxxx.

Простейший пример: агент Hello World

Создайте агента с пользовательским инструментом и отправьте первое сообщение в DeepSeek.

пример

# Путь к файлу: hello_agent.py

import os
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

# Используйте ChatOpenAI и укажите base_url на DeepSeek; это самый прямой способ подключения
model = ChatOpenAI(
model="deepseek-v4-flash", # Обязательно: имя модели
api_key=os.environ["OPENAI_API_KEY"], # Обязательно: API-ключ DeepSeek
base_url="https://api.deepseek.com", # Обязательно: эндпоинт DeepSeek, совместимый с OpenAI
)

# Определите простой пользовательский инструмент; docstring функции служит описанием инструмента
def get_weather(city: str) -> str:
"""Запросить погоду для указанного города."""
# В реальном проекте здесь вы бы вызвали настоящий API погоды
return f"{city} сегодня солнечно, 25°C, подходит для прогулки."

# Создайте агента, передав экземпляр модели и список инструментов
agent = create_deep_agent(
model=model,
tools=[get_weather],
system_prompt="Вы — дружелюбный помощник, который может запрашивать информацию о погоде.",
)

# Вызовите агента; messages принимает формат сообщений в стиле OpenAI
result = agent.invoke({
"messages": [{"role": "user", "content": "Какая сегодня погода в Пекине?"}]
})

# Вывести окончательный ответ агента
print(result["messages"][-1].content)

# 运行脚本
python hello_agent.py

Вывод:

В Пекине сегодня **солнечно**, температура **25°C**, очень подходит для прогулки. ☀️

Примечание: Агент возвращает полный список сообщений (messages), а окончательный ответ находится в конце списка, т.е.,result["messages"][-1].content。

Подробное использование

В этом разделе используются несколько реальных сценариев, чтобы постепенно продемонстрировать основные возможности Deep Agents.

Используйте DeepSeek R1 для задач рассуждения.

DeepSeek R1 — это модель с улучшенными рассуждениями, подходящая для задач, требующих сложного анализа.

Пример

# Путь к файлу: reasoning_agent.py

import os
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI

# DeepSeek R1: Разработан для сложных рассуждений
model = ChatOpenAI(
model="deepseek-v4-pro", # Модель рассуждений DeepSeek
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
)

# Пример инструмента математических вычислений
def calculate(expression: str) -> str:
"""Безопасно вычислить математическое выражение и вернуть результат вычисления."""
try:
# Примечание: в производственных средах следует использовать более безопасную библиотеку для вычисления выражений.
result = eval(expression, {"__builtins__": {}}, {})
return f"Результат вычисления: {expression} = {result}"
except Exception as e:
return f"Ошибка вычисления: {str(e)}"

agent = create_deep_agent(
model=model,
tools=[calculate],
system_prompt="Вы — эксперт по математическому анализу, умеете разбивать сложные задачи на части и решать их шаг за шагом.",
)

result = agent.invoke({
"messages": [{"role": "user", "content": "Вычислите сумму всех нечетных чисел от 1 до 100 и проверьте результат."}]
})

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

Вывод выполнения:

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

- 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 \)

Пользовательский системный промпт

Черезsystem_promptПараметры определяют роль Агента, цели задачи и нормы поведения.

Пример

# Путь к файлу: 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",
)

# Пользовательский системный промпт: определите идентичность Агента, его обязанности и правила поведения.
code_review_instructions = """Вы — старший Python-инженер, специализирующийся на проверке кода.

Ваши обязанности:
- Проверяйте читаемость кода, производительность и безопасность
- Указывайте на потенциальные ошибки и предложения по улучшению
- Приводите конкретные примеры изменений

Формат ответа:
1. Общая оценка (1-10)
2. Список основных проблем
3. Конкретные предложения по улучшению (с изменёнными фрагментами кода)
"""

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

# Отправить фрагмент кода на проверку
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"Пожалуйста, проверьте следующий код:\n```python{code_to_review}```"}]
})

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

Потоковый вывод

В сценариях, требующих отображения прогресса в реальном времени, можно использоватьstreamМетод получает вывод Agent порциями.

Пример

# Путь к файлу: 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="Вы эксперт по техническому письму, умеющий писать ясную и понятную техническую документацию.",
)

# Метод stream возвращает генератор, выдавая по одному фрагменту события за раз.
for chunk in agent.stream({
"messages": [{"role": "user", "content": "Напишите краткое введение в декораторы Python."}]
}):
# chunk — это словарь, содержащий инкрементальные сообщения
if "messages" in chunk:
for msg in chunk["messages"]:
if hasattr(msg, "content") and msg.content:
print(msg.content, end="", flush=True)

print() # Заключительный перевод строки

Многоходовой диалог (с контрольными точками)

Вместе сMemorySaverконтрольными точками можно добиться диалога с сохранением состояния между ходами.

пример

# Путь к файлу: multi_turn_agent.py

import os
from deepagents import create_deep_agent
from langchain_openai import ChatOpenAI
from langgraph.checkpoint.memory import MemorySaver # Контрольная точка в памяти, данные будут потеряны после перезапуска.

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

# MemorySaver сохраняет состояние диалога в памяти, которое теряется после завершения процесса.
# В производственной среде рекомендуется использовать SqliteSaver или PostgresSaver
checkpointer = MemorySaver()

agent = create_deep_agent(
model=model,
system_prompt="Вы — полезный помощник по программированию.",
checkpointer=checkpointer, # Должен быть передан, иначе многоходовые диалоги не смогут запоминать контекст
)

# thread_id — уникальный идентификатор потока диалога; один и тот же thread_id использует общий контекст
config = {"configurable": {"thread_id": "example-session-001"}}

# Первый раунд
result1 = agent.invoke(
{"messages": [{"role": "user", "content": "Меня зовут EXAMPLE, и я изучаю Python."}]},
config=config,
)
print("Ответ первого раунда:", result1["messages"][-1].content)

# Второй раунд: Агент может помнить информацию из предыдущего раунда
result2 = agent.invoke(
{"messages": [{"role": "user", "content": "Как меня зовут? Что я изучаю?"}]},
config=config,
)
print("Ответ второго раунда:", result2["messages"][-1].content)

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

Роль thread_id:То же самоеthread_idВсе вызовы под ним используют одну и ту же историю разговора. Разныеthread_idизолированы друг от друга и не мешают друг другу. Можно представить это как "номер комнаты для разговора".

Комплексная демонстрация: Агент для исследовательских отчётов

В этом разделе демонстрируется полноценный агент для исследовательских отчётов, использующий DeepSeek V3 в качестве основной модели, интегрирующий пользовательские инструменты поиска и демонстрирующий использование субагентов.

Описание сцены

Мы создадим агента, который получает тему исследования пользователя, автоматически разбивает задачи, вызывает инструменты поиска для сбора информации и в конце выдаёт структурированный отчёт.

Пример

# Путь к файлу: research_agent_demo.py
# Демонстрация: Создание агента для исследовательских отчётов с использованием DeepSeek API + Deep Agents
# Установка зависимостей: 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
# ──────────────────────────────────────────
main_model = ChatOpenAI(
model="deepseek-v4-flash", # Мощные всесторонние возможности, подходит для планирования и написания
api_key=os.environ["OPENAI_API_KEY"],
base_url="https://api.deepseek.com",
temperature=0.3, # Необязательно: уменьшить случайность, чтобы сделать отчёт более строгим
)
# Инициализировать клиент Tavily (для инструментов поиска)
tavily_client = TavilyClient(
api_key=os.environ["TAVILY_API_KEY"]
)
# ──────────────────────────────────────────
# 2. Определить инструмент поиска Tavily
# ──────────────────────────────────────────
def web_search(
query: str,
max_results: int = 5,
) -> str:
"""Использовать Tavily для поиска информации в интернете"""

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

lines = []

# Ответ, обобщённый ИИ
if response.get("answer"):
lines.append(f"Сводка: {response['answer']}\n")

# Результаты поиска
for idx, item in enumerate(response.get("results", []), start=1):
lines.append(
f"""
[{idx}] {item.get('title', '')}
URL: {item.get('url', '')}
Содержимое: {item.get('content', '')}
""".strip()
)

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

def format_report(title: str, sections: str) -> str:
"""Организуйте содержимое исследования в отчёт в формате Markdown.

Аргументы:
title: Название отчёта
sections: Содержимое каждого раздела, представленное в виде строки JSON, формат: {"Название главы": "Содержимое"}
"""
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 fОшибка форматирования: {str(e)}

# ──────────────────────────────────────────
# 3. Определите выделенного субагента (эксперта по интеграции информации)
# У субагента есть независимое окно контекста, что позволяет избежать раздувания контекста основного агента
# ──────────────────────────────────────────
report_writer_subagent = {
"name": "report-writer", # Обязательно: уникальное имя субагента
"description": Профессиональный ассистент по написанию отчётов, отвечающий за объединение исследовательских материалов в чётко структурированные отчёты., # Обязательно: главный агент использует это описание, чтобы решать, когда делегировать задачи
"system_prompt": Вы профессиональный эксперт по написанию отчётов. После получения исследовательских материалов, пожалуйста, организуйте их в отчёт, состоящий из трёх частей: резюме, основное содержание и заключение, с ясным и кратким языком.,
"tools": [format_report], # Необязательно: инструменты, специфичные для субагента
# Если модель не указана, наследуется модель главного агента.
}

# ──────────────────────────────────────────
# 4. Настройка и создание Deep Agent
# ──────────────────────────────────────────
checkpointer = MemorySaver()

research_instructions = Вы профессиональный ассистент-исследователь, владеющий навыками углублённого исследования и написания отчётов.

Когда пользователь предоставляет тему исследования, вы должны:
1. Используйте инструмент web_search для поиска релевантной информации (выполните поиск как минимум 2-3 раза, охватывая разные аспекты).
2. Организуйте и обобщите собранные данные
3. Делегируйте написание итогового отчёта субагенту report-writer
4. Выведите пользователю полный отчёт.

Примечание: используйте разные ключевые слова для каждого поиска, чтобы получить более полную информацию.
"""

agent = create_deep_agent(
model=main_model,
tools=[web_search], # Инструменты, доступные главному агенту
system_prompt=research_instructions,
subagents=[report_writer_subagent], # Зарегистрировать субагента
checkpointer=checkpointer,
)

# ──────────────────────────────────────────
# 5. Запустить агента
# ──────────────────────────────────────────
print("Идёт исследование, пожалуйста, подождите...\n")

result = agent.invoke(
{
"messages": [{
"role": "user",
"content": Пожалуйста, помогите мне исследовать, что такое LangGraph и его основные сценарии применения.
}]
},
config={"configurable": {"thread_id": "example-research-001"}}
)

print("=" * 60)
print("Отчёт об исследовании")
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

Для чувствительных операций (например, удаления файлов, отправки электронных писем) Агент можно настроить так, чтобы он приостанавливался и ждал ручного подтверждения перед выполнением.

Пример

# Путь к файлу: hitl_agent.py
# Human-in-the-loop: Пусть агент запрашивает одобрение человека перед выполнением опасных операций

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",
)

# Используйте декоратор @tool для определения инструментов (требуется пакет langchain)
@tool
def delete_file(path: str) -> str:
"""Удалить файл по указанному пути."""
# В реальных проектах здесь вызывается os.remove(path).
return f"Файл {path} удален."

@tool
def read_file(path: str) -> str:
"""Прочитать содержимое файла по указанному пути."""
return fСодержимое файла {path}: (пример содержимого)

# interrupt_on настраивает, какие инструменты требуют ручного подтверждения
# True означает разрешить: подтверждение, редактирование параметров, отклонение, отправку пользовательских ответов
# False означает, что подтверждение не требуется
# dict позволяет тонко управлять разрешёнными типами операций
checkpointer = MemorySaver() # HITL должен использоваться с checkpointer

agent = create_deep_agent(
model=model,
tools=[delete_file, read_file],
interrupt_on={
"delete_file": True, # Операция удаления: требует полного процесса подтверждения
"read_file": False, # Операция чтения: подтверждение не требуется
},
checkpointer=checkpointer,
)

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

# Первый вызов: Agent приостанавливается при выполнении delete_file
print("Запуск Agent...")
result = agent.invoke(
{"messages": [{"role": "user", "content": "Пожалуйста, удалите файл /tmp/test.txt."}]},
config=config,
)

# Проверить, есть ли ожидающее прерывание одобрения
for msg in result.get("messages", []):
print(fСообщение агента: {msg.content if hasattr(msg, 'content') else msg})

# Возобновить выполнение: передать решение об одобрении
# "approve" означает одобрить выполнение инструмента
# "reject" означает отклонить; Агент не будет выполнять инструмент
print("\n"Одобрение пользователя: одобрить операцию удаления")
final_result = agent.invoke(
Command(resume={"decision": "approve"}),
config=config,
)
print("Итоговый результат:", final_result["messages"][-1].content)

Как работает interrupt_on:Когда Агент собирается вызвать помеченный инструмент, LangGraph запускаетinterrupt, выполнение агента приостанавливается. Вы можетеCommand(resume=...)передать результат одобрения, чтобы возобновить выполнение.

Часто задаваемые вопросы

Ниже приведены распространённые вопросы и соображения при использовании Deep Agents.

Как выбрать между использованием Deep Agents или прямым использованием LangChain/LangGraph?

Сценарий	Рекомендуемый выбор	Причина
Требуется планирование, чтение/запись файлов, субагенты, сжатие контекста	Deep Agents	Эти возможности доступны из коробки, их не нужно собирать самостоятельно
Требуется лёгкая обёртка, только цикл вызова инструментов	LangChain create_agent	Легче, чем Deep Agents, без встроенного middleware
Нужна пользовательская структура графа, цикл не является стандартным циклом вызова инструментов	LangGraph	Полностью настраивайте логику узлов и рёбер графа
LangGraph CompiledStateGraph как субагент	Смешанное использование	Можно передать пользовательский граф как субагента в Deep Agents

Модель	строка модели	Особенности	Применимые сценарии
deepseek-v4-flash	`deepseek-v4-flash`	Сильные комплексные возможности, высокая скорость, низкая цена	Общие задачи, повседневное общение, написание текстов
deepseek-v4-pro	`deepseek-v4-pro`	Мощные способности к рассуждению, встроенная цепочка рассуждений	Математика, код, сложные логические рассуждения

Что следует делать, если Агент вызывает инструмент и результат не возвращается?

Возвращаемое значение функции инструмента должно быть строкой или типом, который может быть сериализован в строку.

Если инструмент возвращает сложный объект (например, dict или list), рекомендуется использоватьjson.dumps(result, ensure_ascii=False)чтобы преобразовать его перед возвратом.

Как Агент может получать доступ только к определённым файлам за раз?

Используйтеpermissionsпараметры для настройки разрешений доступа к файловой системе, которые позволяют точно контролировать, чтобы Агент читал и записывал только указанные пути.

пример

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,
разрешения=[
FilesystemPermission(path="/workspace/", read=True, write=True), # Разрешить чтение и запись рабочей директории
FilesystemPermission(path="/secrets/", read=False, write=False), # Запретить доступ к чувствительным каталогам
],
)

Как объединяются системный промпт агента по умолчанию и мой промпт?

Промпт Deep Agents собирается из четырёх частей в фиксированном порядке:

USER(ваш system_prompt) →BASE(промпт SDK по умолчанию) →SUFFIX(корректировки, специфичные для производителя модели)

Ваш промпт всегда находится в самом начале и не будет перезаписан. Промпт SDK по умолчанию сообщает модели, как использовать инструменты планирования и работы с файлами, поэтому в большинстве случаев вам не нужно переписывать его самостоятельно.

Ошибки, которые часто допускают новички.

Частая ошибка 1:Забыли передатьcheckpointer. При использовании Human-in-the-loop (interrupt_on) или многоходовых диалогах, выдолжныпередать checkpointer, иначе состояние не сможет быть сохранено, и Agent сообщит об ошибке.

Частая ошибка 2:Функции инструментов не имеют docstring. Deep Agents использует docstring функции как описание инструмента, чтобы модель знала, когда вызывать инструмент. Для инструмента без docstring модель может не знать, когда его вызывать, или даже отказаться его использовать.

Частая ошибка 3:Прямое изменениеselfатрибутов в middleware. Субагенты Агента и параллельные операции могут выполняться одновременно, и прямое изменение атрибутов экземпляра middleware может привести к состояниям гонки. Когда состояние нужно сохранить, его следует передавать через состояние графа, а не через переменные экземпляра middleware.

Дополнительная информация

Для получения дополнительной информации обратитесь к следующей документации:

Name	Адрес
Официальная документация Deep Agents (домашняя страница)	https://docs.langchain.com/deepagents
Репозиторий Deep Agents на GitHub (исходный код)	https://github.com/langchain-ai/deepagents
Документация Deep Agents по Python (руководство по разработке на Python)	https://docs.langchain.com/oss/python/deepagents/overview
Документация Deep Agents по JavaScript (руководство по разработке на JS/TS)	https://docs.langchain.com/oss/javascript/deepagents/overview
Справочное руководство по Python API Deep Agents	https://reference.langchain.com/python/deepagents/deepagents
Справочник по JavaScript API Deep Agents	https://reference.langchain.com/javascript/modules/deepagents.html
Официальная документация LangChain (библиотека базовых компонентов)	https://docs.langchain.com/langchain
Официальная документация LangGraph (среда выполнения агентов)	https://docs.langchain.com/langgraph
Репозиторий LangGraph на GitHub (исходный код)	https://github.com/langchain-ai/langgraph
Репозиторий LangChain на GitHub (исходный код)	https://github.com/langchain-ai/langchain
Официальный сайт LangSmith (отладка и мониторинг агентов)	https://www.langchain.com/langsmith
Официальная документация LangSmith	https://docs.smith.langchain.com
Официальный сайт Tavily (инструмент поиска)	https://tavily.com
Документация API Tavily	https://docs.tavily.com
Открытая платформа DeepSeek (сервисы моделей)	https://platform.deepseek.com
Документация API DeepSeek	https://api-docs.deepseek.com

Другие расширения

Инструменты агента

Реализация агента на Python

Руководство по началу работы с Deep Agents

Что такое Deep Agents?

Цели проектирования Deep Agents

Связь с LangChain и LangGraph

Обзор основных компетенций

Установка

Установка с помощью uv (рекомендуется)

Установка с использованием pip.

Установка с DeepSeek API

Инструкции по настройке

Сравнение бэкендов файловой системы

Быстрый старт

Настройка API-ключа DeepSeek

Простейший пример: агент Hello World

пример

Подробное использование

Используйте DeepSeek R1 для задач рассуждения.

Пример

Пользовательский системный промпт

Пример

Потоковый вывод

Пример

Многоходовой диалог (с контрольными точками)

пример

Комплексная демонстрация: Агент для исследовательских отчётов

Описание сцены

Пример

Пример Human-in-the-loop

Пример

Часто задаваемые вопросы

Как выбрать между использованием Deep Agents или прямым использованием LangChain/LangGraph?

Рекомендации по выбору модели DeepSeek

Что следует делать, если Агент вызывает инструмент и результат не возвращается?

Как Агент может получать доступ только к определённым файлам за раз?

пример

Как объединяются системный промпт агента по умолчанию и мой промпт?

Ошибки, которые часто допускают новички.

Дополнительная информация