Следующий доклад для разработчиков на конференции ‘26: Создание агентов ADK с помощью навыков и инструментов.

1. Введение

В этом практическом занятии вы создадите сложный агент Marathon Planner, используя комплект разработки агентов (ADK). Вы постепенно изучите возможности агента, начиная от хорошо структурированной системной подсказки и заканчивая динамической загрузкой навыков и сопоставлением инструментов MCP. Наконец, вы протестируете агента локально и развернете его в среде выполнения агентов (Agent Engine).

Что вы будете делать

  • Инициализировать новый проект агента ADK .
  • Создайте надежную системную подсказку с помощью конструктора структурированных сообщений.
  • Добавьте инструменты Google Maps MCP для отображения реального местоположения.
  • Динамическая загрузка навыков в набор инструментов агента.
  • Проверьте выполнение агента локально.
  • Разверните агент в Agent Engine (Cloud Run).

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

  • Веб-браузер, например Chrome.
  • Проект Google Cloud с включенной функцией выставления счетов.
  • Базовые знания Python.

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

Ориентировочная продолжительность: 45 минут

Стоимость ресурсов, созданных в рамках этого практического занятия, должна составлять менее 2 долларов.

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

Создайте проект в Google Cloud.

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

Запустить Cloud Shell

Cloud Shell — это среда командной строки, работающая в Google Cloud и поставляемая с предустановленными необходимыми инструментами.

  1. В верхней части консоли Google Cloud нажмите кнопку «Активировать Cloud Shell» .
  2. После подключения к Cloud Shell подтвердите свою аутентификацию: 
    gcloud auth list
  3. Убедитесь, что ваш проект настроен: 
    gcloud config get project
  4. Если параметры вашего проекта заданы не так, как ожидалось, настройте их следующим образом: 
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Проверка подлинности:

gcloud auth list

Подтвердите свой проект:

gcloud config get project

При необходимости установите значение:

export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Включить API

Выполните эту команду, чтобы включить все необходимые API:

gcloud services enable \
  aiplatform.googleapis.com \
  run.googleapis.com \
  secretmanager.googleapis.com \
  mapstools.googleapis.com \
  storage.googleapis.com \
  cloudresourcemanager.googleapis.com \
  serviceusage.googleapis.com

Создайте ключ API Google Maps.

Для использования инструментов Google Maps MCP необходимо сгенерировать ключ API карт.

  1. В консоли Google Cloud воспользуйтесь строкой поиска, чтобы перейти к Google Maps Platform > Credentials .
  2. При появлении запроса подтвердите свой проект в Google Cloud.
  3. Нажмите «Создать учетные данные» и выберите «Ключ API» .
  4. Скопируйте сгенерированный API-ключ. Он понадобится вам на следующем шаге.

3. Настройте свою среду.

Для этого практического занятия код размещен на GitHub. Вам нужно будет клонировать репозиторий, который содержит структуру каталогов и необходимые подкомпоненты (например, каталог skills/ ).

  1. Клонируйте репозиторий и перейдите в папку проекта: 
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/demo-1
  1. Настройте виртуальное окружение Python и установите ADK: 
uv venv
source .venv/bin/activate
uv sync
  1. Укажите свой ключ API для работы с картами. Приложение считывает его из переменной окружения: 
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"

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

Агент симулятора использует файл .env для настройки. Скопируйте пример файла и обновите его, указав идентификатор вашего проекта.

  1. Скопируйте пример файла среды: 
cp planner_agent/sample.env planner_agent/.env
  1. Откройте planner_agent/.env и обновите поле GOOGLE_CLOUD_PROJECT , указав в нем фактический идентификатор вашего проекта Google Cloud, а также обновите поле GOOGLE_MAPS_API_KEY , указав созданный вами ключ API Google Maps.

Файл должен выглядеть примерно так: 

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
GOOGLE_MAPS_API_KEY=<YOUR_MAPS_API_KEY>
GOOGLE_CLOUD_AGENT_ENGINE_ENABLE_TELEMETRY=true
OTEL_PYTHON_LOGGING_AUTO_INSTRUMENTATION_ENABLED=true
OTEL_INSTRUMENTATION_GENAI_CAPTURE_MESSAGE_CONTENT=true
ADK_CAPTURE_MESSAGE_CONTENT_IN_SPANS=true

