Создание и развертывание агента ADK в Cloud Run

1. Введение

Эта лабораторная работа посвящена реализации и развертыванию клиентского агентского сервиса. Вы будете использовать Agent Development Kit (ADK) для создания агента искусственного интеллекта , использующего соответствующие инструменты.

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

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

Наконец, мы развернем агента гида в Google Cloud Run , а не будем запускать его локально.

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

  • Проект Google Cloud с включенной функцией выставления счетов.

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

  • Как структурировать проект на Python для развертывания в ADK .
  • Как реализовать агента, использующего инструменты, с помощью Google AdK.
  • Как развернуть приложение Python в виде бессерверного контейнера в Cloud Run .
  • Как настроить безопасную аутентификацию между сервисами с использованием ролей IAM .
  • Как удалить облачные ресурсы, чтобы избежать будущих затрат.

Что вам понадобится

  • Аккаунт Google Cloud и проект Google Cloud
  • Веб-браузер, например Chrome.

2. Почему стоит развертывать приложения в Cloud Run?

Cloud Run — отличный выбор для размещения агентов ADK , поскольку это бессерверная платформа, а это значит, что вы можете сосредоточиться на своем коде, а не на управлении базовой инфраструктурой. Мы берем на себя операционную работу.

Представьте это как временный магазин: он открывается и использует ресурсы только тогда, когда поступают заказы. Когда заказов нет, он полностью закрывается, и вы не платите за пустой магазин.

Основные характеристики

Запускает контейнеры где угодно:

  • Вы предоставляете контейнер (образ Docker), внутри которого находится ваше приложение.
  • Cloud Run запускает его на инфраструктуре Google.
  • Никаких проблем с обновлением ОС, настройкой виртуальных машин или масштабированием.

Автоматическое масштабирование:

  • Если приложением пользуются 0 человек, то запускается 0 экземпляров (масштабирование до нуля экземпляров экономически выгодно).
  • Если поступает 1000 запросов, то запускается столько копий, сколько необходимо.

По умолчанию не сохраняющее состояние:

  • Каждый запрос может быть направлен в отдельный экземпляр.
  • Если вам необходимо хранить состояние, используйте внешний сервис, такой как Cloud SQL, Firestore или Memorystore.

Поддерживает любой язык программирования или фреймворк:

  • Пока приложение работает в контейнере Linux, Cloud Run неважно, используется ли Python, Go, Node.js, Java или .Net.

Платите только за то, что используете:

3. Настройка проекта

Аккаунт Google

Если у вас еще нет личного аккаунта Google, вам необходимо его создать .

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

Войдите в консоль Google Cloud.

Войдите в консоль Google Cloud, используя личную учетную запись Google.

Включить выставление счетов

Создайте личный платежный аккаунт.

Если вы настроили оплату с использованием кредитов Google Cloud, этот шаг можно пропустить.

Чтобы настроить личный платежный аккаунт, перейдите сюда, чтобы включить оплату в облачной консоли.

Несколько замечаний:

  • Выполнение этой лабораторной работы должно обойтись менее чем в 1 доллар США в виде облачных ресурсов.
  • В конце этой лабораторной работы вы можете выполнить действия по удалению ресурсов, чтобы избежать дальнейших списаний средств.
  • Новые пользователи могут воспользоваться бесплатной пробной версией стоимостью 300 долларов США .

Создать проект (необязательно)

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

4. Откройте редактор Cloud Shell.

  1. Нажмите на эту ссылку, чтобы перейти непосредственно в редактор Cloud Shell.
  2. Если сегодня вам будет предложено авторизоваться, нажмите «Авторизовать» , чтобы продолжить. Нажмите, чтобы авторизовать Cloud Shell.
  3. Если терминал не отображается внизу экрана, откройте его:
    • Нажмите «Просмотреть».
    • Нажмите «Терминал» Откройте новый терминал в редакторе Cloud Shell.

