Next '26 Developer Keynote: como criar agentes do ADK com habilidades e ferramentas

1. Introdução

Neste codelab, você vai criar um agente sofisticado de planejamento de maratona usando o Kit de Desenvolvimento de Agente (ADK, na sigla em inglês). Você vai examinar progressivamente os recursos do agente, desde um comando de sistema bem estruturado até o carregamento dinâmico de habilidades e o mapeamento de ferramentas do MCP. Por fim, você vai testar o agente localmente e implantá-lo no ambiente de execução do agente (Agent Engine).

Atividades deste laboratório

  • Inicializar um novo projeto de agente do ADK
  • Criar um comando de sistema robusto usando um builder estruturado
  • Adicionar ferramentas do MCP do Google Maps para contexto de localização no mundo real
  • Carregar habilidades dinamicamente no conjunto de ferramentas do agente
  • Testar a execução do agente localmente
  • Implantar o agente no Agent Engine (Cloud Run)

O que é necessário

  • Um navegador da web, como o Chrome
  • Tenha um projeto na nuvem do Google Cloud com o faturamento ativado.
  • Noções básicas sobre o Python.

Este codelab é para desenvolvedores intermediários que querem criar agentes de IA generativa especializados.

Duração estimada: 45 minutos

Os recursos criados neste codelab custam menos de US $2.

2. Antes de começar

Criar um projeto do Google Cloud

  1. No console do Google Cloud, na página de seletor de projetos, selecione ou crie um projeto do Google Cloud.
  2. Verifique se o faturamento está ativado para seu projeto na nuvem. Saiba como verificar se o faturamento está ativado em um projeto.

Iniciar o Cloud Shell

O Cloud Shell é um ambiente de linha de comando em execução no Google Cloud que vem pré-carregado com as ferramentas necessárias.

  1. Clique em Ativar o Cloud Shell na parte de cima do console do Google Cloud.
  2. Depois de se conectar ao Cloud Shell, verifique sua autenticação:
    gcloud auth list
  3. Confirme se o projeto está configurado:
    gcloud config get project
  4. Se o projeto não estiver definido como esperado, defina-o:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Verificar a autenticação:

gcloud auth list

Confirme seu projeto:

gcloud config get project

Defina-o, se necessário:

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

Ativar APIs

Execute este comando para ativar todas as APIs necessárias:

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

Criar uma chave da API Google Maps

Para usar as ferramentas do MCP do Google Maps, é necessário gerar uma chave da API Maps.

  1. No console do Google Cloud, use a barra de pesquisa para acessar Plataforma Google Maps > Credenciais.
  2. Se solicitado, confirme seu projeto na nuvem do Google.
  3. Clique em Criar credenciais e selecione Chave de API.
  4. Copie a chave de API gerada. Você precisará dela na próxima etapa.

3. Configurar o ambiente

Para este codelab, o código está hospedado no GitHub. Você vai clonar o repositório, que contém a estrutura de diretórios e os subcomponentes necessários (como o diretório skills/).

  1. Clone o repositório e navegue até a pasta do projeto:
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/demo-1
  1. Configure um ambiente virtual do Python e instale o ADK:
uv venv
source .venv/bin/activate
uv sync
  1. Defina a chave da API Maps. O aplicativo a lê de uma variável de ambiente:
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"

Definir as variáveis de ambiente

O agente do simulador usa um arquivo .env para configuração. Copie o arquivo de amostra e atualize-o com o ID do projeto.

  1. Copie o arquivo de ambiente de amostra:
cp planner_agent/sample.env planner_agent/.env
  1. Abra planner_agent/.env e atualize o campo GOOGLE_CLOUD_PROJECT com o ID do projeto do Google Cloud e o campo GOOGLE_MAPS_API_KEY com a chave da API Google Maps que você criou.

O arquivo deve ser semelhante a este:

GOOGLE_GENAI_USE_VERTEXAI=1
GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=global
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. Criar um novo agente do ADK

Conheça o arquivo principal que define o agente: planner_agent/agent.py.

No repositório build-agents-with-skills, o agente é inicializado usando a classe Agent do ADK. Ele especifica o modelo subjacente, um nome de identidade e extrai as instruções e ferramentas definidas em outros módulos.

Abra planner_agent/agent.py para examinar o código de inicialização:

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
)

A classe Agent abstrai o histórico de mensagens, a orquestração de ferramentas e a comunicação LLM, permitindo que você se concentre no comportamento do agente.

No momento, o agente é muito genérico. É possível interagir com ele como qualquer outro LLM.

uv run adk run planner_agent

Esse comando inicia um chat com o agente. Ele usa gemini-3-flash-preview como modelo e pode responder a perguntas básicas.

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**.

O agente já conhece alguns fatos sobre maratonas. No entanto, isso não é suficiente para planejar uma maratona adequada com regras e planejamento de rotas.

5. Criar um comando de sistema

Os comandos de sistema (instruções) ditam o comportamento do agente. Em vez de uma única string gigante, esse projeto usa um PromptBuilder (planner_agent/utils.py) para criar instruções dinamicamente.

Abra planner_agent/prompts.py para ver como o comando é estruturado em seções lógicas:

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()

De volta a planner_agent/agent.py, isso já foi importado.

Encontre a seção com TODO: Replace Instruction and Description e remova a marca de comentário da reatribuição da variável instruction e description.

Essa seção do código deve ser assim:

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

Você está importando uma versão do comando para o agente que não faz referência a nenhuma ferramenta. Você vai adicionar ferramentas em uma etapa posterior.