4. Создайте нового агента ADK.

Изучите основной файл, определяющий агента: planner_agent/agent.py .

В репозитории build-agents-with-skills инициализация агента осуществляется с помощью класса Agent из ADK. Он задает базовую модель, имя идентификатора и подтягивает инструкции и инструменты, определенные в других модулях.

Откройте planner_agent/agent.py , чтобы изучить код инициализации: 

instruction="Answer user questions to the best of your knowledge"
description="A helpful assistant for user questions."
tools=[]

# ...

root_agent = Agent(
    model='gemini-3-flash-preview',
    name='planner_agent',
    description=description,
    instruction=instruction,
    tools=tools
)

Класс Agent абстрагирует историю сообщений, управление инструментами и коммуникацию LLM, позволяя вам сосредоточиться на поведении агента.

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

uv run adk run planner_agent

Эта команда запустит чат с агентом. Она использует gemini-3-flash-preview в качестве модели и может отвечать на основные вопросы. 

Running agent planner_agent, type exit to exit.
[user]: What is the length of a Marathon
[planner_agent]: The official length of a marathon is **26.2 miles**, which is
equivalent to **42.195 kilometers**.

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

5. Создайте системную подсказку.

Системные подсказки (инструкции) определяют поведение агента. Вместо одной большой строки в этом проекте используется PromptBuilder ( planner_agent/utils.py ) для динамического составления инструкций.

Откройте planner_agent/prompts.py чтобы увидеть, как подсказка структурирована на логические разделы: 

from collections import OrderedDict
from .utils import PromptBuilder

ROLE = """\
...
"""

RULES = """\
...
"""

WORKFLOW = """\
...
"""

###

# Planner instructions with no tools mentioned
PLANNER_INSTRUCTION_NO_TOOLS = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        tools=TOOLS_PROMPT_ONLY,
        workflow=WORKFLOW_PROMPT_ONLY,
    )
).build()

# Planner instruction with skills and tools defined
PLANNER_INSTRUCTION = PromptBuilder(
    OrderedDict(
        role=ROLE,
        rules=RULES,
        skills=SKILLS,
        tools=TOOLS,
        workflow=WORKFLOW,
    )
).build()

В файле planner_agent/agent.py это уже импортировано.

Найдите раздел с TODO: Replace Instruction and Description и раскомментируйте переназначение переменных instruction и description .

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

instruction=PLANNER_INSTRUCTION_NO_TOOLS
description="Expert GIS analyst for marathon route and event planning."

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

Вы можете протестировать эту версию агента: 

uv run adk run planner_agent

В окне чата отправьте следующее сообщение: 

Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

Через несколько мгновений вы должны получить ответ, похожий на этот: 

Running agent planner_agent, type exit to exit.
[user]: Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the evening timeframe
[planner_agent]: Here is the comprehensive marathon plan for Las Vegas.

As requested, I have designed this event for an evening start on April 24, 2027. Because certain parameters (theme and budget) were not specified, I have applied pragmatic defaults: this will be a "Neon Nights" scenic theme to capitalize on the evening Strip, operating on a moderate-to-high budget given the infrastructure needed to secure major Las Vegas corridors.

### 1. Intent Alignment
*   **City & Theme:** Las Vegas, Nevada. Theme: "Neon Nights" an evening race maximizing the visual impact of the illuminated city.
*   **Date & Time:** Saturday, April 24, 2027. Late April evenings in Las Vegas offer optimal running weather (temperatures dropping from ~70°F at sunset to ~60°F). Race start is 6:30 PM (sunset is approx. 7:20 PM).
...
...

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

6. Добавьте навыки и инструменты.

Чтобы включить навыки и инструменты в planner_agent/agent.py , найдите раздел с TODO: Replaces Tools и раскомментируйте следующие две строки. Ваш код должен выглядеть следующим образом: 

instruction=PLANNER_INSTRUCTION
tools=get_tools()

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

