Vibe Coding AI Agents: Управление жизненным циклом агентов с помощью Agents CLI и ADK 2.0

1. Обзор

В этом практическом занятии вы узнаете, как использовать Agents CLI для управления полным циклом локальной разработки ИИ-агента. Независимо от того, используете ли вы существующие модели Gemini или создаете собственных агентов с нуля с помощью Agent Development Kit (ADK 2.0), Agents CLI предоставляет инструменты для создания, сборки, проверки и тестирования ваших агентов локально.

Что вы узнаете

  • Как установить и настроить agents-cli и связанные с ним навыки.
  • Как создать структуру для нового проекта по разработке агента.
  • Структура и ключевые файлы проекта агента графового рабочего процесса ADK 2.0.
  • Как запустить автоматическую проверку синтаксиса и очистку кода.
  • Как запустить и использовать локальную веб-площадку для интерактивного тестирования с автоматической перезагрузкой.

Что вам нужно

  • Python 3.11 или выше
  • менеджер пакетов UV
  • Node.js 18+ (при использовании навыков программирования)
  • Antigravity IDE (установите и настройте с сайта Google Antigravity )

Предварительные требования

В этом практическом занятии предполагается, что вы хорошо знакомы со следующими темами:

  • Используя терминал и командную строку.

Предварительного опыта работы с ИИ-агентами или ADK 2.0 не требуется!

2. Настройка аутентификации и среды.

Укажите свои учетные данные для аутентификации, чтобы агент мог звонить моделям Gemini.

Вариант 1: API-ключ Gemini (Google AI Studio)

Если вы используете стандартный ключ API Gemini (который можно получить в Google AI Studio ), экспортируйте его в терминале вашей IDE:

export GEMINI_API_KEY="your_api_key_here"
export GOOGLE_GENAI_USE_ENTERPRISE=FALSE

Вариант 2: Учетные данные по умолчанию для приложений Google Cloud

Если вы используете Vertex AI в Google Cloud, выполните аутентификацию с помощью учетных данных Google Cloud Application Default Credentials (ADC) и укажите свой активный проект Google Cloud:

gcloud auth application-default login
gcloud config set project <YOUR_PROJECT_ID>
export GOOGLE_GENAI_USE_ENTERPRISE=TRUE
export GOOGLE_CLOUD_PROJECT=REPLACE-WITH-YOUR-PROJECT_ID # Replace with your project ID
export GOOGLE_CLOUD_LOCATION=REPLACE-WITH-LOCATION # Replace the location

3. Настройка интерфейса командной строки и навыков агентов.

Первый шаг — установка инструмента agents-cli . Этот инструмент берет на себя основную работу по управлению проектами агентов.

После установки Antigravity выполните команду setup непосредственно в терминале.

👉 Откройте терминал и выполните:

uvx google-agents-cli setup

Эта команда автоматически устанавливает:

  1. Инструмент командной строки Agents CLI доступен глобально в вашей системе.
  2. Семь специализированных навыков программирования, которые Antigravity может использовать для создания, структурирования, оценки и развертывания агентов. Эти навыки устанавливаются один раз глобально в ~/.agents/skills/ и автоматически обнаруживаются Antigravity.

Примечание: Навыки устанавливаются в ~/.agents/skills/ и автоматически распознаются Antigravity. Вы можете проверить это с помощью команды /skills или настроек Antigravity.

Ожидаемый результат (в сокращенном виде):

█▀█ █▀▀ █▀▀ █▄ █ ▀█▀ █▀ █▀▀ █ █`
`█▀█ █▄█ ██▄ █ ▀█ █ ▄█ █▄▄ █▄ █`

`Your coding agent just got an upgrade.`

`1. Authentication`

`─────────────────`

`✓ Authenticated with Google Cloud`

`2. CLI Installation`

`───────────────────`

`▸ uv tool install google-agents-cli`

`✓ Installed google-agents-cli`

`3. Skills Installation`

`──────────────────────`

`▸ npx -y skills add https://github.com/google/agents-cli -y --all -g`

`◇ Found 7 skills`

`~/.agents/skills/google-agents-cli-adk-code`

`~/.agents/skills/google-agents-cli-deploy`

`~/.agents/skills/google-agents-cli-eval`

`~/.agents/skills/google-agents-cli-observability`

`~/.agents/skills/google-agents-cli-publish`

`~/.agents/skills/google-agents-cli-scaffold`

`~/.agents/skills/google-agents-cli-workflow`

4. Создайте свой проект агента.

В этом разделе вы создадите полностью структурированную директорию проекта, используя шаблон прототипа.

👉 Мгновенная антигравитация:

Use ADK 2.0 to create a new graph workflow agent project called
customer-support-agent. I don't want to deploy this agent, so you can skip
the deployment files. The workflow should act as a customer support
representative for a shipping company. It should first classify if the user
query is related to shipping (rates, tracking, delivery, returns) or
unrelated. If it is related to shipping, route to a shipping FAQ agent to
answer the question. If it is unrelated, route to a node that politely
declines to answer.

Antigravity автоматически запускает команду генерации кода ( agents-cli scaffold create customer-support-agent --prototype --yes ) и настраивает файлы проекта.

5. Изучите код агента.

👉 Обратитесь к Antigravity за разъяснением сгенерированного кода:

Read and explain the project structure of my new agent project. Walk me
through how `app/agent.py` is configured, highlighting the role of the
tools, nodes, edges, and the root Workflow.

В среде разработки Antigravity IDE вновь созданные файлы проекта и артефакты отображаются непосредственно во вспомогательной панели (слева). Там вы можете просмотреть app/agent.py или открыть его из проводника файлов IDE, чтобы изучить сгенерированный код.

# app/agent.py

from __future__ import annotations

from typing import Any, Literal

from google.adk.agents.context import Context
from google.adk.apps.app import App
from google.adk.events.event import Event
from google.adk.workflow import Edge
from google.adk.workflow import Workflow
from google.adk.workflow.agents.llm_agent import LlmAgent
from google.adk.workflow.node import node
from pydantic import BaseModel
from pydantic import Field


class InquiryCategory(BaseModel):
  category: Literal['shipping', 'unrelated'] = Field(
      description=(
          'Determine if the user query is related to shipping (rates, tracking,'
          ' delivery times, returns) or unrelated.'
      )
  )


def save_query(node_input: str):
  """Saves user query in state for downstream nodes."""
  yield Event(data=node_input, state={'user_query': node_input})


categorize_agent = LlmAgent(
    name='categorize',
    model='gemini-3.1-flash-lite',
    instruction='You are an expert classifier. Categorize the user query.',
    output_key='inquiry_category',
    output_schema=InquiryCategory,
)


@node
def route_inquiry(ctx: Context, node_input: Any):
  """Routes the workflow based on the classified category."""
  category_data = ctx.state.get('inquiry_category', {})
  category = category_data.get('category', 'unrelated')
  query = ctx.state.get('user_query', '')
  yield Event(data=query, route=category)


faq_agent = LlmAgent(
    name='shipping_faq',
    model='gemini-3.1-flash-lite'',
    instruction="""You are a customer support representative for a shipping company. Answer user questions based ONLY on the shipping FAQ below. Do not answer questions outside of the FAQ.
    
    SHIPPING FAQ:
    - Rates: Standard shipping is $5.99. Express shipping is $12.99. Orders
      over $50 qualify for free standard shipping.
    - Tracking: You can track your order by entering your tracking number on
      our website's tracking page.
    - Delivery Times: Standard delivery takes 3-5 business days. Express
      delivery takes 1-2 business days.
    - Returns: We offer free returns within 30 days of delivery. Please make
      sure the item is in its original condition.
    """,
)


@node
def handle_unrelated(ctx: Context, node_input: Any):
  """Handles unrelated inquiries politely."""
  yield Event(
      data=(
          'I am sorry, I am a shipping customer support assistant and can only'
          ' answer questions related to our shipping FAQ.'
      )
  )


root_agent = Workflow(
    name='customer_support_workflow',
    edges=[
        *Edge.chain('START', save_query, categorize_agent, route_inquiry),
        (route_inquiry, faq_agent, 'shipping'),
        (route_inquiry, handle_unrelated, 'unrelated'),
    ],
)

app = App(
    name='customer_support_agent',
    root_agent=root_agent,
)

Ключевые понятия

  • Рабочий процесс и ребра : В ADK 2.0 приложения агентов управляются в виде графа с использованием Workflow . Список edges определяет поток выполнения, связывая узлы вместе, начиная с START , и обеспечивая условное ветвление на основе маршрутов (например, маршрутизация к faq_agent по "shipping" или handle_unrelated по маршруту "unrelated" ).
  • LlmAgent : Декларативные узлы, определяющие задачи, работающие на основе LLM, с конкретными инструкциями, моделями и структурированными выходными данными ( output_schema ).
  • Узлы и контекст : функции Python, помеченные аннотацией @node (или стандартные функции), которые выполняют логику, получают доступ к состоянию выполнения через Context и возвращают объекты Event для передачи данных и сигналов маршрутизации по графу.
  • Модель : `gemini-3.1-flash-lite` используется в качестве модели быстрого вывода по умолчанию.
  • Оболочка приложения : Объект App верхнего уровня инкапсулирует корневой рабочий процесс. Внешние инструменты, такие как локальная среда разработки, оценочные среды ADK и среда выполнения агентов, обнаруживают и выполняют ваш рабочий процесс через этот стандартизированный интерфейс app .

