Создайте автономную цепочку поставок с помощью Gemini 3 Flash и AlloyDB AI.

1. Обзор

Эпоха «читающих чат-ботов» подходит к концу. Мы вступаем в эпоху агентного зрения.

В этом практическом занятии мы будем реализовывать детерминированное проектирование ИИ — практику создания систем искусственного интеллекта, которые не делают предположений. Стандартные модели ИИ часто «галлюцинируют» (делают предположения), когда их просят подсчитать количество предметов на сложном изображении. В цепочке поставок предположение опасно. Если ИИ предполагает, что у вас 12 предметов, когда на самом деле их 15, это приводит к дорогостоящим ошибкам.

Мы создадим автономного агента для управления цепочкой поставок, используя новый цикл «Думай, действуй, наблюдай» в Gemini 3 Flash . Он не просто смотрит, он исследует.

Детерминированная архитектура

Начнём с «слепой» и «амнезичной» системы. Вы будете вручную «пробуждать» её чувства одно за другим:

1. «Глаза» (Агент зрения) : Мы активируем Gemini 3 Flash с выполнением кода . Вместо предсказания токенов для угадывания числа, модель пишет код на Python (OpenCV) для детерминированного подсчета пикселей.
2. Память (агент поставщика) : Мы используем AlloyDB AI с алгоритмом ScaNN (масштабируемый метод ближайших соседей). Это позволяет агенту за миллисекунды находить точного поставщика детали среди миллионов вариантов.
3. Протокол "рукопожатие" (A2A) : Мы обеспечиваем связь между агентами с использованием стандартизированного файла agent_card.json, что позволяет агенту Vision автономно заказывать товары у агента-поставщика.

Что вы построите

• Агент обработки изображений , выполняющий «визуальные вычисления» над видеопотоками с камер.
• Агент поставщика, использующий AlloyDB ScaNN для высокоскоростного векторного поиска.
• Интерфейс диспетчерской вышки с обновлениями WebSocket в реальном времени для визуализации автономного цикла.

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

• Как настроить AlloyDB с использованием векторных представлений и индексов ScaNN.
• Как включить Agentic Vision с помощью gemini-3-flash-preview, используя API Gemini.
• Как реализовать векторный поиск с использованием оператора <=> (косинусное расстояние) в AlloyDB.
• Как подключить агентов к AlloyDB с помощью коннектора AlloyDB для Python.
• Как использовать протокол A2A для динамического обнаружения агентов.

Требования

• Браузер, например Chrome или Firefox.
• Проект Google Cloud с включенной функцией выставления счетов.
• Ключ API Gemini (бесплатный уровень доступен в Google AI Studio ) для Vision Agent.

2. Прежде чем начать

Создать проект

1. В консоли Google Cloud на странице выбора проекта выберите или создайте проект Google Cloud.
2. Убедитесь, что для вашего облачного проекта включена функция выставления счетов. Узнайте, как проверить, включена ли функция выставления счетов для проекта .

Чтобы попробовать выполнить это задание, вы можете воспользоваться ссылкой на пробный период оплаты GCP: https://bit.ly/cvs14-ghj

Как использовать бонусы по этой ссылке? См . .

3. Вы будете использовать Cloud Shell — среду командной строки, работающую в Google Cloud. Нажмите «Активировать Cloud Shell» в верхней части консоли Google Cloud.

4. После подключения к Cloud Shell необходимо проверить, прошли ли вы аутентификацию и установлен ли идентификатор вашего проекта, используя следующую команду:

gcloud auth list

Настройка базы данных [AlloyDB]

Прежде всего, давайте подготовим базу данных — это займет около 15 минут, поэтому начнем с этого.

1. Нажмите кнопку ниже, чтобы открыть инструмент настройки AlloyDB в Cloud Shell:

Открыть в Google Cloud Shell

2. Запустите программу установки:

Sh run.sh

3. Воспользуйтесь функцией веб-предварительного просмотра (значок глаза 👁️ → Предварительный просмотр на порту 8080), чтобы открыть интерфейс настройки.
4. Введите идентификатор вашего проекта, выберите регион (например, us-central1) и создайте пароль для базы данных.

⚠️ СОХРАНИТЕ ЭТОТ ПАРОЛЬ — он понадобится вам, когда скрипт установки запросит его.

5. Нажмите «Начать развертывание» и подождите около 15 минут, пока кластер будет создан.

Получить код

Пока AlloyDB выполняет инициализацию (или после ее завершения), откройте репозиторий codelab в Cloud Shell:

Открыть в Google Cloud Shell

⚠️ ВАЖНО: После нажатия кнопки появится диалоговое окно безопасности. Установите флажок «Доверять репозиторию» и нажмите «Подтвердить».

В качестве альтернативы, можно клонировать вручную:

git clone https://github.com/MohitBhimrajka/visual-commerce-gemini-3-alloydb.git

cd visual-commerce-gemini-3-alloydb

Назначьте свой проект

В этом терминале Cloud Shell подтвердите, что ваш проект настроен:

gcloud config set project <YOUR_PROJECT_ID>

Включить публичный IP-адрес в AlloyDB

После завершения подготовки AlloyDB включите публичный IP-адрес, чтобы Python-коннектор мог подключаться из Cloud Shell:

1. Перейдите в консоль AlloyDB.
2. Щелкните по своему кластеру → щелкните по основному экземпляру
3. Нажмите «Редактировать».
4. Перейдите в раздел «Подключение по публичному IP-адресу» и установите флажок «Включить публичный IP-адрес».
5. Нажмите «Обновить экземпляр».

💡 Примечание: Коннектор AlloyDB для Python обрабатывает аутентификацию и шифрование — вам не нужно добавлять какие-либо авторизованные внешние сети.

Предоставить Vertex AI разрешения

Для генерации эмбеддингов учетной записи службы AlloyDB необходим доступ к Vertex AI. Запустите эту команду в том же окне Cloud Shell:

PROJECT_ID=$(gcloud config get-value project)


gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:service-$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")@gcp-sa-alloydb.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"

Запустите скрипт установки.

Теперь запустите скрипт настройки — он автоматически определит ваш экземпляр AlloyDB:

sh setup.sh

Что делает этот скрипт:

• Проверяет работу CLI gcloud, аутентификацию, проект и Python 3.
• Проверяет и включает необходимые API (AlloyDB, Vertex AI, Compute, Service Networking).
• Запрос на ввод вашего ключа API Gemini
• Автоматически определяет ваш экземпляр AlloyDB и извлекает регион, кластер и имя экземпляра.
• Запрашивает пароль от базы данных.
• Генерирует конфигурационный файл .env.
• Устанавливает зависимости Python.

💡 Советы по устранению неполадок:

• В консоли отображается не тот проект? Проверьте выпадающее меню проекта в верхнем левом углу консоли.
• AlloyDB не создает запрос? Сначала необходимо включить оплату. AlloyDB — высокопроизводительный движок, и без нее выделение ресурсов не произойдет.
• API отображают сообщение «Не включено» после включения? Подождите 60 секунд — задержка распространения сигнала действительно существует.
• Проблемы с региональной квотой? Если us-central1 не работает, попробуйте us-east1 или us-west1.

3. Настройка базы данных

Примечание: Если вы использовали полное руководство по Cloud Shell, все это было автоматизировано. В этом разделе объясняется, что происходило «под капотом».

В основе нашего приложения лежит AlloyDB для PostgreSQL . Мы будем использовать его мощные векторные возможности и индекс ScaNN для обеспечения семантического поиска практически в реальном времени, что позволит нашим агентам находить совпадения в тысячах записей за миллисекунды.

В этом разделе вы настроите схему, заполните данные и сгенерируете эмбеддинги — всё это в AlloyDB Studio.

Подключитесь к AlloyDB Studio

1. Перейдите к своему экземпляру AlloyDB в консоли AlloyDB.
2. В левой панели навигации нажмите AlloyDB Studio.
3. Аутентификация с помощью:
4. Имя пользователя : postgres
5. База данных : postgres
6. Пароль : Пароль, который вы установили при создании кластера.

Включить расширения

AlloyDB предоставляет встроенные расширения для работы с векторами и искусственным интеллектом. Выполните следующий SQL-запрос в AlloyDB Studio:

CREATE EXTENSION IF NOT EXISTS google_ml_integration CASCADE;
CREATE EXTENSION IF NOT EXISTS vector;
CREATE EXTENSION IF NOT EXISTS alloydb_scann CASCADE;

• google_ml_integration : Включает функцию ai.embedding() для прямого вызова Vertex AI из SQL.
• vector: Хранит и обрабатывает 768-мерные векторные представления.
• alloydb_scann : Включает индекс ScaNN от Google для сверхбыстрого векторного поиска.

Создайте таблицу инвентаризации.

DROP TABLE IF EXISTS inventory;

CREATE TABLE inventory (
    id SERIAL PRIMARY KEY,
    part_name TEXT NOT NULL,
    supplier_name TEXT NOT NULL,
    description TEXT,
    stock_level INT DEFAULT 0,
    part_embedding vector(768)
);

В столбце part_embedding хранятся 768-мерные векторы из text-embedding-005. Именно они обеспечивают работу семантического поиска.

Вставьте пример данных

Вставьте 20 позиций складского учета:

INSERT INTO inventory (part_name, supplier_name, description, stock_level) VALUES
('Cardboard Shipping Box Large', 'Packaging Solutions Inc', 'Heavy-duty corrugated cardboard shipping container, 24x18x12 inches', 250),
('Warehouse Storage Container', 'Industrial Supply Co', 'Stackable plastic storage bin with snap-lock lid, blue', 180),
('Product Shipping Boxes', 'Acme Packaging', 'Medium corrugated boxes for warehouse storage, 18x14x10 inches', 320),
('Industrial Widget X-9', 'Acme Corp', 'Heavy-duty industrial coupling for pneumatic systems', 50),
('Precision Bolt M4', 'Global Fasteners Inc', 'Stainless steel M4 allen bolt, 20mm length, grade A2-70', 200),
('Hexagonal Nut M6', 'Metro Supply Co', 'Galvanized steel hex nut M6, DIN 934 standard', 150),
('Phillips Head Screw 3x20', 'Acme Corp', 'Zinc-plated Phillips head wood screw, 3mm x 20mm', 500),
('Wooden Dowel 10mm', 'Craft Materials Ltd', 'Hardwood birch dowel rod, 10mm diameter x 300mm length', 80),
('Rubber Gasket Small', 'SealTech Industries', 'Buna-N rubber gasket, 25mm OD x 15mm ID, oil resistant', 120),
('Spring Tension 5kg', 'Mechanical Parts Co', 'Stainless steel compression spring, 5kg load capacity', 60),
('Bearing 6204', 'Bearings Direct', 'Deep groove ball bearing 6204-2RS, 20x47x14mm sealed', 45),
('Warehouse Shelf Boxes', 'Storage Systems Ltd', 'Standardized warehouse inventory boxes, corrugated, bulk pack', 400),
('Inventory Container Units', 'Supply Chain Pros', 'Modular stackable storage units for warehouse racking', 95),
('Aluminum Extrusion Bar', 'MetalWorks International', 'T-slot aluminum extrusion 20x20mm profile, 1 meter length', 110),
('Cable Tie Pack 200mm', 'ElectroParts Depot', 'Nylon cable ties, 200mm x 4.8mm, UV resistant black, pack of 100', 600),
('Hydraulic Hose 1/2 inch', 'FluidPower Systems', 'High-pressure hydraulic hose, 1/2 inch ID, 3000 PSI rated', 35),
('Safety Goggles Clear', 'WorkSafe Equipment Co', 'ANSI Z87.1 rated clear safety goggles, anti-fog coating', 275),
('Packing Tape Industrial', 'Packaging Solutions Inc', 'Heavy-duty polypropylene packing tape, 48mm x 100m, clear', 450),
('Stainless Steel Sheet 1mm', 'MetalWorks International', '304 stainless steel sheet, 1mm thickness, 300x300mm', 70),
('Silicone Sealant Tube', 'SealTech Industries', 'Industrial-grade RTV silicone sealant, 300ml cartridge, grey', 190);

Предоставить разрешение на встраивание

GRANT EXECUTE ON FUNCTION embedding TO postgres;

Создание векторных представлений

В этом примере используется встроенная функция AlloyDB ai.embedding() для прямого вызова модели text-embedding-005 от Vertex AI из SQL-запроса — код на Python не требуется:

UPDATE inventory
SET part_embedding = ai.embedding(
    'text-embedding-005',
    part_name || '. ' || description
)::vector
WHERE part_embedding IS NULL;

Это генерирует 768-мерные векторы, отражающие семантическое значение названия и описания каждой части. Индекс ScaNN будет использовать их для молниеносного поиска сходства. [Выполнение займет приблизительно 3-5 минут]

Создайте индекс ScaNN.

SET scann.allow_blocked_operations = true;

CREATE INDEX IF NOT EXISTS idx_inventory_scann
ON inventory USING scann (part_embedding cosine)
WITH (num_leaves=5, quantizer='sq8');

Почему именно ScaNN? Стандартный векторный поиск (HNSW) потребляет много памяти. По мере роста вашего склада до 100 миллионов деталей индекс становится слишком большим для оперативной памяти. ScaNN (масштабируемый поиск ближайших соседей) использует векторное квантование для сжатия векторов, чтобы индекс помещался в кэш L2 процессора. Это делает его до 10 раз быстрее, чем стандартный HNSW, для запросов с фильтрацией.

Проверьте, всё ли работает.

SELECT part_name, supplier_name, stock_level,
       (part_embedding IS NOT NULL) as has_embedding
FROM inventory
ORDER BY id;

Вы должны увидеть 20 строк, во всех из которых установлено значение has_embedding = true.

💡 Советы по устранению неполадок:

• "Расширение не найдено"? Возможно, экземпляр еще обновляется. Подождите несколько секунд и повторите попытку.
• Ошибка "Доступ запрещен" при встраивании? Распространение IAM занимает до 60 секунд. Повторно выполните команды GRANT и UPDATE.
• Несоответствие размерности вектора? В таблице используется vector(768) — используйте text-embedding-005. Другие модели имеют другую размерность.
• Функция встраивания возвращает NULL? Дважды проверьте, что роль IAM пользователя Vertex AI была предоставлена ​​учетной записи службы AlloyDB (см. предыдущий раздел).

4. Понимание архитектуры

Прежде чем вносить изменения в код, давайте разберемся, как устроена система. Архитектура следует схеме постепенного «пробуждения»:

Стек агентов

Vision Agent (agents/vision-agent/)

• agent.py — Логика Core Gemini 3 Flash. Отправляет изображения в модель с включенным выполнением кода, чтобы она записывала данные на Python (OpenCV) для детерминированного подсчета элементов.
• agent_executor.py — Обеспечивает связь между запросами протокола A2A и логикой агента.
• main.py — A2A-сервер Uvicorn, который обслуживает файл /.well-known/agent-card.json и обрабатывает запросы.

Агент поставщика (агенты/поставщик-агент/)

• inventory.py — Подключается к AlloyDB через коннектор AlloyDB Python (прокси-сервер аутентификации не требуется). Содержит функцию find_supplier(), которая выполняет векторный поиск ScaNN.
• agent_executor.py — Обеспечивает связь протокола A2A с логикой поиска в инвентаре.
• main.py — A2A-сервер Uvicorn с картой агента и конечной точкой проверки работоспособности.

Диспетчерская вышка (фронтенд/)