5. Назначьте проект.

  1. В терминале настройте свой проект с помощью этой команды:
    gcloud config set project [PROJECT_ID]
    Пример: gcloud config set project lab-project-id-exampleУстановите идентификатор проекта в терминале редактора Cloud Shell.
  2. Вы должны увидеть следующее сообщение: 
    Updated property [core/project].

6. Включите API.

Для использования Cloud Run , Artifact Registry , Cloud Build , Vertex AI и Compute Engine необходимо включить соответствующие API в вашем проекте Google Cloud.

  • В терминале включите API:
    gcloud services enable \
  run.googleapis.com \
  artifactregistry.googleapis.com \
  cloudbuild.googleapis.com \
  aiplatform.googleapis.com \
  compute.googleapis.com
    После завершения выполнения программы вы должны увидеть примерно следующий результат: 
    Operation "operations/acat.p2-[GUID]" finished successfully.

Представляем API.

  • Cloud Run Admin API ( run.googleapis.com ) позволяет запускать фронтенд и бэкенд сервисы, пакетные задания или веб-сайты в полностью управляемой среде. Он обеспечивает инфраструктуру для развертывания и масштабирования ваших контейнеризированных приложений.
  • API реестра артефактов ( artifactregistry.googleapis.com ) предоставляет безопасное, приватное хранилище для ваших образов контейнеров. Это эволюция Container Registry, которая легко интегрируется с Cloud Run и Cloud Build.
  • Cloud Build API ( cloudbuild.googleapis.com ) — это бессерверная платформа CI/CD, которая выполняет сборки на инфраструктуре Google Cloud. Она используется для сборки образа контейнера в облаке из вашего Dockerfile.
  • API Vertex AI ( aiplatform.googleapis.com ) позволяет вашему развернутому приложению взаимодействовать с моделями Gemini для выполнения основных задач искусственного интеллекта. Он предоставляет единый API для всех сервисов Google Cloud в области ИИ.
  • API Compute Engine ( compute.googleapis.com ) предоставляет безопасные и настраиваемые виртуальные машины, работающие на инфраструктуре Google. В то время как Cloud Run является управляемым сервисом, API Compute Engine часто требуется в качестве базовой зависимости для различных сетевых и вычислительных ресурсов.

7. Подготовьте среду разработки.

Создайте каталог

  1. В терминале создайте каталог проекта и необходимые подкаталоги: 
    cd && mkdir zoo_guide_agent && cd zoo_guide_agent
  2. В терминале выполните следующую команду, чтобы открыть каталог zoo_guide_agent в обозревателе Cloud Shell Editor: 
    cloudshell open-workspace ~/zoo_guide_agent
  3. Панель проводника слева обновится. Теперь вы должны увидеть созданную вами директорию.
    Скриншот новой директории в боковой панели проводника.
    ВАЖНО : Открытие нового рабочего пространства сбрасывает редактор Cloud Shell и перезапускает сеанс терминала. Необходимо убедиться, что терминал снова открыт, что вы находитесь в правильном каталоге ~/zoo_guide_agent (при необходимости выполните pwd и cd ~/zoo_guide_agent ) и что ваш проект gcloud по-прежнему выбран (при необходимости выполните gcloud config set project [PROJECT_ID] ).

Требования к установке

  1. Выполните следующую команду в терминале , чтобы создать файл requirements.txt . 
    cloudshell edit requirements.txt
  2. Добавьте следующее в только что созданный файл requirements.txt 
    google-adk==2.4.0
langchain-community==0.3.27
wikipedia==1.4.0
  3. В терминале создайте и активируйте виртуальное окружение с помощью команды `uv`. Это гарантирует, что зависимости вашего проекта не будут конфликтовать с системным Python. 
    uv venv
source .venv/bin/activate
  4. Установите необходимые пакеты в виртуальную среду в терминале . 
    uv pip install -r requirements.txt

Создайте учетную запись службы и настройте разрешения IAM.

Перед созданием агента необходимо создать учетную запись службы и настроить необходимые разрешения. Это гарантирует, что ваш агент сможет вызывать модели Vertex AI, а Cloud Build сможет успешно развернуть ваше приложение.

  1. В терминале создайте выделенную учетную запись службы для вашей службы Cloud Run: 
    SA_NAME=lab-service-account