Навыки

Навык агента — это самодостаточный функционал, который агент ADK может использовать для выполнения конкретной задачи. Навык агента инкапсулирует необходимые инструкции, ресурсы и инструменты, требуемые для выполнения задачи, в соответствии со спецификацией навыка агента. Структура навыка позволяет загружать его постепенно, чтобы минимизировать влияние на контекстное окно работы агента.

Для специалиста по планированию марафона определены 3 навыка:

  1. ГИС-пространственная инженерия — отвечает за обработку данных GeoJSON для создания маршрута марафона.
  2. Картография — используйте инструменты Google Maps для поиска мест и информации о погоде.
  3. Директор забега - Подтвердите соответствие маршрута марафона планировочным рекомендациям.

Навыки могут включать в себя скрипты, дополнительные ресурсы и ссылки.

Приложение загружает все навыки и предоставляет их в качестве инструментов в planner_agent/tools.py . Обратите внимание, как это делается в функции get_tools() : 

def get_tools() -> list:
    """Build the planner's tool list with lazy-loaded skills."""
    from google.adk.code_executors.unsafe_local_code_executor import UnsafeLocalCodeExecutor

    skills_dir = pathlib.Path(__file__).parent / "skills"

    skills = []
    if skills_dir.exists():
        skills = [
            load_skill_from_dir(d)
            for d in sorted(skills_dir.iterdir())
            if d.is_dir() and not d.name.startswith("_") and (d / "SKILL.md").exists()
        ]

    additional_tools = _load_additional_tools(skills_dir)

    skill_toolset = SkillToolset(
        skills=skills,
        code_executor=UnsafeLocalCodeExecutor(),
        additional_tools=additional_tools,
    )

    tools = [
        skill_toolset,
        PreloadMemoryTool(),
    ]

    tools.extend(get_maps_tools())

    return tools

Наиболее интересная часть — это метод load_skill_from_dir из ADK. В ADK есть ещё один способ создания навыков — встроенный. Хотя в этом практическом занятии он не используется, выглядит он примерно так: 

from google.adk.skills import models

greeting_skill = models.Skill(
    frontmatter=models.Frontmatter(
        name="greeting-skill",
        description=(
            "A friendly greeting skill that can say hello to a specific person."
        ),
    ),
    instructions=(
        "Step 1: Read the 'references/hello_world.txt' file to understand how"
        " to greet the user. Step 2: Return a greeting based on the reference."
    ),
    resources=models.Resources(
        references={
            "hello_world.txt": "Hello! So glad to have you here!",
            "example.md": "This is an example reference.",
        },
    ),
)

Добавить инструменты картографирования

Для построения маршрутов марафонского забега необходим пространственный контекст. Вы можете обеспечить его, интегрировав сервер Google Maps MCP (Model Context Protocol).

В planner_agent/tools.py обратите внимание на то, как сервер MCP регистрируется в инструменте ApiRegistry : 

from google.adk.integrations.api_registry import ApiRegistry

class MapsApiRegistry(ApiRegistry):
    """ApiRegistry subclass that strips ADC headers to force API key auth."""

    def get_toolset(self, *args, **kwargs):  # noqa: ANN002, ANN003
        toolset = super().get_toolset(*args, **kwargs)
        conn = getattr(toolset, "_connection_params", None)
        headers = getattr(conn, "headers", None) if conn else None
        if headers:
            headers.pop("Authorization", None)  # type: ignore[union-attr]
            headers.pop("x-goog-user-project", None)  # type: ignore[union-attr]
        return toolset

def get_maps_tools() -> list:
    """Return Maps MCP toolset if configured."""
    project_id = os.getenv("GOOGLE_CLOUD_PROJECT", "").strip()
    maps_key = _resolve_maps_key()

    if not project_id or not maps_key:
        return []

    # Map the MCP server location on Google Cloud
    mcp_server_name = f"projects/{project_id}/locations/global/mcpServers/google-mapstools.googleapis.com-mcp"
    
    # Initialize the custom API registry that supports header injection
    api_registry = MapsApiRegistry(
        api_registry_project_id=project_id,
        header_provider=header_provider,
    )
    return [api_registry.get_toolset(mcp_server_name=mcp_server_name)]