• app.py — сервер FastAPI + WebSocket, который обнаруживает агентов через A2A, организует конвейер обработки данных: зрение → поиск → заказ и передает обновления в реальном времени в браузер.

Поток A2A

• Диспетчерская вышка считывает файл /.well-known/agent-card.json от каждого агента.
• Обнаруживает возможности (навыки, конечные точки) — без жестко закодированных URL-адресов.
• Отправляет изображение в Vision Agent → получает количество элементов + описание
• Отправляет описание в виде запроса на встраивание агенту поставщика → получает частичное совпадение
• Оформляет заказы автономно.

Подключение к AlloyDB

Агент поставщика использует коннектор AlloyDB Python вместо традиционного прокси-сервера аутентификации:

from google.cloud.alloydbconnector import Connector

connector = Connector()
conn = connector.connect(
    inst_uri,       # Full instance URI
    "pg8000",       # Driver
    user="postgres",
    password=DB_PASS,
    ip_type="PUBLIC",  # Cloud Shell uses Public IP
)

Это автоматически обрабатывает аутентификацию IAM, SSL/TLS и маршрутизацию соединений. При последующем развертывании в Cloud Run просто измените ip_type на "PRIVATE" для доступа к VPC.

5. Шаг 1: Память (агент-поставщик)

Примечание : Если вы использовали руководство по Cloud Shell, вы уже внесли это изменение в код. В этом разделе объясняется, почему это важно и как это работает.

Агент поставщика запоминает миллионы деталей, используя AlloyDB ScaNN . В настоящее время он поставляется с запросом-заполнителем — своего рода «амнезиаком», который возвращает первую найденную строку независимо от того, что вы ищете.

Аудит: Амнезиак

Если сейчас отправить запрос агенту поставщика, он вернет случайный результат. Он не имеет понятия о сходстве. Давайте это исправим.

Запустить агента поставщика

Сервер A2A (main.py) делегирует управление скрипту agent_executor.py, который обеспечивает связь протокола с бизнес-логикой в ​​скрипте inventory.py .

💡 Совет по устранению неполадок: Если вы получаете ошибки типа «адрес уже используется», завершите существующие процессы и попробуйте снова:

pkill -f uvicorn #Kill all uvicorn processes

Шаг 1: Перейдите в каталог агентов.

cd agents/supplier-agent

Шаг 2: Установка зависимостей

pip install -r requirements.txt

Шаг 3: Запустите сервер агента.

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

Команда `> /dev/null 2>&1 &` запускает сервер в фоновом режиме и подавляет вывод, чтобы не прерывать работу терминала.

Шаг 4: Убедитесь, что агент запущен (подождите 2-3 секунды после запуска).

curl http://localhost:8082/.well-known/agent-card.json

Ожидаемый результат: JSON с конфигурацией агента (должен возвращаться без ошибок).

Решение: Реализация оператора <=>

Откройте файл agents/supplier-agent/inventory.py и найдите функцию find_supplier() примерно в строках 60-70 . Вы увидите заполнитель:

# TODO: Replace this placeholder query with ScaNN vector search

sql = "SELECT part_name, supplier_name FROM inventory LIMIT 1;"
cursor.execute(sql)

Замените эти две строки следующим содержимым:

sql = """
SELECT part_name, supplier_name,
       part_embedding <=> %s::vector as distance
FROM inventory
ORDER BY part_embedding <=> %s::vector
LIMIT 1;
"""
cursor.execute(sql, (embedding_str, embedding_str))

Что это делает:

• <=> — это оператор косинусного расстояния в PostgreSQL.
• ORDER BY part_embedding <=> %s::vector находит ближайшее совпадение (наименьшее расстояние = ближайшее семантическое значение)
• %s::vector преобразует ваш массив вложений в векторный тип PostgreSQL.
• Индекс ScaNN автоматически ускоряет выполнение этого запроса!

Шаг 4: Сохраните файл (Ctrl+S или Cmd+S)

Теперь агент будет использовать семантический поиск вместо возврата случайных результатов!

Проверка

Проверка обнаружения A2A и инвентаризации:

curl http://localhost:8082/.well-known/agent-card.json

python3 -c "
from inventory import find_supplier
import json
vec = [0.1]*768
r = find_supplier(vec)
if r:
    result = {'part': r[0], 'supplier': r[1]}
    if len(r) > 2:
        result['distance'] = float(r[2]) if r[2] else None
    print(json.dumps(result))
else:
    print('No result found')
"

Ожидалось: файл agent-card.json возвращает карточку агента. Приведенный фрагмент кода на Python возвращает информацию о детали и поставщике из исходных данных.

Распространенные ошибки:

• "Нет такого файла или каталога" : Вы находитесь не в корневом каталоге репозитория. Перейдите в корневой каталог с помощью команды `cd`, затем перейдите в каталог `visual-commerce-gemini-3-alloydb` или используйте команду `pwd`, чтобы узнать, где вы находитесь.
• Порт 8082 используется : Завершить существующий процесс: lsof -ti:8082 | xargs kill -9
• ModuleNotFoundError : Установка зависимостей: pip install -r requirements.txt
• Не удалось подключиться к базе данных: проверьте файл .env — заполните поля ALLOYDB_REGION, ALLOYDB_CLUSTER и ALLOYDB_INSTANCE.
• Соединение отклонено: Убедитесь, что публичный IP-адрес включен в вашем экземпляре AlloyDB.
• Сбой скрипта проверки: Убедитесь, что заполнение начальной ячейки прошло успешно на шаге 4.

