Практичні зауваження: ваш AI-агент зустрічає перешкоду на кроці 12. Deep Agents від LangChain

Цей посібник описує процес створення системи від сировини до готового продукту у наступних випадках: ваш AI-агент зустрічає перешкоду на 12-му кроці. Deep Agents від LangChain пояснює причини цього. Основна увага приділяється конкретним крокам виконання, чітким перевіркам та коду, який можна просто додати до репозиторію без необхідності здогадуватися щодо його призначення. На етапі огляду необхідно визначити вхідні дані, відповідальну особу за крок та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись здогадатися про прихований стан системи. Розглядайте цей етап як угоду між вхідними даними та перевіреними результатами. Перейменуйте створювані елементи, визначте критерії успіху та не допускайте безповідомного часткового завершення роботи.

Проблема поверхневих агентів

Під час роботи над етапом «Проблема поверхневого агента» спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність у подальших змінах коду. Запишіть час виконання та витрати на токени або запити поруч із функціональними результатами. Чітке бачення витрат заздалегідь запобігає несподіваним рахункам, коли процес переходить від демо-середовища до спільних. Створюйте контрольні точки після дорогих кроків. Функція відновлення не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор перезапускає пізнішу ланку.

Чотири основи, просто та зрозуміло

Під час роботи над сценарієм «Чотири стовпи» спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Робіть контрольні пункти після дорогих кроків. Система відновлення не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор перезапускає пізнішу ланку.

Стовп 1: Запишіть план там, де його може бачити модель

Під час роботи над етапом Pillar 1 спочатку складіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність у подальших змінах коду. Документуйте як шлях успішної роботи, так і шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки. Зберігайте у кеші стабільні інструкції системи та схеми інструментів. Повторна передача ідентичних даних є поширеною причиною витрат ресурсів. Під час роботи над етапом Pillar 1 спочатку складіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Цей перелік допомагає зберігати чесність у подальших змінах коду. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Назвіть створювані елементи, визначте критерії успіху та не допускайте безповідомного часткового завершення роботи.

Pillar 2: Файлова система, яку агент може використовувати як пам’ять

Етап файлової системи Pillar 2 працює найкраще, коли його розглядають як вимірювану поверхню. Запишіть один ідеальний зразок роботи, один випадок збою та примітки щодо скасування змін перед розширенням обсягу роботи. Записуйте час виконання та витрати на токени чи запити поруч із функціональними результатами. Візуалізація витрат заздалегідь запобігає несподіваним рахункам під час переходу від демо-середовища до спільних середовищ. Зберігайте стан графа у вигляді простих структур із чіткими типами даних. Вбудовані блоки даних приховують інформацію про те, який вузол записав яке поле, і ускладнюють продовження роботи після перерв.

Pillar 3: Підагенти для карантину контексту

Підагенти Стовпа 3 для етапних робіт найкраще функціонують, якщо їх розглядати як вимірювану поверхню. Збережіть один ідеальний приклад виконання, один випадок невдачі та запис про скасування змін перед розширенням обсягу роботи. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь граф. Зберігайте стан графа у простій та типованій формі. Вкладені блоки приховують інформацію про те, який вузол заповнив яке поле, і ускладнюють продовження роботи після перерв.

Стовп 4: Навички, які агент завантажує за потребою

У рамках підходу Pillar 4 Skills цей етап функціонує найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Документуйте як успішний, так і відновлювальний сценарії роботи. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої доробки. Зберігайте стан графа у простому та типованому вигляді. Вкладені структури приховують інформацію про те, який вузол заповнив яке поле, що призводить до порушення послідовності дій після перерв. У рамках підходу Pillar 4 Skills цей етап функціонує найкраще, коли його розглядають як вимірювану поверхню. Збережіть один ідеальний запис, один випадок збою та примітку про скасування змін перед розширенням обсягу роботи. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Позначте всі елементи, визначте критерії успіху та не допускайте безповідомного часткового завершення роботи.

- research: Conducts multi-source web research with citation
- writer: Drafts long-form content matching house style
- sql_query: Runs read-only queries against the analytics warehouse

Чотири основи – це один і той самий принцип, повторений чотири рази

Чотири основні елементи – це етап, визначення вхідних даних, власник кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Записуйте час виконання та витрати на токени або запити поруч із функціональними результатами. Візуалізація витрат заздалегідь запобігає несподіваним рахункам, коли процес переходить від демо-середовища до спільних середовищ. Встановлюйте людське схвалення для кроків, які витрачають гроші або змінюють дані в продакшені. Підключення під час компіляції не є гарантією повноти бізнес-функціоналу.

Як насправді спробувати це

На етапі «Як насправді спробувати» необхідно визначити вхідні дані, виконавця кроку та критерії завершення перед зміною коду. Оператори мають мати можливість перезапустити крок з відомої точки контролю, не здогадуючись про прихований стан. Конфігурацію слід тримати окремо від коду додатку. Файли середовища, сховища конфіденційних даних та флаги функціоналу мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь архітектурний план. Встановлюйте людське схвалення для дій, які призводять до витрат грошей чи змінюють дані у продакшені. Підключення на етапі компіляції не є гарантією повноти бізнес-функціоналу.

pip install deepagents

import os
from pathlib import Path
from deepagents import create_deep_agent
from deepagents.backends import FilesystemBackend
from tavily import TavilyClient