PROJECT_ID=$(gcloud config get-value project)
gcloud iam service-accounts create ${SA_NAME} \
    --display-name="Service Account for Zoo Agent"
  2. Предоставьте учетной записи службы роль пользователя Vertex AI , чтобы ваш агент мог звонить в Gemini: 
    gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com" \
  --role="roles/aiplatform.user"
  3. Настройте разрешения Cloud Build. Поскольку современные проекты Google Cloud ограничивают права доступа к учетной записи службы по умолчанию, необходимо предоставить учетной записи службы Compute Engine по умолчанию роли, необходимые для сборки и развертывания контейнера. Выполните следующие команды в терминале: 
    PROJECT_NUMBER=$(gcloud projects describe $PROJECT_ID --format="value(projectNumber)")

# Grant Artifact Registry Writer role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/artifactregistry.writer"

# Grant Storage Object Viewer role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/storage.objectViewer"

# Grant Logs Writer role
gcloud projects add-iam-policy-binding $PROJECT_ID \
  --member="serviceAccount:${PROJECT_NUMBER}-compute@developer.gserviceaccount.com" \
  --role="roles/logging.logWriter"

Настройте переменные среды

Теперь вам нужно создать файл .env содержащий переменные среды, используемые агентом и скриптом развертывания.

  1. Поскольку вы уже определили переменные в терминале на предыдущем шаге, вы можете создать файл .env напрямую: 
    cat <<EOF > .env
PROJECT_ID=$PROJECT_ID
PROJECT_NUMBER=$PROJECT_NUMBER
SA_NAME=$SA_NAME
SERVICE_ACCOUNT=${SA_NAME}@${PROJECT_ID}.iam.gserviceaccount.com
MODEL="gemini-3.5-flash"
EOF

8. Создание рабочего процесса для агента

Создайте файл __init__.py

  1. Создайте файл init.py , выполнив в терминале следующую команду:
    cloudshell edit __init__.py
    Этот файл сообщает Python, что каталог zoo_guide_agent является пакетом.
  2. Добавьте следующий код в новый файл __init__.py : 
    from . import agent

Создайте файл agent.py

  1. Создайте основной файл agent.py , вставив следующую команду в терминал . 
    cloudshell edit agent.py
  2. Импорт и начальная настройка : добавьте следующий код в ваш пустой файл agent.py :
    import os
import logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

load_dotenv()