6. Шаг 2: Глаза (Видящий агент)

Примечание: Если вы использовали руководство по Cloud Shell, вы уже включили выполнение кода. В этом разделе объясняется архитектура и почему такой подход исключает галлюцинации.

Пока база данных доступна, давайте пробудим зрение с помощью Gemini 3 Flash . Агент Vision выполняет «визуальные вычисления» посредством выполнения кода.

Аудит: Галлюцинация

Если задать стандартной мультимодальной модели вопрос: «Сколько квадратов на этом беспорядочном изображении?», она обработает изображение как статический снимок и сделает предположение.

• Модель говорит: «Я вижу около 12 коробок».
• В действительности: коробок 15.
• Результат: Сбой в цепочке поставок.

Решение: Пробуждение цикла «Думай-Действуй-Наблюдай»

Мы включаем выполнение кода и ThinkingConfig , чтобы модель писала код на Python (OpenCV) для детерминированного подсчета.

1. Откройте файл agents/vision-agent/agent.py.
2. Найдите раздел GenerateContentConfig (примерно строки 68-78).
3. Раскомментируйте блок thinking_config=types.ThinkingConfig(...) и tools=[types.Tool(code_execution=...)].
4. Клиент уже настроен на использование вашего GEMINI_API_KEY из среды выполнения.

Совет: параметр thinking_level="MINIMAL" обеспечивает баланс между скоростью и точностью. Допустимые значения: "MINIMAL", "LOW", "MEDIUM", "HIGH". Требуется google-genai>=1.56.0.

Примечание к архитектуре: Агент обработки изображений использует API Gemini (ключ API), а агент поставщика — встраивания Vertex AI (учетные данные GCP). Такой гибридный подход упрощает компонент обработки изображений, сохраняя при этом возможности базы данных корпоративного уровня.

Файл: agents/vision-agent/agent.py

config = types.GenerateContentConfig(
    temperature=0,
    # CODELAB STEP 1: Uncomment to enable reasoning
    thinking_config=types.ThinkingConfig(
        thinking_level="MINIMAL",  # Valid: "MINIMAL", "LOW", "MEDIUM", "HIGH"
        include_thoughts=False    # Set to True for debugging
    ),
    # CODELAB STEP 2: Uncomment to enable code execution
    tools=[types.Tool(code_execution=types.ToolCodeExecution)]
)

Почему thinking_level="MINIMAL"?

Для этой задачи (подсчет предметов посредством выполнения кода) уровень "MINIMAL" обеспечивает достаточное обоснование для планирования скрипта и проверки подсчета. Использование уровня "HIGH" увеличит задержку в 2-3 раза без повышения точности для детерминированных задач. Оптимизация соотношения затрат и производительности — соотнесите глубину обоснования со сложностью задачи.

Оптимизация соотношения затрат и производительности — ключевой навык для разработки ИИ-приложений: необходимо соотносить глубину рассуждений со сложностью задачи.

Запустите агента Vision

🔄 Проверка пути: Если вы все еще находитесь в папке agents/supplier-agent/, сначала вернитесь в корневую папку репозитория с помощью команды cd ../..

Шаг 1: Перейдите в каталог агентов Vision.

cd agents/vision-agent

Шаг 2: Установка зависимостей

pip install -r requirements.txt

Шаг 3: Запустите сервер агента Vision.

uvicorn main:app --host 0.0.0.0 --port 8081 > /dev/null 2>&1 &

Команда `> /dev/null 2>&1 &` запускает сервер в фоновом режиме и подавляет вывод, чтобы не прерывать работу терминала.

Проверка

Проверка обнаружения A2A:

curl http://localhost:8081/.well-known/agent-card.json

Ожидается: JSON с именем агента и его навыками. Фактический подсчет обнаруженных объектов вы проверите с помощью пользовательского интерфейса диспетчерской вышки на шаге 8.

Распространенные ошибки:

• " Нет такого файла или каталога ": Вы находитесь не в корневом каталоге репозитория. Используйте команду `cd ../..`, чтобы вернуться в корневой каталог репозитория, или проверьте свое местоположение с помощью команды `pwd`.
• Порт 8081 занят: Завершить существующий процесс: lsof -ti:8081 | xargs kill -9
• Параметр GEMINI_API_KEY не установлен: проверьте наличие файла .env в корневом каталоге репозитория с помощью команды `cat .env | grep GEMINI_API_KEY`.
• Ключ API недействителен : убедитесь, что ваш ключ верен и не просрочен.
• google-genai не найден: Установите зависимости: pip install -r requirements.txt

7. Шаг 3: Рукопожатие (Карточка агента A2A)

Примечание: Если вы использовали руководство по Cloud Shell, вы уже создали эту карточку агента. В этом разделе объясняется протокол A2A и почему он обеспечивает создание агентов по принципу «подключи и работай».

Наш агент видит проблему (Vision) и знает поставщика (Memory). Протокол A2A обеспечивает динамическое обнаружение — интерфейс обучается взаимодействию с каждым агентом, считывая его карточку.

A2A против традиционных REST API