tavily = TavilyClient(api_key=os.environ["TAVILY_API_KEY"])def web_search(query: str, max_results: int = 5):
    return tavily.search(query, max_results=max_results)workspace = Path("./workspace").resolve()  # root_dir must be absolute
workspace.mkdir(exist_ok=True)agent = create_deep_agent(
    model="anthropic:claude-3-5-sonnet-latest",
    system_prompt="You are a senior analyst. Use web search to find sources, save the raw results to disk, then synthesize.",
    tools=[web_search],
    backend=FilesystemBackend(root_dir=str(workspace), virtual_mode=True),
)result = agent.invoke({"messages": [{"role": "user", "content": "Brief me on the current state of LLM agent frameworks"}]})print(result["messages"][-1].content)

Що додати ще

На другому етапі «Що додати» необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Необхідно документувати як шлях успішного виконання, так і шлях відновлення. Повторні спроби, людський контроль та обробка некоректних повідомлень є частиною продукту, а не етапом подальшої оптимізації. Встановлюйте людське схвалення для операцій, які призводять до витрат грошей чи змінюють дані у продакшені. Підключення на етапі компіляції не є гарантією повності функціоналу продукту. На другому етапі «Що додати» необхідно визначити вхідні дані, власника кроку та критерії завершення перед зміною коду. Оператори повинні мати можливість перезапустити крок з відомої точки контролю, не намагаючись вгадати прихований стан. Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Називайте створювані елементи, визначайте критерії успіху та не допускайте безповідомного часткового завершення роботи.

Коли Deep Agents — не правильний інструмент

Під час роботи на етапі Where Deep Agents спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається при частковій невдачі. Цей перелік допомагає зберігати чесність пізніших змін у коді. Запишіть час виконання та витрати на токени або запити поруч із функціональними результатами. Відомі заздалегідь витрати запобігають несподіваним рахункам, коли процес переходить від демо-версії до спільних середовищ. Записуйте назву інструменту, хеш аргументів, затримку та результат кожного виклику. Без цих записів виправлення помилок у циклах агента займає години.

Висновок, який можна використати навіть якщо ви ніколи не будете працювати з цією бібліотекою

Під час роботи над етапом «Висновки, які можна застосувати», спочатку запишіть умови контракту: необхідні вхідні дані, сигнал про успіх та те, що відбувається у разі часткової невдачі. Такий перелік допомагає зберігати чесність пізніших змін у коді. Тримайте конфігурацію окремо від коду додатку. Файли середовища, сховища секретних даних та флаги функцій мають знаходитися в одному місці, де оператори можуть їх перевіряти, не читаючи весь код. Робіть контрольні пункти після дорогих кроків. Система відновлення не повинна знову стягувати плату за один і той самий виклик LLM, коли оператор перезапускає пізніший етап.

Перелік операційних кроків

Етап переліку операційних кроків працює найкраще, якщо його розглядати як вимірювану поверхню. Збережіть один ідеальний запис, один випадок невдачі та примітку щодо скасування змін перед розширенням обсягу роботи.

Віддавайте перевагу невеликим, тестованим одиницям коду перед об’ємними скриптами. Коли якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій.

Зберігайте стан графа у вигляді плоскої структури з визначеними типами даних. Вкладені блоки приховують інформацію про те, який вузол заповнив певне поле, що ускладнює продовження роботи після перерв.

Додайте тест на базову функціональність, який перевіряє критичний шлях у процесі інтеграційного тестування за допомогою фікстур, а не реальних платних API, коли це дозволяють бюджетні обмеження.

Розглядайте цей етап як контракт між вхідними даними та перевіреними результатами. Назвіть створювані артефакти, визначте критерії успіху та не допускайте мовчазного часткового завершення роботи.

Зберігайте стан графа у вигляді плоскої структури з визначеними типами даних. Вкладені блоки приховують інформацію про те, який вузол заповнив певне поле, що ускладнює продовження роботи після перерв.

Перед підвищенням версії стека заморозьте поточні версії, зафіксуйте ідеальний запис дій для критичного шляху та підтвердьте кроки для відкату. У спільних середовищах необхідні обмеження на швидкість виконання операцій, перевірки прав доступу та чіткий власник для зміни секретних даних. Віддавайте перевагу надійності перед креативними одноразовими демонстраціями.

Примітка до пакету 8916e9958e68: не включайте ключі постачальника до репозиторію, встановіть ліміт токенів на сеанс та зберігайте транскрипції поруч із фіксами для оцінки, щоб подальша заміна моделей залишалася порівнянною.

Під час роботи над етапом 0 примітки щодо посилення безпеки спочатку запишіть контракт: необхідні вхідні дані, сигнал про успіх та те, що відбувається при частковій невдачі. Цей перелік допомагає зберігати чесність у подальших змінах коду. Віддавайте перевагу невеликим, тестованим одиницям перед об’ємними скриптами. Якщо якийсь крок зазнає невдачі, причина має вказувати на конкретну відповідальність, а не на заплутану послідовність дій.

Деталь посилення безпеки 0/751: вимірюйте час виконання, клас помилки та кількість витрачених токенів для цієї примітки, а потім вирішуйте, чи залишити зміни, ґрунтуючись на фіксованому наборі питань, а не на окремих випадках.