6. Автоматическая проверка синтаксиса.

Перед запуском или тестированием агента рекомендуется убедиться в чистоте и правильном форматировании кода.

👉 Мгновенная антигравитация:

Run linting on my agent project to verify its health.

Antigravity будет запускать agents-cli lint в фоновом режиме для выполнения предварительно настроенных проверок, подтверждающих корректность импорта, синтаксиса и форматирования ваших файлов.

7. Интерактивное тестирование с помощью игровой площадки

Локальная веб-площадка — это самый быстрый способ проверить поведение вашего агента. Она предоставляет интерактивный чат, где вы можете общаться со своим агентом и проверять выполнение инструментов в режиме реального времени.

👉 Мгновенная антигравитация:

Launch the local development playground for my agent.

Antigravity запустит локальный сервер разработки ( agents-cli playground ). Откройте предоставленный URL-адрес (обычно http://127.0.0.1:8080/dev-ui/?app=app ) в веб-браузере, выберите папку app из выпадающего списка, чтобы начать общение с вашим агентом.

Начните общение со своим агентом в веб-интерфейсе. Попробуйте задать вопрос, связанный с доставкой: 

How much is standard shipping?

Обратите внимание, как рабочий процесс успешно классифицирует вопрос и направляет его к faq_agent для ответа. Также попробуйте задать несвязанный вопрос, чтобы убедиться, что рабочий процесс направляет к handle_unrelated и корректно отклоняет запрос на ответ: 

What is the weather like?

Протестируйте автоматическую перезагрузку в реальном времени.

В Playground вы можете увидеть, как изменения, внесенные вашим агентом в режиме реального времени, отображаются.

  1. Измените инструкцию faq_agent в app/agent.py , обратившись к Antigravity: 
    Modify the faq_agent instruction in app/agent.py to make the shipping rates
response more playful and enthusiastic. Add some emojis and highlight the
free shipping threshold.
  2. Отправьте новое сообщение агенту на тестовой площадке, чтобы проверить автоматическую перезагрузку:
    How much is standard shipping?
    Игровая площадка автоматически перезагружается и выполняет обновленный код в режиме реального времени без необходимости перезапуска сервера! Теперь в ответе вы должны увидеть несколько эмодзи.

8. Выполнение из командной строки

Для быстрых тестов, автоматизации или написания скриптов вы можете попросить Antigravity запустить вашего агента непосредственно из терминала.

👉 Мгновенная антигравитация: 

Run a CLI query asking my agent how long standard delivery takes.

Antigravity выполнит команду запроса ( agents-cli run "How long does standard delivery take?" ). Это позволит быстро выполнить одноходовой вывод и вывести окончательный ответ агента вместе с подробной информацией о выполнении инструмента.

9. Уборка

Чтобы избежать оставления нежелательных ресурсов в окружающей среде, выполните следующие действия по очистке:

  1. Остановка локальных серверов : Если ваш сервер agents-cli playground все еще запущен, остановите его в терминале, нажав Ctrl + C
  2. Удаление локальных файлов проекта : Удалите каталог проекта агента, созданного с помощью Scaffolded, с вашего локального компьютера. 
rm -rf customer-support-agent

10. Резюме и дальнейшие шаги

Поздравляем! Вы успешно завершили полный цикл локальной разработки ИИ-агента с помощью Agents CLI и ADK 2.0 .

Что вы узнали

  • Настройка инструментов : Установлен CLI агентов и настроены навыки рабочих процессов для Antigravity, специфичные для конкретного домена.
  • Создание структуры проекта : Разработан полностью структурированный проект customer-support-agent с использованием стандартизированных шаблонов.
  • Проанализирована структура ADK 2.0 : изучены рабочие процессы на основе графов, агенты LLM, узлы, ребра и условная маршрутизация.
  • Управление локальной работоспособностью : Выполнены автоматизированные проверки качества кода с помощью agents-cli lint .
  • Проверенное поведение : Протестирован агент в интерактивном режиме с возможностью перезагрузки в реальном времени через тестовую среду, а также проведены быстрые тесты в командной строке.

Что дальше?

Теперь, когда вы освоили цикл локальной разработки, вот как вы можете расширить и запустить свой агент в производственной среде:

  • Оценка : Оцените своего агента по набору данных evalset с помощью agents-cli eval run чтобы измерить точность и выявить регрессии.
  • Масштабирование корпоративного облака: развертывание и мониторинг : упакуйте и разверните свой агент в производственных средах, таких как Agent Runtime или Cloud Run, используя agents-cli deploy . Настройте телеметрию в производственной среде для потоковой передачи журналов и трассировок выполнения в Cloud Trace и BigQuery.

Дополнительные ресурсы