Практические замечания: я создал тот же агент тремя способами: через Interactions API, ADK и

В этом руководстве показано, как пройти путь от сырья до рабочей системы: я создал тот же агент тремя способами — через Interactions API, ADK и Antigravity SDK. Основное внимание уделяется выполнимым шагам, явным проверкам и коду, который можно просто добавить в репозиторий без необходимости догадываться о его назначении. На этапе обзора необходимо определить входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Регистрируйте время выполнения и стоимость токенов или запросов вместе с функциональными результатами. Отображение стоимости заранее помогает избежать неожиданных счетов при переходе от демо-среды к общедоступным средам.

Настройка и последовательное выполнение

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

export GOOGLE_API_KEY="..."   # get this at aistudio.google.com
gcloud auth application-default login

Метод 1: API взаимодействия, вы пишете инструмент и цикл

При работе над этапом API взаимодействий метода 1 сначала запишите контракт: необходимые входные данные, сигнал о успехе и то, что происходит при частичной неудаче. Такой чек-лист помогает сохранять честность при последующих изменениях кода. Документируйте одновременно успешный сценарий и сценарий восстановления. Повторные попытки, проверки человеком и обработка неработоспособных сообщений являются частью продукта, а не элементами последующей доработки. Фиксируйте имя инструмента, хеш аргументов, время задержки и результат каждого вызова. Без этой информации отладка агента занимает часы.

def execute_sql(query: str) -> list[dict]:
    client = bigquery.Client()
    config = bigquery.QueryJobConfig(maximum_bytes_billed=20 * 10**9)
    rows = client.query_and_wait(query, job_config=config, max_results=50)
    return [{k: str(v) for k, v in dict(row).items()} for row in rows]

execute_sql_tool = {
    "type": "function",
    "name": "execute_sql",
    "description": (
        "Run a BigQuery Standard SQL SELECT query against "
        "`bigquery-public-data.hacker_news.full`, the public Hacker News "
        "dataset (stories and comments since 2006). Columns: id INT, "
        "type STRING (story/comment/job/poll), title STRING (stories only), "
        "text STRING (body, HTML-escaped), `by` STRING (username), score INT, "
        "parent INT, descendants INT, timestamp TIMESTAMP, url STRING, "
        "dead BOOL, deleted BOOL. Returns at most 50 rows."
    ),
    "parameters": {
        "type": "object",
        "properties": {"query": {"type": "string"}},
        "required": ["query"],
    },
}

while True:
    calls = [s for s in interaction.steps if s.type == "function_call"]
    if not calls:
        break
    results = [{
        "type": "function_result",
        "name": step.name,
        "call_id": step.id,
        "result": [{"type": "text", "text": json.dumps(execute_sql(**step.arguments))}],
    } for step in calls]
    interaction = client.interactions.create(
        model=MODEL,
        input=results,
        system_instruction=INSTRUCTION,
        tools=[execute_sql_tool],
        previous_interaction_id=interaction.id,
    )

Метод 2: ADK — фреймворк предоставляет инструменты

При работе над этапом Method 2 ADK сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. Если какой-то шаг не сработает, причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций. Записывайте название инструмента, хеш аргументов, время задержки и результат каждого вызова. Без такой информации отладка занимает гораздо больше времени. При работе над этапом Method 2 ADK сначала запишите условия работы: необходимые входные данные, сигнал о успешном выполнении и действия при частичной неудаче. Такой список помогает сохранять честность при последующих изменениях кода. Рядом с функциональными результатами фиксируйте время выполнения и стоимость токенов или запросов. Отслеживание затрат с самого начала предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.

import google.auth
from google.adk import Agent
from google.adk.integrations.bigquery import BigQueryCredentialsConfig, BigQueryToolset
from google.adk.integrations.bigquery.config import BigQueryToolConfig, WriteMode

credentials, _ = google.auth.default()
toolset = BigQueryToolset(
    credentials_config=BigQueryCredentialsConfig(credentials=credentials),
    bigquery_tool_config=BigQueryToolConfig(write_mode=WriteMode.BLOCKED),
)
root_agent = Agent(name="hn_opinion_agent", model=..., instruction=..., tools=[toolset])

Метод 3: Antigravity SDK, крепление плюс MCP

Этап Antigravity SDK из Метода 3 работает наилучшим образом, когда рассматривается как измеримая поверхность. Сохраните один пример успешной работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объёма работ. Храните конфигурацию вне кода приложения. Файлы среды, хранилища секретов и флаги функций должны находиться в одном месте, чтобы операторы могли их проверять, не читая весь код. Обеспечьте доступ к инструментам с узкими схемами и чёткими метками побочных эффектов. Хостам необходимо знать, какие вызовы изменяют состояние, прежде чем они автоматически одобрят их.