Аспект	Традиционный ОТДЫХ	Протокол A2A
Обнаружение конечных точек	Закодированные URL-адреса в конфигурации	Динамическое управление через /.well-known/agent-card.json
Описание возможностей	Документация API (для пользователей)	Навыки (машинночитаемые)
Интеграция	Ручной код для каждой услуги	Семантическое сопоставление: "Мне нужен поиск по инвентарю" → обнаруживает навык
Добавлен новый агент.	Обновите конфигурации всех клиентов.	Настройка не требуется — автоматическое обнаружение

Практическое преимущество: В традиционной микросервисной архитектуре, если добавить третьего «агента логистики», потребуется обновить код диспетчерской вышки, добавив его URL-адрес и контракт API. С A2A диспетчерская вышка обнаруживает его автоматически и понимает его возможности благодаря описаниям навыков на естественном языке.

Именно поэтому A2A обеспечивает возможность подключения и использования агентов по принципу Plug-and-Play — архитектурный шаблон для автономных систем.

Создайте карточку агента

🔄 Проверка пути: Если вы все еще находитесь в папке agents/vision-agent/, сначала вернитесь в корневую папку репозитория с помощью команды cd ../..

Карточка агента уже включена в файл agents/supplier-agent/agent_card.json. Откройте его и просмотрите:

{
  "name": "Acme Supplier Agent",
  "description": "Autonomous fulfillment for industrial parts via AlloyDB ScaNN.",
  "version": "1.0.0",
  "skills": [{
    "id": "search_inventory",
    "name": "Search Inventory",
    "description": "Searches the warehouse database for semantic matches using AlloyDB ScaNN vector search.",
    "tags": ["inventory", "search", "alloydb"],
    "examples": ["Find stock for Industrial Widget X-9", "Who supplies ball bearings?"]
  }]
}

Вы можете изменить название, описание или примеры в соответствии с вашими потребностями.

Перезапустите агент поставщика, чтобы загрузить карту:

Шаг 1: Остановите работающее устройство.

pkill -f "uvicorn main:app.*8082"

Шаг 2: Перейдите в каталог агентов.

cd agents/supplier-agent

Шаг 3: Запустите агента снова.

uvicorn main:app --host 0.0.0.0 --port 8082 > /dev/null 2>&1 &

Команда `> /dev/null 2>&1 &` запускает сервер в фоновом режиме и подавляет вывод, чтобы не прерывать работу терминала.

Шаг 4: Проверьте новую карту агента (подождите 2-3 секунды после начала).

curl http://localhost:8082/.well-known/agent-card.json

Ожидаемый результат: JSON с заполненными вами именем, описанием и навыками.

8. Шаг 4: Диспетчерская вышка

Примечание: Если вы использовали руководство по Cloud Shell, ваши сервисы уже запущены. Перейдите к разделу «Проверка системы» ниже, чтобы получить доступ к Control Tower и посмотреть, как работает автономный рабочий процесс.

Запустите интерфейс Control Tower с помощью FastAPI + WebSockets. Он обнаруживает агентов через A2A и управляет полным циклом с обновлениями в реальном времени.

Запустить все службы

Самый простой способ запустить все сервисы:

Убедитесь, что вы находитесь в корневом каталоге репозитория.

pwd  # Should end with: visual-commerce-gemini-3-alloydb

Затем,

sh run.sh

Эта единственная команда запускает:

• Агент Vision на порту 8081
• Представитель поставщика в порту 8082
• Диспетчерская вышка в порту 8080

Подождите примерно 10 секунд, пока все службы инициализируются.

💡 Совет по устранению неполадок : Если скрипт run.sh завершается с ошибкой " адрес уже используется ":

Завершите все службы и попробуйте снова.

pkill -f uvicorn

sh run.sh

Это происходит, если службы все еще запущены после предыдущей попытки.

Проверьте систему

Получите доступ к диспетчерской вышке:

1. Нажмите кнопку «Предварительный просмотр веб-страницы» (значок глаза 👁️) на панели инструментов Cloud Shell.
2. Выберите " Предварительный просмотр на порту 8080 "
3. Панель управления диспетчерской вышки откроется в новой вкладке.

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

Запустите демоверсию:

1. В правом верхнем углу: состояние подключения (зеленая точка «Live»), переключение между режимами DEMO/AUTO и элементы управления звуком.
2. Центр : Основное рабочее поле с загрузкой изображений и визуализацией анализа.
3. Боковые панели (появляются во время анализа): временная шкала рабочего процесса (слева), отслеживание прогресса и просмотр кода (справа).

Вариант 1: Быстрый старт (рекомендуется)

1. На главной странице вы увидите раздел « Быстрый старт » с примерами изображений.
2. Щелкните по любому изображению-образцу , чтобы автоматически начать анализ.
3. Посмотрите, как работает автономный процесс (примерно 30-45 секунд).

Вариант 2: Загрузите свой собственный файл.

1. Перетащите изображение склада/полки (PNG, JPG, до 10 МБ) или выберите нужный файл, нажав на него.
2. Нажмите « Запустить автономный рабочий процесс ».
3. Ознакомьтесь с четырехэтапным конвейером обработки данных.

Что происходит:

1. Обнаружение агентов: в модальных окнах протокола A2A отображаются карточки агентов Vision и агентов-поставщиков с указанием их навыков и конечных точек.
2. Анализ изображений: Gemini 3 Flash генерирует и выполняет код на Python (OpenCV) для подсчета элементов. Индикатор выполнения показывает подшаги. На обнаруженные элементы накладываются ограничивающие рамки. Значок результата показывает «✓ Код проверен» или «~ Предполагаемое значение».
3. Поиск поставщика: анимация векторного поиска AlloyDB ScaNN. Отображается поисковый запрос (например, «промышленные металлические коробки»). В карточке результатов отображается найденная деталь, поставщик и оценка достоверности.
4. Заказ оформлен: Чек с идентификатором заказа, количеством и подробной информацией.

Совет: Оставьте режим DEMO включенным (в правом верхнем углу), чтобы приостанавливать работу на каждом этапе для презентаций. В режиме AUTO рабочий процесс выполняется непрерывно.

Что только что произошло?

Диспетчерская вышка использовала протокол A2A для обнаружения обоих агентов через файл /.well-known/agent-card.json, организовала анализ изображений (Gemini 3 Flash с выполнением кода), выполнила векторный поиск (AlloyDB ScaNN) и разместила автономный заказ — всё с обновлениями WebSocket в реальном времени. Каждый агент предоставляет свои возможности через стандарт A2A, что позволяет создавать конфигурации по принципу «подключи и работай» без использования пользовательских SDK. Подробнее: Протокол A2A

Поиск неисправностей

Ошибки, связанные с путями:

• Сообщение " Нет такого файла или каталога " при выполнении команд означает, что вы находитесь не в корневом каталоге репозитория.

# Check where you are
pwd

# If you're lost, navigate to home and back to repo
cd
cd visual-commerce-gemini-3-alloydb

Ошибки сервиса:

• " Адрес уже используется ": процессы из предыдущих запусков все еще активны.

# Kill all services and restart
pkill -f uvicorn
sh run.sh  # Or manually restart individual agents

• Службы не запускаются : проверьте, не заняты ли порты:

# Check which processes are using the ports
lsof -i :8080  # Control Tower
lsof -i :8081  # Vision Agent
lsof -i :8082  # Supplier Agent

• Сообщение "Соединение с AlloyDB отклонено": Убедитесь, что публичный IP-адрес включен в вашем экземпляре AlloyDB.

9. 🎁 Бонус: Развертывание в облаке.

Необязательно — всё работает локально! Но если вы хотите поделиться своим творением по общедоступному URL-адресу:

# From repo root
sh deploy/deploy.sh

Что происходит:

1. Считывает ваш файл конфигурации .env.
2. Запрашивает ваше имя (отображается в развернутом приложении).
3. Развертывает все 3 сервиса в виде единого контейнера Cloud Run.
4. Предоставляет роли IAM для доступа к AlloyDB.
5. Выводит URL-адрес, которым можно поделиться.

Посетители, открывшие ваш URL-адрес, увидят всплывающее окно:

🚀 Развернуто под вашим именем — Работает на Gemini 3 Flash · AlloyDB AI · Протокол A2A

Выполнено в рамках 14-го сезона Code Vipassana.

[Попробуйте выполнить задание самостоятельно →]

10. Уборка

Во избежание дополнительных расходов удалите все ресурсы с помощью автоматического скрипта очистки:

# From repo root
sh deploy/cleanup.sh

Это безопасно удаляет:

• Кластер AlloyDB (основной фактор, влияющий на стоимость)
• Сервисы Cloud Run (если развернуты)
• Связанные сервисные счета

Перед удалением скрипт запросит подтверждение.

11. Список литературы и дополнительные материалы

Все технические утверждения в этом практическом занятии проверены на основе официальной документации Google Cloud и Google AI.

Официальная документация

Gemini 3 Flash:

• API выполнения кода: https://cloud.google.com/vertex-ai/generative-ai/docs/model-reference/code-execution-api
• Руководство для разработчиков: https://ai.google.dev/gemini-api/docs/gemini-3
• Документация по модели: https://docs.cloud.google.com/vertex-ai/generative-ai/docs/models/gemini/3-flash
• Модель карты: https://deepmind.google/models/gemini/flash/

AlloyDB AI & ScaNN:

• Тесты производительности ScaNN: https://cloud.google.com/blog/products/databases/how-scann-for-alloydb-vector-search-compares-to-pgvector-hnsw
• Понимание индекса ScaNN: https://cloud.google.com/blog/products/databases/understanding-the-scann-index-in-alloydb
• Подробный анализ AlloyDB AI: https://cloud.google.com/blog/products/databases/alloydb-ais-scann-index-improves-search-on-all-kinds-of-data
• Рекомендации по оптимизации производительности: https://docs.cloud.google.com/alloydb/docs/ai/best-practices-tuning-scann
• Документация AlloyDB: https://cloud.google.com/alloydb/docs

MCP Toolbox for Databases (альтернативный подход):

• MCP Toolbox: https://googleapis.github.io/genai-toolbox/getting-started/introduction/

Информация о ценах:

• Цены на Gemini API: https://ai.google.dev/gemini-api/docs/pricing
• Цены на AlloyDB: https://cloud.google.com/alloydb/pricing
• Цены на Vertex AI: https://cloud.google.com/vertex-ai/pricing

Подтвержденные заявления о производительности