model_name = os.getenv("MODEL")
    Первый блок файла agent.py подключает все необходимые библиотеки из ADK и Google Cloud. Он также настраивает логирование и загружает переменные окружения из вашего файла .env , что крайне важно для доступа к вашей модели и URL-адресу сервера.
  3. Определите инструменты : Эффективность агента напрямую зависит от имеющихся у него инструментов. Добавьте следующий код в конец файла agent.py , чтобы определить инструменты:
    # Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=api_wrapper)
)
    Инструменты объяснены.
    • add_prompt_to_state 📝: Этот инструмент запоминает вопросы посетителей зоопарка. Когда посетитель спрашивает: «Где львы?», этот инструмент сохраняет конкретный вопрос в памяти агента, чтобы другие агенты в рабочем процессе знали, что искать.
      Как это работает: это функция на Python, которая записывает подсказку посетителя в общий словарь tool_context.state . Этот контекст инструмента представляет собой кратковременную память агента для одного разговора. Данные, сохраненные в состоянии одним агентом, могут быть прочитаны следующим агентом в рабочем процессе.
    • LangchainTool 🌍: Этот инструмент предоставляет гиду общие знания о мире. Когда посетитель задает вопрос, которого нет в базе данных зоопарка, например: «Чем питаются львы в дикой природе?», этот инструмент позволяет гиду найти ответ в Википедии. (Подробнее о настройке и использовании инструмента «Википедия» можно узнать в руководстве «Использование инструмента Википедия» ).
      Как это работает: Он выступает в качестве адаптера, позволяя нашему агенту использовать встроенный инструмент WikipediaQueryRun из библиотеки LangChain.
      Дружелюбный на вид робот держит блокнот с рисунками животных и облачком с мыслью о льве, разговаривая с мужчиной и мальчиком с рюкзаком. На заднем плане видны жирафы и другие элементы зоопарка, а вход обрамляют пальмы.
  4. Определите агентов-специалистов : добавьте следующий код в конец файла agent.py , чтобы определить агентов comprehensive_researcher и response_formatter : 
    # 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
      you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)
    • Агент comprehensive_researcher — это «мозг» нашей работы. Он берет запрос пользователя из общего State , анализирует его с помощью инструмента Википедии и решает, какие из них использовать для поиска ответа.
    • Роль агента response_formatter заключается в представлении информации. Он берет необработанные данные, собранные агентом Researcher (переданные через State), и использует языковые навыки LLM для преобразования их в дружелюбный, разговорный ответ.
      Робот со светящимися голубыми глазами сидит перед большим изогнутым монитором, на котором слева отображается MCP ZOO SERVER, а справа — страница Википедии о зоопарке. На интерфейсе сервера видны значки животных. На столе расположены несколько светящихся голубых сенсорных панелей. На заднем плане — городской пейзаж, видимый через большие окна.
  5. Определите агента рабочего процесса : добавьте этот блок кода в конец файла agent.py , чтобы определить агента последовательного tour_guide_workflow :
    tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)
    Агент рабочего процесса выступает в роли «бэк-офиса» для экскурсии по зоопарку. Он принимает запрос на поиск информации и обеспечивает выполнение двумя описанными выше агентами своих задач в правильном порядке: сначала поиск, затем форматирование. Это создает предсказуемый и надежный процесс ответа на вопрос посетителя.
    Как это работает: это SequentialAgent , особый тип агента, который не мыслит самостоятельно. Его единственная задача — запускать список sub_agents (исследователя и форматировщика) в фиксированной последовательности, автоматически передавая общую память от одного к другому.
  6. Создайте основной рабочий процесс : добавьте этот заключительный блок кода в конец файла agent.py , чтобы определить root_agent :
    root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)
    В фреймворке ADK в качестве отправной точки для всех новых диалогов используется root_agent . Его основная роль заключается в организации всего процесса. Он выступает в качестве начального контроллера, управляя первым этапом диалога.
    На картине изображены три робота: слева — робот-приветствующий, пишущий в блокноте с изображением льва в облачке мысли; в центре — робот-исследователь, сидящий за столом с компьютером, на котором отображаются данные и стрелка запроса; справа — робот-презентатор, улыбающийся и держащий диаграмму с надписью «Проанализированные данные», на которую указывает стрелка от робота-исследователя. На заднем плане видны жирафы и слоны, а сцену обрамляют пальмы.

Полный файл agent.py

Ваш файл agent.py готов! Собрав его таким образом, вы сможете увидеть, как каждый компонент — инструменты, рабочие агенты и агенты-менеджеры — играет определенную роль в создании конечной интеллектуальной системы.

Полный файл должен выглядеть следующим образом: 

import os
import logging
from dotenv import load_dotenv

from google.adk import Agent
from google.adk.agents import SequentialAgent
from google.adk.tools.tool_context import ToolContext
from google.adk.tools.langchain_tool import LangchainTool

from langchain_community.tools import WikipediaQueryRun
from langchain_community.utilities import WikipediaAPIWrapper

import google.auth
import google.auth.transport.requests
import google.oauth2.id_token

# --- Setup Logging and Environment ---

load_dotenv()

model_name = os.getenv("MODEL")

# Greet user and save their prompt

def add_prompt_to_state(
    tool_context: ToolContext, prompt: str
) -> dict[str, str]:
    """Saves the user's initial prompt to the state."""
    tool_context.state["PROMPT"] = prompt
    logging.info(f"[State updated] Added to PROMPT: {prompt}")
    return {"status": "success"}