from google.antigravity import Agent, LocalAgentConfig
from google.antigravity.types import McpStreamableHttpServer

bigquery_mcp = McpStreamableHttpServer(
    name="bigquery",
    type="http",
    url="https://bigquery.googleapis.com/mcp",
    headers={"Authorization": f"Bearer {token}",
             "x-goog-user-project": project},
    enabled_tools=["execute_sql_readonly", "get_table_info", ...],
)
config = LocalAgentConfig(system_instructions=..., mcp_servers=[bigquery_mcp])
async with Agent(config) as agent:
    response = await agent.chat(question)

Сравнение

Этап сравнения работает наилучшим образом, когда его рассматривают как измеримую поверхность. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Документируйте одновременно успешный и восстановительный пути выполнения. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не этапом последующей доработки. Сохраняйте структуру графа простой и типизированной; вложенные структуры скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.

Реализация

Этап обслуживания работает наилучшим образом, когда его рассматривают как измеримую среду. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Предпочитайте небольшие, тестируемые единицы кода вместо обширных скриптов. При сбое какого-либо шага причина должна быть связана с конкретной функцией, а не с запутанной цепочкой операций. Сохраняйте структуру графа простой и типизированной. Вложенные структуры данных маскируют информацию о том, какой узел заполнил тот или иной поле, что приводит к нарушению работоспособности после перерывов. Этап обслуживания работает наилучшим образом, когда его рассматривают как измеримую среду. Соберите один идеальный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию перед расширением объёма работ. Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отслеживание затрат на раннем этапе предотвращает неожиданные расходы при переходе с демо-среды в общедоступные среды.

Примечание по учётной записи сервиса

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

Какой вариант выбрать

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

Чек-лист операционной работы

Этап чек-листа операционной работы работает наилучшим образом, когда рассматривается как измеримая основа. Перед расширением объема работ необходимо собрать один эталонный пример работы, один случай сбоя и записку о возврате к предыдущему состоянию. Считайте этот этап договором между входными данными и проверенными результатами. Дайте названия всем элементам, определите критерии успеха и не допускайте молчаливого частичного завершения операций.

Сохраняйте состояние графа в виде плоской структуры с явным типированием. Вложенные объекты скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.

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

Записывайте временные показатели, а также стоимость токенов или запросов рядом с функциональными результатами. Отображение стоимости заранее помогает избежать неожиданных счетов при переходе с демо-среды в общедоступные среды.

Сохраняйте состояние графа в виде плоской структуры с явным типированием. Вложенные объекты скрывают информацию о том, какой узел заполнил тот или иной поле, и мешают возобновлению работы после прерываний.

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

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

При работе над этапом 0 записи по усилению безопасности сначала запишите контракт: необходимые входные данные, сигнал успешного завершения и последствия частичной неудачи. Такой чек-лист поможет сохранять честность при последующих изменениях кода. Рассматривайте этот этап как контракт между входными данными и проверенными выходными данными. Дайте названия результатам обработки, определите критерии успеха и не допускайте безусловного частичного завершения работы.

Деталь усиления безопасности 0/754: измерьте время выполнения, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранять изменение на основе фиксированного набора критериев, а не на основе устных замечаний.

На этапе 0 записей по укреплению безопасности лучше всего работает подход, при котором рассматривается измеримая поверхность. Соберите один идеальный пример работы, один случай сбоя и запись о возврате к предыдущему состоянию перед расширением объема работ. Документируйте одновременно успешный и восстановительный пути выполнения. Повторные попытки, проверки человеком и обработка неработающих сообщений являются частью продукта, а не последующими доработками.

Подробности укрепления безопасности 0/773: измеряйте время выполнения, класс ошибки и расход токенов для этой записи, затем принимайте решение о сохранении изменений на основе фиксированного набора вопросов, а не на основе устных описаний.

Для этапа 1 записей по укреплению безопасности определите входные данные, ответственного за шаг и критерии завершения перед изменением кода. Операторы должны иметь возможность перезапустить шаг с известной точки контроля, не догадываясь о скрытом состоянии. Рассматривайте этот этап как контракт между входными данными и проверенными выходными результатами. Дайте названия элементам, определите критерии успеха и не допускайте молчаливого частичного завершения работы.

Подробности усиления безопасности 1/773: измерьте время работы на стенде, класс ошибки и расход токенов для этой записи, затем решите, следует ли сохранять изменения на основе фиксированного набора вопросов, а не на основе единичных примеров.