Особенность	Требовать	Источник
ScaNN против HNSW (отфильтровано)	В 10 раз быстрее	Блог Google Cloud (проверено)
ScaNN против HNSW (стандарт)	В 4 раза быстрее	Блог Google Cloud (проверено)
Объем памяти, занимаемый ScaNN	в 3-4 раза меньше	Блог Google Cloud (проверено)
Время построения индекса ScaNN	В 8 раз быстрее	Блог Google Cloud (проверено)
Таймаут выполнения кода	максимум 30 секунд	Документация Google Cloud (проверено)
Ввод-вывод файлов выполнения кода	Не поддерживается	Документация Google Cloud (проверено)
Поведение при температуре = 0	Детерминированный результат	Подтверждено сообществом

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

Протокол взаимодействия между агентами (A2A):

• A2A стандартизирует обнаружение агентов и обмен информацией.
• Карты агентов размещены по адресу /.well-known/agent-card.json
• Формирующийся стандарт для взаимодействия автономных агентов

Исследование ScaNN:

• На основе 12 лет исследований Google.
• Обеспечивает работу Google Search и YouTube в масштабах миллиарда пользователей.
• Дата выхода в широкую продажу: октябрь 2024 года.
• Первый векторный индекс PostgreSQL, подходящий для векторов объемом от миллионов до миллиардов.

12. Режим испытаний: Повышайте уровень своих агентских навыков.

Вы создали работающую автономную цепочку поставок. Готовы двигаться дальше? Эти задачи позволят применить изученные вами методы к решению новых проблем.

Задача 1: Поиск на основе изображений (мультимодальные встраивания)

Текущий алгоритм: Агент Vision подсчитывает количество элементов → генерирует текстовый запрос → Агент Supplier встраивает текст → выполняет поиск в AlloyDB

Задача: Полностью обойтись без текста — отправить обрезанное изображение напрямую агенту поставщика.

Подсказки:

1. Выполнение кода Vision Agent позволяет вырезать отдельные элементы из изображения на полке.
2. Модель multimodalembedding@001 от Vertex AI может напрямую встраивать изображения.
3. Измените файл inventory.py, чтобы он принимал байты изображения вместо текста.
4. Обновите описание навыка A2A, указав: «Принимает: изображения/jpeg или текст».

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

Задача 2: Наблюдаемость — Доверие через прозрачность

Текущее состояние: Система работает, но заглянуть "под капот" невозможно.

Задача: Проанализировать журналы запросов AlloyDB, чтобы доказать, что векторный поиск выполняется.

Шаги:

• Функция анализа запросов включена по умолчанию в AlloyDB. Для проверки выполните следующую команду:

gcloud alloydb instances describe INSTANCE_NAME \
  --cluster=CLUSTER_NAME \
  --region=us-central1 \
  --format="value(queryInsightsConfig.queryPlansPerMinute)"

• Выполните поиск поставщика через пользовательский интерфейс.
• Посмотреть фактический выполненный SQL-запрос:

gcloud logging read \
  'resource.type="alloydb.googleapis.com/Instance" AND textPayload:"ORDER BY part_embedding"' \
  --limit 5 \
  --format=json

Ожидаемый результат: Вы увидите точный запрос ORDER BY part_embedding <=> $1::vector LIMIT 1 с указанием времени выполнения.

Почему это важно: Наблюдаемость укрепляет доверие. Когда заинтересованные стороны спрашивают: «Как этот агент принимает решения?», вы можете показать им план выполнения запроса, а не только результат.

Задача 3: Составление многоагентной структуры

Задача: Добавить третьего агента (агента по логистике), который будет рассчитывать стоимость доставки на основе местоположения склада и веса товара.

Архитектура:

• Результаты работы Vision Agent: количество элементов
• Выходные данные агента поставщика: местоположение поставщика
• Входные данные для логистического агента (НОВИНКА): пункт назначения, вес → выходные данные: стоимость доставки + расчетное время прибытия

Подсказка: Протокол A2A делает это тривиальным — создайте новую карточку агента с навыком calculate_shipping. Центр управления обнаружит её автоматически.

Изучаемый шаблон: это ядро ​​агентно-ориентированной архитектуры — сложных систем, построенных из небольших, компонуемых специалистов.

13. Заключение

Вы успешно перешли от генеративного ИИ к агентному ИИ .

Что мы построили:

• Видение: Мы заменили «угадывание» выполнением кода (прошивка Gemini 3 через API-ключ).
• Память: Мы заменили "медленный поиск" на AlloyDB ScaNN (через GCP).
• Действие: Мы заменили "интеграцию API" протоколом A2A .

Преимущества гибридной архитектуры:

В этом практическом занятии был продемонстрирован гибридный подход:

• Vision Agent: Использует API Gemini (ключ API) — доступен простой бесплатный тариф, не требуется оплата через GCP.
• Агент поставщика: использует GCP (Vertex AI + AlloyDB) — решение корпоративного уровня, готовое к соблюдению нормативных требований.

Это архитектура автономной экономики. Код остаётся за вами.

Следующие шаги

• Получите свой API-ключ Gemini (доступен бесплатный тариф).
• Изучите документацию по API Gemini.
• Ознакомьтесь с документацией AlloyDB AI.
• Изучите возможности выполнения кода в Gemini.