# Configuring the Wikipedia Tool
api_wrapper = WikipediaAPIWrapper(top_k_results=1, doc_content_chars_max=1000)
api_wrapper.wiki_client.set_user_agent("ZooTourGuideAgent/1.0")
wikipedia_tool = LangchainTool(
    tool=WikipediaQueryRun(api_wrapper=api_wrapper)
)

# 1. Researcher Agent
comprehensive_researcher = Agent(
    name="comprehensive_researcher",
    model=model_name,
    description="The primary researcher that can access both internal zoo data and external knowledge from Wikipedia.",
    instruction="""
    You are a helpful research assistant. Your goal is to fully answer the user's PROMPT.
    You have access to two tools:
    1. A tool for getting specific data about animals AT OUR ZOO (names, ages, locations).
    2. A tool for searching Wikipedia for general knowledge (facts, lifespan, diet, habitat).

    First, analyze the user's PROMPT.
    - If the prompt can be answered by only one tool, use that tool.
    - If the prompt is complex and requires information from both the zoo's database AND Wikipedia,
        you MUST use both tools to gather all necessary information.
    - Synthesize the results from the tool(s) you use into preliminary data outputs.

    PROMPT:
    { PROMPT }
    """,
    tools=[
        wikipedia_tool
    ],
    output_key="research_data" # A key to store the combined findings
)

# 2. Response Formatter Agent
response_formatter = Agent(
    name="response_formatter",
    model=model_name,
    description="Synthesizes all information into a friendly, readable response.",
    instruction="""
    You are the friendly voice of the Zoo Tour Guide. Your task is to take the
    RESEARCH_DATA and present it to the user in a complete and helpful answer.

    - First, present the specific information from the zoo (like names, ages, and where to find them).
    - Then, add the interesting general facts from the research.
    - If some information is missing, just present the information you have.
    - Be conversational and engaging.

    RESEARCH_DATA:
    { research_data }
    """
)

tour_guide_workflow = SequentialAgent(
    name="tour_guide_workflow",
    description="The main workflow for handling a user's request about an animal.",
    sub_agents=[
        comprehensive_researcher, # Step 1: Gather all data
        response_formatter,       # Step 2: Format the final response
    ]
)

root_agent = Agent(
    name="greeter",
    model=model_name,
    description="The main entry point for the Zoo Tour Guide.",
    instruction="""
    - Let the user know you will help them learn about the animals we have in the zoo.
    - When the user responds, use the 'add_prompt_to_state' tool to save their response.
    After using the tool, transfer control to the 'tour_guide_workflow' agent.
    """,
    tools=[add_prompt_to_state],
    sub_agents=[tour_guide_workflow]
)

Следующий этап — развертывание!

9. Подготовьте приложение к развертыванию.

Проверьте окончательную структуру.

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

  • Убедитесь, что папка zoo_guide_agent выглядит следующим образом: 
    zoo_guide_agent/
├── .env
├── __init__.py
├── agent.py
└── requirements.txt

Настройте файл .gcloudignore и загрузите переменные среды.

  1. Создайте файл .gcloudignore в каталоге zoo_guide_agent , чтобы предотвратить загрузку вашей виртуальной среды ( .venv/ ) и других ненужных файлов в Google Cloud: 
    cloudshell edit .gcloudignore
  2. Добавьте следующее содержимое в файл .gcloudignore : 
    .gcloudignore
.git
.gitignore
.venv/
venv/
__pycache__/
.env
  3. Загрузите переменные среды в терминал: 
    source .env

10. Разверните агент с помощью интерфейса командной строки ADK.

После того, как ваш локальный код готов, а проект Google Cloud подготовлен, пришло время развернуть агент. Вы будете использовать команду adk deploy cloud_run — удобный инструмент, автоматизирующий весь процесс развертывания. Эта единственная команда упаковывает ваш код, создает образ контейнера, загружает его в реестр артефактов и запускает службу в Cloud Run , делая ее доступной в сети.

  1. Для развертывания агента выполните следующую команду в терминале :
    # Run the deployment command
