Практические замечания: LangChain Deep Agents — системы искусственного интеллекта
Пошаговое руководство по использованию практических заметок: LangChain Deep Agents AI Systems — контракты, проверки и готовые блоки кода для команд, внедряющих эту архитектуру.
Используйте это как переработанную версию идей из книги «LangChain Deep Agents AI Systems», ориентированную на операторов: четкие этапы, упорядоченные блоки кода и записи о восстановлении, сохраняющиеся при передаче задач. Этап Обзора работает наилучшим образом, если рассматривать его как измеримую основу. Соберите один идеальный пример выполнения, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Документируйте как успешный ход выполнения, так и пути восстановления одновременно. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не этапом последующей доработки.
Что такое Deep Agents на самом деле
Для этапа What Deep Agents Actually необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Лучше использовать небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину, а не на сложную структуру обработки данных. Внедрять утверждение человека там, где происходит трата средств или изменение данных в продакшене. Наличие связей на этапе компиляции не гарантирует полноты решения бизнес-задач.
from deepagents import create_deep_agent
def get_weather(city: str) -> str:
"""Get weather for a given city."""
return f"It's always sunny in {city}!"
agent = create_deep_agent(
tools=[get_weather],
system_prompt="You are a helpful assistant",
)
agent.invoke(
{"messages": [{"role": "user", "content": "What is the weather in Mumbai?"}]}
)
Пять ключевых возможностей, которые делают это уникальным
На этом этапе «Пять способностей» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия результатам работы, определите критерии успеха и не допускайте молчаливого частичного завершения задачи. Внедряйте утверждение человека для операций, связанных с тратой денег или изменением производственных данных. Настройка на этапе компиляции не эквивалентна полноте выполнения бизнес-задач.
1. Встроенное планирование с write_todos
Для режима «Встроенное планирование с этапами» необходимо заранее определить входные данные, ответственного за выполнение этапа и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить этап с известной точки контроля, не догадываясь о скрытом состоянии. Регистрируйте время выполнения и стоимость токенов или запросов вместе с функциональными результатами. Отображение стоимости на ранних этапах предотвращает неожиданные счета при переходе с демо-среды в общедоступные среды. Внедряйте человеческое утверждение для операций, связанных с расходами или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты функционала для бизнеса. Для режима «Встроенное планирование с этапами» необходимо заранее определить входные данные, ответственного за выполнение этапа и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить этап с известной точки контроля, не догадываясь о скрытом состоянии. Документируйте одновременно «идеальный путь» и пути восстановления. Повторные попытки, человеческое утверждение и обработка некорректных сообщений являются частью продукта, а не элементами, добавляемыми позже.
2. Виртуальная файловая система
При работе над этапом «2. Виртуальная файловая система» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина неудачи должна указывать на конкретную ответственность, а не на запутанную последовательность операций. Создавайте контрольные точки после дорогостоящих шагов. Функция возобновления работы не должна повторно запускать один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий элемент работы.
3. Создание подагентов
При работе над этапом создания 3 подагентов сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и последствия частичной неудачи. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте безусловного частичного завершения работы. Создавайте контрольные точки после дорогостоящих операций. Функция возобновления работы не должна снова запрашивать один и тот же вызов LLM, когда оператор пытается выполнить следующий этап.
from deepagents import create_deep_agent, Subagent
code_reviewer = Subagent(
name="code-reviewer",
system_prompt="You are an expert code reviewer. Analyze code for bugs, style, and performance.",
tools=[read_file_tool],
)
agent = create_deep_agent(
tools=[internet_search],
subagents=[code_reviewer],
system_prompt="You are a research and engineering assistant.",
)
4. Автоматическое сжатие и краткое изложение контекста
При работе над 4 этапами автоматического сжатия контекста сначала запишите условия использования: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Запишите также время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на ранних этапах предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Выполняйте контрольные точки после дорогостоящих шагов. Функция возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели при повторной попытке обработки последующего узла. При работе над 4 этапами автоматического сжатия контекста сначала запишите условия использования: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Документируйте одновременно успешный и восстановительный сценарии работы. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки.
5. Долгосрочная память в ходе разговоров
Механизм долгосрочной памяти на этом этапе работает наилучшим образом, когда рассматривается как измеримая структура. Сначала соберите один идеальный пример транскрипции, один пример сбоя и запись о возврате к предыдущему состоянию, прежде чем расширять объем работы. Предпочитайте небольшие, проверяемые единицы вместо обширных скриптов. При сбое какого-либо шага причина должна указывать на конкретного ответственного, а не на запутанную цепочку операций. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.
from deepagents import create_deep_agent
from deepagents.backends import CompositeBackend, StateBackend, StoreBackend
from langgraph.store.memory import InMemoryStore
store = InMemoryStore()
backend = CompositeBackend(
routes={"/memories/": StoreBackend(store=store)},
default=StateBackend(),
)
agent = create_deep_agent(
tools=[...],
backend=backend,
memory=["path/to/AGENTS.md"], # persistent context file
)
Как это вписывается в экосистему LangChain
Этап «Как это вписывается» работает наилучшим образом, если рассматривать его как измеримую поверхность. Соберите один образец успешного результата, один пример сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия создаваемым объектам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, и приводят к нарушению последовательности выполнения после перерывов.
Создание исследовательского агента: быстрый старт
Этап создания исследовательского агента работает наилучшим образом, когда его рассматривают как измеримую среду. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и могут нарушить работу после прерываний. Этап создания исследовательского агента работает наилучшим образом, когда его рассматривают как измеримую среду. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Документируйте одновременно успешный путь выполнения и путь восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не этапом последующей доработки.
import os
from typing import Literal
from tavily import TavilyClient
from deepagents import create_deep_agent
tavily_client = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])
def internet_search(
query: str,
max_results: int = 5,
topic: Literal["general", "news", "finance"] = "general",
include_raw_content: bool = False,
):
"""Run a web search and return results."""
return tavily_client.search(
query,
max_results=max_results,
include_raw_content=include_raw_content,
topic=topic,
)
research_instructions = """You are an expert researcher.
Your job is to conduct thorough research and then write a polished report.
Use internet_search to gather information.
Write your findings to files as you go to avoid losing context.
Use write_todos to plan your research steps before starting.
"""
agent = create_deep_agent(
model="anthropic:claude-sonnet-4-6", # default model
tools=[internet_search],
system_prompt=research_instructions,
)
result = agent.invoke({
"messages": [{
"role": "user",
"content": "Research the current state of agentic AI frameworks in 2025 and write a structured report."
}]
})
print(result["messages"][-1].content)
CLI Deep Agents
Для этапа The Deep Agents CLI необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не пытаясь угадать скрытое состояние. Лучше использовать небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину, а не на сложную структуру всей системы. Внедрять утверждение человека там, где происходят финансовые операции или изменяются данные в продакшене. Простая настройка во время компиляции не гарантирует полноты функционала системы.
pip install deepagents
deepagents # launches the interactive CLI agent
Когда следует (и когда не следует) его использовать
На этапе «Когда следует» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте молчаливого частичного завершения работы. Внедряйте утверждение человека для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты выполнения бизнес-задач.
Почему это важнее, чем выпуск другой фреймворка
На этапе «Почему это особенно важно» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Записывайте время выполнения и стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Внедряйте человеческое утверждение для операций, связанных с расходами или изменением производственных данных. Подключение на этапе компиляции не гарантирует полноты решения для бизнеса. На этапе «Почему это особенно важно» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Документируйте одновременно «идеальный путь» и пути восстановления. Повторные попытки, человеческое утверждение и обработка некорректных сообщений являются частью продукта, а не элементами последующей доработки.
Начало работы
На этапе «Начало работы» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые модули большим скриптам. Если какой-то шаг не сработает, причина неудачи должна указывать на конкретную ответственность, а не на запутанную цепочку операций. Выполняйте проверки после дорогостоящих шагов. Система должна не повторно взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.
pip install deepagents tavily-python
export ANTHROPIC_API_KEY="your-key"
export TAVILY_API_KEY="your-key"
export LANGSMITH_TRACING=true # optional, for debugging
export LANGSMITH_API_KEY="your-key"
Чек-лист операций
На этапе чек-листа операций сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода.
Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код.
Создавайте точку контроля после дорогостоящих операций. Функция возобновления не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий шаг.
Фиксируйте версии зависимостей и записывайте хэш изображения, с использованием которого выполнялась демонстрация. Воспроизводимость важнее устного опыта сотрудников.
Документируйте как успешный, так и восстановительный пути работы. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не его дополнительными улучшениями.
Создавайте точку контроля после дорогостоящих операций. Функция возобновления не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий шаг.
Перед тем как запускать стек, заморозьте версии, сделайте копию «золотого» отчета для критической цепочки операций и уточните шаги возврата к предыдущему состоянию. В совместных средах необходимы ограничения на частоту запросов, проверки принадлежности пользователя и четко определенный ответственный за обновление секретов. Лучше выбирать надежность, чем креативные одноразовые демонстрации.
Примечание для задачи c6305757c342: не храните ключи поставщика в репозитории, установите лимит токенов на сессию и сохраняйте отчеты рядом с фикстурами для оценки, чтобы последующие замены моделей оставались сопоставимыми.