Добавив набор инструментов MCP, агент автоматически получает возможность запрашивать у Google Maps информацию о маршруте, высоте и местоположении!

7. Запустите агент локально.

Теперь, когда агент, подсказка и инструменты связаны между собой, запустите агент локально. На этот раз вы будете использовать adk web , чтобы видеть события загрузки навыков и вызова инструментов. 

uv run adk web

Вы должны увидеть что-то подобное. 

INFO:     Started server process [99665]
INFO:     Waiting for application startup.

+-----------------------------------------------------------------------------+
| ADK Web Server started                                                      |
|                                                                             |
| For local testing, access at http://127.0.0.1:8000.                         |
+-----------------------------------------------------------------------------+

INFO:     Application startup complete.
INFO:     Uvicorn running on http://127.0.0.1:8000 (Press CTRL+C to quit)
  1. Откройте браузер и перейдите по URL-адресу, отображаемому в терминале (обычно http://localhost:8000 ).
  2. В выпадающем списке в левом верхнем углу выберите planner_agent .
  3. В окне чата отправьте следующее сообщение: 
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

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

Ваш пользовательский интерфейс должен выглядеть примерно так:

Веб-интерфейс ADK

8. Разверните агента.

Как только вы убедитесь, что агент работает локально, вы можете развернуть его в Agent Engine, который безопасно размещает агент в Cloud Run.

Для развертывания агента используйте команду развертывания ADK CLI: 

uv run adk deploy agent_engine \
  --env_file planner_agent/.env \
  planner_agent

После завершения развертывания CLI выводит на экран защищенную конечную точку для вашего агента. Теперь вы можете интегрировать эту конечную точку в приложения для внешнего интерфейса, чат-боты или другие бэкэнд-системы. Вы также можете использовать среду выполнения агента (Agent Runtime Playground) для тестирования агента.

Результат выглядит следующим образом: 

Files and dependencies resolved
Deploying to agent engine...
✅ Created agent engine: projects/<PROJECT_ID>/locations/us-west1/reasoningEngines/<AGENT_ID>

Для связи с агентом вы можете использовать предоставленный скрипт на языке Python.

  1. Скопируйте пример файла среды: 
cp sample.env .env
  1. Откройте файл .env и обновите поле GOOGLE_CLOUD_PROJECT , указав в нем фактический идентификатор вашего проекта Google Cloud.

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

GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
  1. Вы можете указать агентов в своем проекте. 
python main.py list

Вы должны увидеть что-то подобное. 

Listing deployed agents...

ID: <AGENT_ID> | Display Name: planner_agent

Получив идентификатор развернутого агента, вы можете отправить запрос: 

export AGENT_ID=<AGENT_ID>

python main.py prompt --agent-id ${AGENT_ID} --message "Plan a marathon for
10000 participants in Las Vegas on April 24, 2027 in the evening timeframe"

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

Streaming response from agent <AGENT_ID>:

{'model_version': 'gemini-3-flash-preview', 'content': {'parts': [{'text': 'Here is a comprehensive
...
...
...

9. Уборка

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

Удалите службу Cloud Run, созданную в ходе развертывания: 

python main.py delete --agent-id ${AGENT_ID}

Если вы сохранили ключ API карт в Secret Manager, удалите секрет: 

gcloud secrets delete maps-api-key --project=$PROJECT_ID

Если вы создали новый проект Google Cloud для этого практического занятия, вы можете удалить весь проект, чтобы удалить все связанные с ним ресурсы и API: 

gcloud projects delete $PROJECT_ID

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

Поздравляем! Вы создали сложный агент планирования марафона с помощью ADK.

Что вы узнали

  • Инициализация проекта комплекта разработки агентов (ADK).
  • Использование PromptBuilder для модульных системных подсказок.
  • Интеграция возможностей сопоставления данных с использованием инструментов MCP и ApiRegistry
  • Условная загрузка навыков с помощью SkillToolset
  • Тестирование локально и развертывание в Agent Engine.

Справочная документация