uvx --from google-adk==2.4.0 \
adk deploy cloud_run \
  --project=$PROJECT_ID \
  --region=europe-west1 \
  --service_name=zoo-tour-guide \
  --with_ui \
  . \
  -- \
  --allow-unauthenticated \
  --set-env-vars=MODEL=$MODEL,GOOGLE_GENAI_USE_VERTEXAI=TRUE,GOOGLE_CLOUD_PROJECT=$PROJECT_ID,GOOGLE_CLOUD_LOCATION=global \
  --labels=dev-tutorial=codelab-adk \
  --service-account=$SERVICE_ACCOUNT
    Команда uvx позволяет запускать инструменты командной строки, опубликованные в виде пакетов Python, без необходимости глобальной установки этих инструментов.
  2. Если вам будет предложено следующее:
    Deploying from source requires an Artifact Registry Docker repository to store built containers. A repository named [cloud-run-source-deploy] in region 
[europe-west1] will be created.

Do you want to continue (Y/n)?
    Если да, то введите Y и нажмите ENTER.
  3. В случае успешного выполнения команда предоставит URL-адрес развернутой службы Cloud Run. (Он будет выглядеть примерно так: https://zoo-tour-guide-123456789.europe-west1.run.app ).
  4. Скопируйте URL-адрес развернутой службы Cloud Run для выполнения следующей задачи.

11. Протестируйте развернутого агента.

После запуска агента в Cloud Run вам потребуется провести тест, чтобы убедиться в успешности развертывания и корректной работе агента. Для доступа к веб-интерфейсу ADK и взаимодействия с агентом используйте общедоступный URL-адрес сервиса (например, https://zoo-tour-guide-123456789.europe-west1.run.app/ ).

  1. Откройте общедоступный URL-адрес Cloud Run Service в веб-браузере. Поскольку вы использовали --with_ui flag , вы должны увидеть пользовательский интерфейс разработчика ADK.
  2. Включите функцию Token Streaming в правом верхнем углу.
    Теперь вы можете взаимодействовать с агентом зоопарка.
  3. Напишите hello и нажмите Enter, чтобы начать новый разговор.
  4. Обратите внимание на результат. Агент должен быстро ответить своим приветствием, которое будет выглядеть примерно так: 
    "Hello! I'm your Zoo Tour Guide. I can help you learn about the amazing animals we have here. What would you like to know or explore today?"
  5. Задавайте агенту такие вопросы: 
    Where can I find the polar bears in the zoo and what is their diet?
    Скриншот, демонстрирующий последовательность действий агента ADK: add_prompt_to_state, transfer_to_agent, wikipedia и get_animals_by_species.Первый ответ гласит: «Я не могу сказать вам, где именно в этом зоопарке находятся белые медведи, но могу рассказать об их рационе». Второй ответ гласит: «Белые медведи находятся в Арктической экспозиции на Полярной тропе. Я не могу получить информацию об их рационе с помощью имеющихся инструментов». Третий, наиболее подробный ответ гласит: «Я с удовольствием расскажу вам о наших белых медведях! Вы можете найти наших белых медведей в Арктической экспозиции на Полярной тропе. У нас здесь три белых медведя: Снежинка, которой 7 лет; Метель, которой 5 лет; Айсберг, которой 9 лет. Что касается их рациона, белые медведи в основном плотоядные. Они специализируются на охоте на тюленей, особенно на кольчатых тюленей. Они также едят моржей, белух и некоторых наземных животных».

Объяснение потока агентов

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

1. Сотрудник зоопарка, встречающий посетителей (стойка регистрации)

Весь процесс начинается с сотрудника, встречающего гостей.

  • Его задача: начать разговор. Его инструкция — поприветствовать пользователя и спросить, о каком животном он хотел бы узнать больше.
  • Инструмент: Когда пользователь отвечает, приветствующая система использует инструмент add_prompt_to_state, чтобы зафиксировать его точные слова (например, "расскажите мне о львах") и сохранить их в памяти системы.
  • Передача управления: После сохранения запроса управление немедленно передается его субагенту, рабочему процессу гида-экскурсовода.

2. Исследователь-всесторонне развитый (Супер-исследователь)

Это первый этап основного рабочего процесса и «мозг» операции. Вместо большой команды у вас теперь есть один высококвалифицированный агент, имеющий доступ ко всей доступной информации.

  • Его задача: проанализировать вопрос пользователя и сформировать интеллектуальный план. Он использует возможности инструментария языковой модели, чтобы определить, нуждается ли он в следующем:
    • Общие сведения из интернета (через API Википедии).
    • Или, в случае сложных вопросов, и то, и другое.

3. Форматировщик ответов (докладчик)

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

  • Его задача: выступать в роли дружелюбного голоса гида зоопарка. Он берет необработанные данные (которые могут поступать из одного или обоих источников) и обрабатывает их.
  • Принцип действия: Он синтезирует всю информацию в единый, связный и увлекательный ответ. Следуя инструкциям, он сначала представляет конкретную информацию о зоопарке, а затем добавляет интересные общие факты.
  • Итоговый результат: текст, сгенерированный этим агентом, представляет собой полный, подробный ответ, который пользователь видит в окне чата.

Если вас интересует более подробная информация о создании агентов , ознакомьтесь со следующими ресурсами:

  1. Документация ADK
  2. Создание пользовательских инструментов для агентов ADK

12. Очистка окружающей среды

Чтобы избежать списания средств с вашего аккаунта Google Cloud за ресурсы, используемые в этом руководстве, либо удалите проект, содержащий эти ресурсы, либо сохраните проект и удалите отдельные ресурсы.

Удалите службы, образы и ресурсы Cloud Run.

Если вы хотите сохранить проект Google Cloud, но удалить определенные ресурсы, созданные в этой лабораторной работе, необходимо удалить работающую службу, реестр образов контейнеров, временное хранилище исходных файлов и учетную запись службы.

  • Выполните следующие команды в терминале : 
    gcloud run services delete zoo-tour-guide --region=europe-west1 --quiet
gcloud artifacts repositories delete cloud-run-source-deploy --location=europe-west1 --quiet
gsutil rm -r gs://run-sources-${PROJECT_ID}-europe-west1
gcloud iam service-accounts delete lab-service-account@${PROJECT_ID}.iam.gserviceaccount.com --quiet

Удалить проект (необязательно)

Если вы создали новый проект специально для этой лабораторной работы и не планируете использовать его снова, самый простой способ очистки — удалить весь проект. Это гарантирует полное удаление всех ресурсов (включая учетную запись службы и любые скрытые артефакты сборки).

  • В терминале выполните следующую команду (замените [YOUR_PROJECT_ID] на фактический идентификатор вашего проекта): 
    gcloud projects delete $PROJECT_ID

13. Поздравляем!

Вы успешно создали и развернули многоагентное приложение искусственного интеллекта в Google Cloud!

Краткий обзор

В этой лабораторной работе вы создали действующий, общедоступный сервис искусственного интеллекта, начав с пустого каталога. Вот что у вас получилось:

  • Вы создали специализированную команду : вместо одного универсального ИИ вы создали «Исследователя» для поиска фактов и «Форматировщика» для уточнения ответа.
  • Вы предоставили им инструменты : вы связали своих агентов с внешним миром, используя API Википедии.
  • Вы его выпустили : вы взяли свой локальный код на Python и развернули его в виде бессерверного контейнера на Cloud Run , защитив его с помощью выделенной учетной записи службы.

Что мы рассмотрели

  • Как структурировать проект на Python для развертывания с помощью ADK .
  • Как реализовать многоагентный рабочий процесс с использованием [SequentialAgent](https://google.github.io/adk-docs/agents/workflow-agents/sequential-agents/) .
  • Как интегрировать внешние инструменты, такие как API Википедии.
  • Как развернуть агент в Cloud Run с помощью команды adk deploy .

14. Опрос

Выход:

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

Прочитайте только до конца. Прочитайте текст и выполните упражнения.