É possível testar essa versão do agente:

uv run adk run planner_agent

Na janela de chat, envie o seguinte comando:

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

Após alguns instantes, você vai receber uma resposta semelhante a esta:

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).
...
...

Com um comando bem definido, a saída já está muito mais próxima do resultado esperado. Na próxima etapa, você vai adicionar ferramentas para levar o agente ao próximo nível.

6. Adicionar habilidades e ferramentas

Para ativar habilidades e ferramentas em planner_agent/agent.py, encontre a seção com TODO: Replaces Tools e remova a marca das duas linhas a seguir. O código vai ficar assim:

instruction=PLANNER_INSTRUCTION
tools=get_tools()

Essa é a única mudança de código necessária nesta etapa. O restante desta seção explica os conceitos por trás de habilidades e ferramentas.

Habilidades

Uma habilidade de agente é uma unidade de funcionalidade independente que um agente do ADK pode usar para realizar uma tarefa específica. Uma habilidade de agente encapsula as instruções, os recursos e as ferramentas necessários para uma tarefa, com base na especificação de habilidade do agente. A estrutura de uma habilidade permite que ela seja carregada incrementalmente para minimizar o impacto na janela de contexto operacional do agente.

Para o agente de planejamento de maratona, há três habilidades definidas:

  1. gis-spatial-engineering : responsável por processar dados GeoJSON para criar a rota da maratona.
  2. mapping : use as ferramentas do Google Maps para pesquisar lugares e informações meteorológicas.
  3. race-director : valida se a rota da maratona segue as diretrizes de planejamento.

As habilidades podem ter scripts, outros recursos e referências.

O aplicativo carrega todas as habilidades e as fornece como ferramentas em planner_agent/tools.py. Observe como isso é feito na função 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

A parte mais interessante é o método load_skill_from_dir do ADK. Há outra maneira de criar habilidades no ADK, que é inline. Embora não seja usado neste codelab, ele é parecido com este:

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.",
        },
    ),
)

Adicionar ferramentas de mapeamento

O planejador de maratona precisa de contexto espacial para gerar rotas. Você fornece isso integrando o servidor MCP (Protocolo de Contexto de Modelo) do Google Maps.

Em planner_agent/tools.py, observe como o servidor MCP é registrado com a ferramenta 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)]

Ao adicionar o conjunto de ferramentas do MCP, o agente ganha automaticamente a capacidade de consultar o Google Maps para detalhes de rota, elevação e localização.

7. Executar o agente localmente

Agora que o agente, o comando e as ferramentas estão conectados, execute o agente localmente. Desta vez, você vai usar adk web para poder ver os eventos de carregamento de habilidades e de chamada de ferramentas.

uv run adk web

Você verá algo semelhante a:

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. Abra o navegador e acesse o URL mostrado no terminal (geralmente http://localhost:8000).
  2. No menu suspenso no canto superior esquerdo, selecione planner_agent.
  3. Na janela de chat, envie o seguinte comando:
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

Você vai ver habilidades sendo carregadas e ferramentas sendo chamadas. Após alguns instantes, o agente vai gerar um plano de maratona.

A interface vai ficar assim:

Interface da Web do ADK

8. Implantar o agente

Quando estiver satisfeito com o desempenho do agente localmente, implante-o no Agent Engine, que hospeda o agente no Cloud Run com segurança.

Para implantar o agente, use o comando de implantação da CLI do ADK:

uv run adk deploy agent_engine \
  --env_file planner_agent/.env --region=us-central1 \
  planner_agent

Quando a implantação terminar, a CLI vai gerar um endpoint hospedado com segurança para seu agente. Agora é possível integrar esse endpoint a aplicativos front-end, chatbots ou outros sistemas de back-end. Você também pode usar o ambiente de testes do ambiente de execução do agente para testar o agente.

A saída será assim:

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

Você pode usar o script Python fornecido para se comunicar com o agente.

  1. Copie o arquivo de ambiente de amostra:
cp sample.env .env
  1. Abra .env e atualize o campo GOOGLE_CLOUD_PROJECT com o ID do projeto do Google Cloud.

O arquivo deve se assemelhar ao seguinte exemplo:

GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-central1
  1. É possível listar agentes no seu projeto.
python main.py list

Você verá algo semelhante a:

Listing deployed agents...

ID: <AGENT_ID> | Display Name: planner_agent

Depois de ter o ID do agente implantado, você pode enviar um comando:

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"

Você vai receber uma saída semelhante a esta:

Streaming response from agent <AGENT_ID>:

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

9. Limpar

Para evitar cobranças contínuas na sua conta do Google Cloud, exclua os recursos criados durante este codelab.

Exclua o serviço do Cloud Run criado pela implantação:

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

Se você armazenou a chave da API Maps no Secret Manager, exclua o secret:

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

Se você criou um novo projeto do Google Cloud para este codelab, poderá excluir todo o projeto para remover todos os recursos e APIs associados a ele:

gcloud projects delete $PROJECT_ID

10. Parabéns

Parabéns! Você criou um agente sofisticado de planejamento de maratona usando o ADK.

O que você aprendeu

  • Inicializar um projeto do Kit de Desenvolvimento de Agente (ADK)
  • Usar PromptBuilder para comandos de sistema modulares
  • Integrar recursos de mapeamento usando ferramentas do MCP e ApiRegistry
  • Carregar habilidades condicionalmente usando SkillToolset
  • Testar localmente e implantar no Agent Engine

Documentos de referência