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

1. Introdução

Neste codelab, você vai criar um agente de planejamento de maratona sofisticado usando o Kit de Desenvolvimento de Agente (ADK). 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 Agent Runtime (Agent Engine).

Atividades deste laboratório

  • Inicializar um novo projeto de agente do ADK
  • Elaborar um comando do sistema robusto usando um builder estruturado
  • Adicione 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
  • Implante o agente no Agent Engine (Cloud Run).

O que é necessário

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

Este codelab é para desenvolvedores de nível intermediário que querem criar agentes especializados de IA generativa.

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 do seletor de projetos, selecione ou crie um projeto na nuvem do Google Cloud.
  2. Verifique se o faturamento está ativado para seu projeto do Cloud. Saiba como verificar se o faturamento está ativado em um projeto.

Iniciar o Cloud Shell

O Cloud Shell é um ambiente de linha de comando executado 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, faça o seguinte:
    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, 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 de API Google Maps

Para usar as ferramentas do MCP do Google Maps, é necessário gerar uma chave de 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á dele na próxima etapa.

3. Configurar o ambiente

Neste 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 acesse 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 sua chave de API Maps. O aplicativo lê de uma variável de ambiente:
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"

Configurar variáveis de ambiente

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

  1. Copie o arquivo de ambiente de exemplo:
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 de API do 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=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. Criar um agente do ADK

Analise 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 do LLM, permitindo que você se concentre no comportamento do agente.

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

uv run adk run planner_agent

Esse comando inicia um chat com o agente. Ele usa o 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á sabe alguns fatos sobre maratonas. No entanto, isso não é suficiente para planejar uma maratona adequada com regras e planejamento de percurso.

5. Criar um comando do sistema

Os comandos do sistema (instruções) determinam o comportamento do agente. Em vez de uma única string gigante, esse projeto usa um PromptBuilder (planner_agent/utils.py) para compor instruções de forma dinâmica.

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

No 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 das variáveis instruction e description.

Essa seção do código vai ficar 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.

Você pode testar esta versão do agente:

uv run adk run planner_agent

Na janela de conversa, envie o seguinte comando:

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

Depois de 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á fica muito mais próxima do resultado esperado. Na próxima etapa, você vai adicionar ferramentas para levar o agente a um novo 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 seguintes. 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 das habilidades e ferramentas.

Habilidades

Uma habilidade de agente é uma unidade independente de funcionalidade que um agente do ADK pode usar para realizar uma tarefa específica. Uma habilidade do agente encapsula as instruções, os recursos e as ferramentas necessárias para uma tarefa, com base na especificação da habilidade do agente. A estrutura de uma habilidade permite que ela seja carregada de forma incremental 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 o percurso da maratona.
  2. Mapeamento: use as ferramentas do Google Maps para pesquisar lugares e informações meteorológicas.
  3. race-director: valida se o percurso da maratona segue as diretrizes de planejamento.

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

O aplicativo carrega todas as habilidades e as oferece como ferramentas no planner_agent/tools.py. Veja 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 é in-line. Embora não seja usado neste codelab, ele tem esta aparência:

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. Para isso, integre 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 MCP, o agente ganha automaticamente a capacidade de consultar o Google Maps para obter detalhes de rotas, 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 ver os eventos de carregamento de habilidade e de chamada de ferramenta.

uv run adk web

Você vai ver algo parecido com isto:

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 conversa, envie o seguinte comando:
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

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

Sua 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 \
  planner_agent

Quando a implantação terminar, a CLI vai gerar um endpoint hospedado com segurança para seu agente. Agora você pode integrar esse endpoint a aplicativos de front-end, chatbots ou outros sistemas de back-end. Você também pode usar o ambiente de simulação do tempo 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 exemplo:
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-west1
  1. É possível listar os agentes no seu projeto.
python main.py list

Você vai ver algo parecido com isto:

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 de API Maps no Secret Manager, exclua o secret:

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

Se você criou um projeto do Google Cloud para este codelab, é possível 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 do Planejador de maratonas usando o ADK.

O que você aprendeu

  • Inicializar um projeto do Kit de Desenvolvimento de Agente (ADK)
  • Como usar PromptBuilder para comandos modulares do sistema
  • Integração de 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