Практические заметки: Введение в агентные ИИ с Google ADK
Пошаговое руководство по практическим заметкам: введение в агентные ИИ с использованием Google ADK: контракты, проверки и слоты для вставки кода для команд, разрабатывающих эту архитектуру.
В этом руководстве пошагово описывается путь от сырья до готовой к работе системы для курса «Введение в агентные ИИ с использованием Google ADK». Основное внимание уделяется практическим шагам, четким проверкам и коду, который можно просто добавить в репозиторий без необходимости догадываться о его назначении. На этапе обзора необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия создаваемым элементам, определите критерии успеха и не допускайте безответственного частичного выполнения задач.
Переход от чат-ботов к агентам
При работе над этапом «Переход от чат-ботов» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список поможет избежать ошибок при последующих изменениях кода. Рядом с результатами работы запишите время выполнения и стоимость токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Выполняйте контрольные точки после дорогостоящих операций. Система возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, если оператор попытается выполнить последующий шаг заново.
Понимание основной идеи агентного ИИ
При работе над этапом «Понимание основной идеи» сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает избегать ошибок при последующих изменениях кода. Храните конфигурацию отдельно от кода приложения. Файлы с настройками окружения, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Создавайте контрольные точки после дорогостоящих операций. Функция возобновления работы не должна повторно взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий шаг.
from google.adk.agents import Agent
root_agent = Agent(
name="assistant",
model="gemini-2.5-flash",
instruction="You are a helpful assistant"
)
Наделение агента реальными возможностями с помощью инструментов
При работе над этапом «Giving an Agent Real» сначала запишите контракт: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Документируйте одновременно успешный и восстановительный пути работы. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Фиксируйте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой записи отладка циклов агента занимает часы. При работе над этапом «Giving an Agent Real» сначала запишите контракт: необходимые входные данные, сигнал о успехе и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте безответственного частичного выполнения задач.
from google.adk.agents import Agent
def calculator(a: float, b: float, operation: str) -> float:
if operation == "add":
return a + b
if operation == "subtract":
return a - b
if operation == "multiply":
return a * b
if operation == "divide":
if b == 0:
raise Exception("Cannot divide by zero")
return a / b
raise Exception("Unsupported operation")
root_agent = Agent(
name="assistant",
model="gemini-2.5-flash",
instruction=(
"You are a helpful assistant with calculator capabilities. "
"Use the calculator tool for arithmetic. "
"Supported operations are add, subtract, multiply, divide."
),
tools=[calculator]
)
Создание агентов с несколькими инструментами
Модель агентов-мультиинструментов в рамках концепции Building работает наилучшим образом, когда рассматривается как измеримая среда. Сначала необходимо зафиксировать один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию, прежде чем расширять объем задачи. Рядом с функциональными результатами следует записывать время выполнения операций, а также стоимость использования токенов или запросов. Отслеживание затрат на раннем этапе помогает избежать неожиданных счетов при переходе от демо-среды к общедоступным средам. Инструменты с узкими схемами и четкими метками о побочных эффектах должны быть отображаемы отдельно. Хостам необходимо знать, какие вызовы изменяют состояние системы, прежде чем они автоматически одобрят их выполнение.
from google.adk.agents import Agent
def calculator(a: float, b: float, operation: str) -> float:
if operation == "add":
return a + b
if operation == "subtract":
return a - b
if operation == "multiply":
return a * b
if operation == "divide":
if b == 0:
raise ValueError("Cannot divide by zero.")
return a / b
raise ValueError("Unsupported operation.")
def convert_units(value: float, from_unit: str, to_unit: str) -> float:
from_unit = from_unit.lower()
to_unit = to_unit.lower()
if from_unit == "km" and to_unit == "miles":
return value * 0.621371
if from_unit == "miles" and to_unit == "km":
return value / 0.621371
if from_unit == "celsius" and to_unit == "fahrenheit":
return value * 9 / 5 + 32
if from_unit == "fahrenheit" and to_unit == "celsius":
return (value - 32) * 5 / 9
raise ValueError("Unsupported unit conversion.")
def get_weather_mock(city: str) -> dict:
weather_data = {
"bucharest": {
"temperature_celsius": 23,
"condition": "sunny",
"wind_speed_kmh": 10,
},
"london": {
"temperature_celsius": 16,
"condition": "rain",
"wind_speed_kmh": 18,
},
}
key = city.lower()
if key not in weather_data:
return {
"city": city,
"error": "Weather data not available."
}
return {
"city": city,
**weather_data[key],
}
root_agent = Agent(
name="multi_tool_agent",
model="gemini-2.5-flash",
instruction=(
"You are a practical assistant. "
"Use the available tools when the user asks for calculations, "
"unit conversions, or weather information."
),
tools=[
calculator,
convert_units,
get_weather_mock,
],
)
Многоагентные системы: агенты, использующие других агентов
Системы с множеством агентов, использующие этапную структуру, работают наилучшим образом, когда их рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь граф. Сохраняйте состояние графа простым и типизированным. Вложенные структуры данных скрывают информацию о том, какой узел заполнил тот или иной поле, и приводят к нарушению возобновления работы после перерывов.
from google.adk.agents import LlmAgent
from google.adk.tools import google_search
from google.adk.tools import google_maps_grounding
from google.adk.tools.agent_tool import AgentTool
routing_agent = LlmAgent(
name="routing_agent",
model="gemini-2.5-pro",
instruction="""
You are a routing agent.
Use google_maps_grounding to estimate routes and travel times.
""",
tools=[google_maps_grounding],
)
discovery_agent = LlmAgent(
name="discovery_agent",
model="gemini-2.5-pro",
instruction="""
You are a travel discovery agent.
Use Google Search to find interesting places.
""",
tools=[google_search]
)
composer_agent = LlmAgent(
name="composer_agent",
model="gemini-2.5-pro",
instruction="""
Write a friendly travel itinerary based on the collected information.
""",
tools=[]
)
root_agent = LlmAgent(
name="travel_agent",
model="gemini-2.5-pro",
instruction="""
You are a travel assistant.
Coordinate discovery, routing, and itinerary composition.
""",
tools=[
AgentTool(discovery_agent),
AgentTool(routing_agent),
AgentTool(composer_agent)
]
)
Последовательные рабочие процессы и детерминистическая оркестрация
Этап последовательных рабочих процессов и детерминистичности работает наилучшим образом, когда рассматривается как измеримая структура. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Документируйте как успешный, так и восстановительный пути выполнения. Повторные попытки, проверки со стороны человека и обработка неработоспособных сообщений являются частью продукта, а не этапом последующей доработки. Сохраняйте структуру графа простой и типизированной. Вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний. Этап последовательных рабочих процессов и детерминистичности работает наилучшим образом, когда рассматривается как измеримая структура. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам документации, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задач.
from google.adk.agents import Agent, SequentialAgent
from google.adk.tools import AgentTool
planner_agent = Agent(
name="planner_agent",
model="gemini-2.5-flash",
instruction="""
Read the user request and create a short execution plan.
"""
)
executor_agent = Agent(
name="executor_agent",
model="gemini-2.5-flash",
instruction="""
Execute the plan and delegate specialist work.
""",
tools=[]
)
report_agent = Agent(
name="report_agent",
model="gemini-2.5-flash",
instruction="""
Produce the final report based on execution results.
"""
)
root_agent = SequentialAgent(
name="planner_executor_report_workflow",
sub_agents=[
planner_agent,
executor_agent,
report_agent,
],
)
Запуск агента ADK локально
На этапе запуска агента ADK необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не пытаясь угадать скрытое состояние. Рядом с функциональными результатами следует записывать время выполнения и стоимость токенов или запросов. Отображение затрат с самого начала помогает избежать неожиданных счетов при переходе от демо-среды к общедоступным средам. Для операций, связанных с расходами или изменением производственных данных, необходимо предусмотреть утверждение человеком. Подключение компонентов во время компиляции не гарантирует полноты реализации бизнес-логики.
GOOGLE_CLOUD_PROJECT=PROJECT_ID
GOOGLE_CLOUD_LOCATION=us-central1
GOOGLE_GENAI_USE_VERTEXAI=True
adk web
Развертывание агента в Google Cloud Run
Для развертывания агента на стадии подготовки необходимо заранее определить входные данные, ответственного за выполнение шага и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии системы. Храните конфигурацию отдельно от кода приложения. Файлы среды, хранилища конфиденциальных данных и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь кодовый граф. Внедряйте процедуру утверждения человеком для операций, связанных с тратой денег или изменением производственных данных. Подключение компонентов во время компиляции не гарантирует полноты бизнес-логики.
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
CMD ["adk", "web", "--host", "0.0.0.0", "--port", "8080"]
gcloud run deploy simple-agent \
--source . \
--region us-central1 \
--allow-unauthenticated \
--set-env-vars GOOGLE_GENAI_USE_VERTEXAI=TRUE \
--set-env-vars GOOGLE_CLOUD_PROJECT=PROJECT_ID \
--set-env-vars GOOGLE_CLOUD_LOCATION=us-central1
gcloud run services describe simple-agent \
--region us-central1 \
--format='value(status.url)'
Выпуск агента через FastAPI
На этапе «Раскрытие агента через интерфейс» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Необходимо одновременно задокументировать успешный сценарий выполнения и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Внедрять утверждение человеком для операций, связанных с тратой денег или изменением производственных данных. Настройка на этапе компиляции не гарантирует полноты функционала продукта. На этапе «Раскрытие агента через интерфейс» необходимо определить входные данные, ответственного за выполнение шага и критерии завершения перед внесением изменений в код. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия результатам работы, определите критерии успеха и не допускайте безответственного частичного завершения задачи.
import uuid
from fastapi import FastAPI
from pydantic import BaseModel
from google.adk.runners import Runner
from google.adk.sessions import InMemorySessionService
from google.genai import types
from agent import root_agent
app = FastAPI()
session_service = InMemorySessionService()
runner = Runner(
agent=root_agent,
app_name="weather_agent_service",
session_service=session_service,
)
class QueryRequest(BaseModel):
message: str
@app.post("/weather")
async def weather(request: QueryRequest):
user_id = "api_user"
session_id = str(uuid.uuid4())
await session_service.create_session(
app_name="weather_agent_service",
user_id=user_id,
session_id=session_id,
)
content = types.Content(
role="user",
parts=[
types.Part(text=request.message)
],
)
final_answer = ""
async for event in runner.run_async(
user_id=user_id,
session_id=session_id,
new_message=content,
):
if event.is_final_response():
final_answer = event.content.parts[0].text
return {
"response": final_answer
}
FROM python:3.11-slim
WORKDIR /app
COPY . .
RUN pip install --no-cache-dir -r requirements.txt
CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8080"]
Развертывание в Agent Engine
При работе над этапом развертывания в Agent Engine сначала запишите условия работы: необходимые параметры входных данных, сигнал о успешном выполнении и последствия частичной неудачи. Такой список поможет избежать ошибок при последующих изменениях кода. Рядом с результатами функционирования записывайте время выполнения операций, а также стоимость токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные счета при переходе от демо-среды к общедоступным средам. Создавайте контрольные точки после дорогостоящих операций. Функция возобновления работы не должна снова взимать плату за один и тот же вызов большой языковой модели, если оператор попытается выполнить следующий шаг заново.
gcloud services enable \
aiplatform.googleapis.com \
storage.googleapis.com
export STAGING_BUCKET="gs://${PROJECT_ID}-agent-staging"
gsutil mb -l us-central1 $STAGING_BUCKET
adk deploy agent_engine \
--project=$PROJECT_ID \
--region=us-central1 \
--staging_bucket=$STAGING_BUCKET \
basic_agent
Заключение
На этапе «Заключительные замечания» сначала запишите условия работы: необходимые входные данные, сигнал успешного выполнения и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Храните конфигурацию отдельно от кода приложения. Файлы с настройками окружения, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь кодовый граф. Создавайте контрольные точки после дорогостоящих операций. Функция возобновления работы не должна повторно взимать плату за один и тот же вызов большой языковой модели, когда оператор пытается выполнить следующий этап.
Чек-лист операционной деятельности
Этап чек-листа операционной деятельности работает наилучшим образом, если рассматривать его как измеримую основу. Соберите один эталонный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объема работ.
Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций.
Сохраняйте состояние графа в виде плоской структуры с явным типированием. Вложенные объекты скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.
При наличии бюджета добавляйте тесты для проверки критического пути в процессе интеграционного тестирования с использованием фикстур, а не реальных платных API.
Рассматривайте этот этап как контракт между входными данными и проверенными результатами. Дайте названия результатам обработки, определите критерии успеха и не соглашайтесь на молчаливое частичное выполнение задачи.
Сохраняйте состояние графа в виде плоской структуры с явным типированием. Вложенные объекты скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.
Перед переходом на новую версию стека заморозьте существующие версии, сохраните эталонный вариант результатов обработки критического пути и убедитесь в наличии шагов для возврата к предыдущей версии. В совместных средах необходимо вводить ограничения на частоту запросов, проверять принадлежность ресурсов и определять четкого ответственного за обновление секретов. Предпочитайте надежность любой сложной одноразовой демонстрации.
Примечание к версии 18b8374abe5a: не хранить ключи поставщиков в репозитории, установить лимит токенов на сессию и сохранять транскрипции рядом с фиксами для оценки, чтобы последующие замены моделей оставались сопоставимыми.