Практические заметки: Объяснение Google ADK: создание многоагентных систем с использованием
Пошаговое руководство по практическим заметкам: «Google ADK Explained»: создание многопроцессных систем с использованием контрактов, проверок и готовых блоков кода для команд, применяющих эту модель.
В следующих заметках описывается практический подход к изучению материала «Google ADK Explained: Building Multi-Agent Systems With Google’s Agent Development Kit». Основное внимание уделяется контрактам, проверкам и местам для вставки кода, а не мотивирующим аспектам. На этапе обзора сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций.
Цель
Этап «Цель» работает наилучшим образом, если рассматривать его как измеримую поверхность. Соберите один идеальный пример результата, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия создаваемым элементам, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, и приводят к нарушению последовательности выполнения после перерывов.
1. Что такое Google ADK? Понимание фреймворка и экосистемы
Этап «Что такое Google» работает наилучшим образом, если рассматривать его как измеримую основу. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на ранних этапах предотвращает неожиданные счёты при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной; вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и могут нарушить возобновление работы после прерываний.
1.1 Фреймворк, ориентированный на код, для агентов
Подход «Code-First» в рамках этапа 1 1 A работает наилучшим образом, когда его рассматривают как измеримую структуру. Соберите один эталонный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных маскируют информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению возобновления работы после перерывов. Подход «Code-First» в рамках этапа 1 1 A работает наилучшим образом, когда его рассматривают как измеримую структуру. Соберите один эталонный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. Когда какой-то шаг сбивается, причина сбоя должна указывать на конкретную ответственность, а не на запутанную цепочку операций.
1.2 Преимущества и компромиссы
Для этапа «1.2 Сильные стороны» необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия соответствующим элементам, определите критерии успеха и не допускайте молчаливого частичного выполнения задачи. Обеспечьте утверждение человеком для операций, связанных с тратой денег или изменением производственных данных. Простая настройка во время компиляции не гарантирует полноты выполнения бизнес-задач.
1.3 Место ADK в экосистеме Agent Framework
Для этапа позиционирования ADK в режиме 1/3 необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рядом с функциональными результатами следует записывать время выполнения и стоимость токенов или запросов. Отображение затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Необходимо ввести человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты реализации бизнес-логики.
2. Внутри ADK: блоки построения и шаблоны мультиагентных систем
Для этапа 2 Inside ADK Building необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Вводите ручное утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты охвата бизнес-логики. Для этапа 2 Inside ADK Building необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое шага он должен указывать на конкретную причину, а не на запутанную структуру обработки данных.
e.2.1 Агенты и инструменты: основные строительные блоки
При работе над этапом «Агенты и инструменты» сначала запишите контракт: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия создаваемым объектам, определите критерии успешности и не допускайте безответственного частичного выполнения задач. Фиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка циклов агентов занимает часы.
from google.adk.agents import LlmAgent
writer_agent = LlmAgent(
name="writer_agent",
model="gemini-2.5-flash",
instruction="You write short popular-science articles. Write about 200 words.",
output_key="draft",
)
from google.adk.tools import ToolContext
def exit_loop(tool_context: ToolContext) -> dict:
"""Call this when the draft is good enough to publish."""
tool_context.actions.escalate = True
tool_context.actions.skip_summarization = True
return {}
critic_agent = LlmAgent(
name="critic_agent",
model="gemini-2.5-flash",
instruction=(
"You are a sharp science editor. Review the draft.\n"
"If it is clear, accurate, and engaging, call exit_loop.\n"
"Otherwise, list specific, actionable fixes."
),
tools=[exit_loop],
output_key="critique",
)
2.2 Оркестрация агентов
При работе над этапом 2 2 Orchestrating Agents сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет избежать ошибок при последующих изменениях кода. Рядом с функциональными результатами занесите информацию о времени выполнения и стоимости токенов или запросов. Отображение затрат с самого начала предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Выполняйте контрольные точки после дорогостоящих шагов. Функция возобновления работы не должна снова взимать плату за один и тот же вызов LLM при повторной попытке обработки последующего узла.
from google.adk.agents import LoopAgent, SequentialAgent
refinement_loop = LoopAgent(
name="refinement_loop",
sub_agents=[writer_agent, critic_agent],
max_iterations=3,
)
root_agent = SequentialAgent(
name="writing_pipeline",
sub_agents=[theme_agent, refinement_loop],
)
root_agent (SequentialAgent)
├── theme_agent
└── refinement_loop (LoopAgent, ≤ 3 rounds)
├── writer_agent
└── critic_agent → exit_loop
2.3 Состояние, сессии и память
При работе над этапом сессий с двумя-тремя состояниями сначала запишите контракт: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой чек-лист помогает сохранять честность последующих изменений в коде. Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Создавайте контрольные точки после дорогостоящих шагов. Функция возобновления не должна снова взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить более поздний узел. При работе над этапом сессий с двумя-тремя состояниями сначала запишите контракт: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой чек-лист помогает сохранять честность последующих изменений в коде. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. Когда шаг терпит неудачу, причина должна указывать на конкретную ответственность, а не на запутанную цепочку операций.
# after theme_agent runs
{"topic": "Why the sky is blue"}
# after writer_agent runs
{
"topic": "Why the sky is blue",
"draft": "The sky is blue because..."
}
# after critic_agent runs
{
"topic": "...",
"draft": "...",
"critique": "Define scattering for a lay reader."
}
# after the next writer iteration
{
"topic": "...",
"draft": "The sky is blue because of a process called...",
"critique": "..."
}
Write a short article about {topic}.
If a critique of your previous draft exists below,
treat it as a checklist and address every point
in your rewrite.\n"
{critique?}
from google.adk.sessions import InMemorySessionService
from google.adk.runners import Runner
session_service = InMemorySessionService()
runner = Runner(
agent=root_agent,
app_name="writing_assistant",
session_service=session_service,
)
await session_service.create_session(
app_name="writing_assistant",
user_id=USER_ID,
session_id=session_id,
)
async for event in runner.run_async(
user_id=USER_ID,
session_id=session_id,
new_message=start,
):
...
session = await session_service.get_session(
app_name="writing_assistant",
user_id="lina",
session_id="run_1",
)
print(session.state["draft"])
async def archive_run(callback_context):
await callback_context.add_session_to_memory()
return None
from google.adk.tools import load_memory
theme_agent = LlmAgent(
name="theme_agent",
model=MODEL,
instruction=(
"Pick a topic for a short popular-science article. "
"Use the 'load_memory' tool to check which topics were already "
"covered, and choose a new one."
),
tools=[load_memory],
output_key="topic",
)
3. Исследование ADK Studio: наблюдение и отладка рабочих процессов агентов
Этап «Исследование ADK Studio» работает наилучшим образом, если рассматривать его как измеримую основу. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия создаваемым объектам, определите критерии успеха и не допускайте молчаливого частичного выполнения задач. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.
3.1 События: что происходило во время выполнения
События 3.1: Какая стадия наилучшим образом подходит для рассмотрения как измеримая поверхность. Зафиксируйте один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема исследования. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости на ранних этапах предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Сохраняйте структуру графа простой и типизированной; вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и могут нарушить возобновление работы после прерываний.
3.2 Трейсы: как выполнялась работа
Методология 3 2 Traces показывает, как наилучшим образом работать с этапами, рассматривая их как измеримые объекты. Соберите один эталонный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию до расширения объёма исследования. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф. Сохраняйте состояние графа простым и типизированным. Вложенные структуры данных скрывают информацию о том, какой узел записал тот или иной поле, и мешают возобновлению работы после прерываний. Методология 3 2 Traces показывает, как наилучшим образом работать с этапами, рассматривая их как измеримые объекты. Соберите один эталонный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию до расширения объёма исследования. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций.
3.3 Панель инспекции: граф, состояние, артефакты и оценки
На этапе инспекции необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия создаваемым элементам, определите критерии успеха и не допускайте молчаливого частичного выполнения задачи. Обеспечьте утверждение человеком для операций, связанных с расходами или изменением производственных данных. Компиляционная настройка не заменяет полноту выполнения бизнес-задач.
3.4 ADK Studio против LangGraph Studio
Для третьего этапа ADK Studio в 3–4 годах нашей эры необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рядом с функциональными результатами следует записывать время выполнения и стоимость токенов или запросов. Отображение затрат на раннем этапе предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Необходимо ввести человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты реализации бизнес-логики.
Основные выводы
На этапе ключевых выводов необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь кодовый граф. Вводите человеческое утверждение для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты обработки бизнес-логики. На этапе ключевых выводов необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочитайте небольшие, тестируемые единицы кода большим скриптам. При сбое шага он должен указывать на конкретную причину, а не на сложную взаимосвязь всех компонентов.
Список ссылок
На этапе работы над списком ссылок сначала запишите условия контракта: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия элементам, определите критерии успеха и не допускайте молчаливого частичного выполнения задачи. Выполняйте контрольные точки после дорогостоящих операций. Система должна не повторно взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий шаг.
Чек-лист операций
На этапе составления чек-листа операций определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг, используя известную контрольную точку, без необходимости угадывать скрытое состояние. Задокументируйте как успешный, так и восстановительный сценарии работы. Повторные попытки, проверки человеком и обработка ошибок являются неотъемлемой частью продукта, а не элементами последующей доработки.
Необходимо получать одобрение человека для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты функционала бизнес-процесса.
Напишите краткий руководство: как обновлять ключи, как опустошать очередь, как откатывать последнюю операцию ввода данных.
Лучше использовать небольшие, тестируемые модули вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций.
Необходимо получать одобрение человека для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты функционала бизнес-процесса.
Перед внедрением новой стековой архитектуры заморозьте версии, сохраните эталонный вариант данных для критически важных процессов и убедитесь, что существуют шаги для отката. В общедоступных средах необходимы ограничения на частоту запросов, проверки принадлежности ресурсов и четко определенный ответственный за обновление секретов. Лучше выбирать надежность, чем красивые, но единоразовые демонстрации.
Примечание к пакету 6e09fe01b77f: не включайте ключи поставщиков в репозиторий, установите лимит токенов на сессию и храните транскрипции рядом с фиксами для оценки, чтобы последующие замены моделей оставались сопоставимыми.
Для этапа 0 примечания по усилению безопасности определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Храните конфигурацию вне кода приложения: файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, которое операторы могут проверять, не читая весь граф.
Подробность усиления безопасности 0/870: измеряйте время выполнения, класс ошибок и расход токенов для этого примечания, затем решайте, следует ли сохранять изменение на основе фиксированного набора вопросов, а не на основе устных замечаний.
При работе над первым этапом записки по укреплению безопасности сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Лучше использовать небольшие, тестируемые модули вместо обширных скриптов. Если какой-то шаг не сработает, причина неудачи должна указывать на конкретную ответственность, а не на запутанную цепочку операций.
Подробность укрепления безопасности 1/870: измерьте время выполнения, класс ошибки и расход токенов для данной записки, затем решите, следует ли сохранять изменение на основе определенного набора критериев, а не на основе устных замечаний.
Второй этап записки по укреплению безопасности работает лучше всего, когда его рассматривают как измеримую область. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Записывайте временные показатели и стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.
Подробности усиления безопасности 2/870: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменение на основе фиксированного набора вопросов, а не на основе единичных случаев.
На третьем этапе работы над усилением безопасности определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Документируйте как успешный путь выполнения, так и путь восстановления. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не последующими улучшениями.
Подробности усиления безопасности 3/870: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменение на основе фиксированного набора вопросов, а не на основе единичных случаев.
При работе над четвертым этапом инструкции по усилению безопасности сначала запишите контракт: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия соответствующим элементам, определите критерии успешности и не допускайте молчаливого частичного выполнения задач.
Подробности усиления безопасности 4/870: измерьте время выполнения, класс ошибки и расход токенов для данной инструкции, затем решите, следует ли сохранять изменение на основе фиксированного набора критериев, а не на основе единичных примеров.
Четвертый этап инструкции по усилению безопасности работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один эталонный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, которое операторы могут проверять, не читая весь код.
Подробности усиления безопасности 5/870: измерьте время выполнения операции, класс ошибки и количество потраченных токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.
На этапе 6 процесса усиления безопасности определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Предпочтительнее использовать небольшие, проверяемые единицы кода вместо обширных скриптов. При сбое шага он должен указывать на конкретную причину, а не на сложную взаимосвязь компонентов.
Подробности усиления безопасности 6/870: измерьте время выполнения операции, класс ошибки и количество потраченных токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.
При работе над этапом 7 записки по усилению безопасности сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рядом с функциональными результатами записывайте время выполнения, стоимость токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.
Подробности усиления безопасности 7/870: измерьте время выполнения, класс ошибки и расход токенов для данной записки, затем решите, следует ли сохранять изменение на основе определенного набора критериев, а не на основе устных оценок.
Этап 8 записки по усилению безопасности лучше всего работает, если рассматривать его как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Документируйте одновременно успешный сценарий работы и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не элементами последующей доработки.
Подробности усиления безопасности 8/870: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.
На этапе 9 записи о усилении безопасности определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными данными. Укажите названия результатов работы, определите критерии успеха и откажитесь от молчаливого частичного завершения задачи.
Подробности усиления безопасности 9/870: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранить изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.