Next '26 Developer Keynote: Building ADK Agents with Skills and Tools

1. Introduzione

In questo codelab creerai un sofisticato agente di pianificazione della maratona utilizzando Agent Development Kit (ADK). Esaminerai progressivamente le funzionalità dell'agente, da un prompt di sistema ben strutturato al caricamento dinamico delle competenze e al mapping degli strumenti MCP. Infine, testerai l'agente localmente ed eseguirai il deployment in Agent Runtime (Agent Engine).

In questo lab proverai a:

  • Inizializzare un nuovo progetto agente ADK
  • Comporre un prompt di sistema robusto utilizzando uno strumento di creazione strutturato
  • Aggiungere strumenti MCP di Google Maps per il contesto di localizzazione nel mondo reale
  • Caricare dinamicamente le competenze nel set di strumenti dell'agente
  • Testare l'esecuzione dell'agente in locale
  • Eseguire il deployment dell'agente in Agent Engine (Cloud Run)

Che cosa ti serve

  • Un browser web come Chrome
  • Un progetto cloud Google Cloud con la fatturazione abilitata
  • Conoscenza di base di Python

Questo codelab è destinato agli sviluppatori di livello intermedio che vogliono creare agenti di AI generativa specializzati.

Durata stimata: 45 minuti

Le risorse create in questo codelab dovrebbero costare meno di 2 $.

2. Prima di iniziare

Crea un progetto Google Cloud

  1. Nella console Google Cloud, nella pagina di selezione del progetto, seleziona o crea un progetto Google Cloud.
  2. Verifica che la fatturazione sia attivata per il tuo progetto Cloud. Scopri come verificare se la fatturazione è abilitata per un progetto.

Avvia Cloud Shell

Cloud Shell è un ambiente a riga di comando in esecuzione in Google Cloud che viene fornito con gli strumenti necessari precaricati.

  1. Fai clic su Attiva Cloud Shell nella parte superiore della console Google Cloud.
  2. Una volta eseguita la connessione a Cloud Shell, verifica l'autenticazione:
    gcloud auth list
  3. Verifica che il progetto sia configurato:
    gcloud config get project
  4. Se il progetto non è impostato come previsto, impostalo:
    export PROJECT_ID=<YOUR_PROJECT_ID>
gcloud config set project $PROJECT_ID

Verifica l'autenticazione:

gcloud auth list

Conferma il progetto:

gcloud config get project

Impostalo, se necessario:

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

Abilita API

Esegui questo comando per abilitare tutte le API richieste:

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

Crea una chiave API di Google Maps

Per utilizzare gli strumenti MCP di Google Maps, devi generare una chiave API di Google Maps.

  1. Nella console Google Cloud, utilizza la barra di ricerca per andare a Google Maps Platform > Credenziali.
  2. Se richiesto, conferma il tuo progetto Google Cloud.
  3. Fai clic su Crea credenziali e seleziona Chiave API.
  4. Copia la chiave API generata. Ti servirà nel passaggio successivo.

3. Configura l'ambiente

Per questo codelab, il codice è ospitato su GitHub. Clonerai il repository, che contiene la struttura delle directory e i sottocomponenti richiesti (ad esempio la directory skills/).

  1. Clona il repository e vai alla cartella del progetto:
git clone https://github.com/GoogleCloudPlatform/next-26-keynotes
cd next-26-keynotes/devkey/demo-1
  1. Configura un ambiente virtuale Python e installa ADK:
uv venv
source .venv/bin/activate
uv sync
  1. Imposta la chiave API di Google Maps. L'applicazione la legge da una variabile di ambiente:
export GOOGLE_MAPS_API_KEY="<YOUR_MAPS_API_KEY>"

Configura le variabili di ambiente

L'agente del simulatore utilizza un file .env per la configurazione. Copia il file di esempio e aggiornalo con l'ID progetto.

  1. Copia il file di ambiente di esempio:
cp planner_agent/sample.env planner_agent/.env
  1. Apri planner_agent/.env e aggiorna il campo GOOGLE_CLOUD_PROJECT con l'ID progetto Google Cloud effettivo e il campo GOOGLE_MAPS_API_KEY con la chiave API di Google Maps che hai creato.

Il file dovrebbe avere un aspetto simile al seguente:

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. Crea un nuovo agente ADK

Esplora il file principale che definisce l'agente: planner_agent/agent.py.

Nel repository build-agents-with-skills, l'agente viene inizializzato utilizzando la classe Agent di ADK. Specifica il modello sottostante, un nome di identità e recupera le istruzioni e gli strumenti definiti in altri moduli.

Apri planner_agent/agent.py per esaminare il codice di inizializzazione:

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
)

La classe Agent astrae la cronologia dei messaggi, l'orchestrazione degli strumenti e la comunicazione LLM, consentendoti di concentrarti sul comportamento dell'agente.

Al momento, l'agente è molto generico. Puoi interagire con lui come con qualsiasi altro LLM.

uv run adk run planner_agent

Questo comando avvierà una chat con l'agente. Utilizza gemini-3-flash-preview come modello e può rispondere a domande di base.

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

L'agente conosce già alcuni fatti sulle maratone. Tuttavia, non è sufficiente per pianificare una maratona corretta con regole e pianificazione del percorso.

5. Crea un prompt di sistema

I prompt di sistema (istruzioni) determinano il comportamento dell'agente. Anziché una singola stringa di grandi dimensioni, questo progetto utilizza un PromptBuilder (planner_agent/utils.py) per comporre le istruzioni in modo dinamico.

Apri planner_agent/prompts.py per vedere come il prompt è strutturato in sezioni logiche:

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

In planner_agent/agent.py, questo è già importato.

Trova la sezione con TODO: Replace Instruction and Description e rimuovi il commento dalla riassegnazione delle variabili instruction e description.

Questa sezione di codice dovrebbe avere il seguente aspetto:

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

Stai importando una versione del prompt per l'agente che non fa riferimento a nessuno strumento. Aggiungerai gli strumenti in un passaggio successivo.

Puoi testare questa versione dell'agente:

uv run adk run planner_agent

Nella finestra della chat, invia il seguente prompt:

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

Dopo alcuni istanti, dovresti ricevere una risposta simile a questa:

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

Con un prompt ben definito, l'output è già molto più vicino al risultato previsto. Nel passaggio successivo, aggiungerai gli strumenti per portare l'agente al livello successivo.

6. Aggiungi competenze e strumenti

Per abilitare le competenze e gli strumenti in planner_agent/agent.py, trova la sezione con TODO: Replaces Tools e rimuovi il commento dalle due righe successive. Il codice dovrebbe avere il seguente aspetto:

instruction=PLANNER_INSTRUCTION
tools=get_tools()

Questa è l'unica modifica al codice richiesta in questo passaggio. Il resto di questa sezione spiega i concetti alla base di competenze e strumenti.

Competenze

Una competenza dell'agente è un'unità di funzionalità autonoma che un agente ADK può utilizzare per eseguire un'attività specifica. Una competenza dell'agente incapsula le istruzioni, le risorse e gli strumenti necessari per un'attività, in base alla specifica della competenza dell'agente. La struttura di una Skill consente di caricarla in modo incrementale per ridurre al minimo l'impatto sulla finestra contestuale dell'agente.

Per l'agente di pianificazione della maratona sono definite tre competenze:

  1. gis-spatial-engineering : responsabile dell'elaborazione dei dati GeoJSON per creare il percorso della maratona.
  2. mapping : utilizza gli strumenti di Google Maps per cercare luoghi e informazioni meteo.
  3. race-director : convalida che il percorso della maratona rispetti le linee guida di pianificazione.

Le competenze possono avere script, risorse aggiuntive e riferimenti.

L'applicazione carica tutte le competenze e le fornisce come strumenti in planner_agent/tools.py. Nota come viene eseguita questa operazione nella funzione 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

La parte più interessante è il metodo load_skill_from_dir di ADK. Esiste un altro modo per creare competenze in ADK, ovvero in linea. Sebbene non venga utilizzato in questo codelab, ha un aspetto simile al seguente:

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

Aggiungi strumenti di mapping

Il pianificatore della maratona ha bisogno di un contesto spaziale per generare i percorsi. Puoi fornirlo integrando il server MCP (Model Context Protocol) di Google Maps.

In planner_agent/tools.py, nota come il server MCP viene registrato con lo strumento 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)]

Aggiungendo il set di strumenti MCP, l'agente acquisisce automaticamente la capacità di eseguire query su Google Maps per i dettagli di routing, elevazione e localizzazione.

7. Esegui l'agente in locale

Ora che l'agente, il prompt e gli strumenti sono collegati, esegui l'agente in locale. Questa volta utilizzerai adk web per poter visualizzare gli eventi di caricamento delle competenze e di chiamata degli strumenti.

uv run adk web

Dovresti vedere qualcosa di simile

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. Apri il browser e vai all'URL mostrato nel terminale (di solito http://localhost:8000).
  2. Nel menu a discesa in alto a sinistra, seleziona planner_agent.
  3. Nella finestra della chat, invia il seguente prompt:
Plan a marathon for 10000 participants in Las Vegas on April 24, 2027 in the
evening timeframe

Dovresti vedere le competenze caricate e gli strumenti chiamati. Dopo alcuni istanti, l'agente genererà un piano di maratona.

L'interfaccia utente dovrebbe avere un aspetto simile al seguente:

UI web dell&#39;ADK

8. Esegui il deployment dell'agente

Quando sei soddisfatto del rendimento dell'agente in locale, puoi eseguirne il deployment in Agent Engine, che ospita l'agente in modo sicuro su Cloud Run.

Per eseguire il deployment dell'agente, utilizza il comando di deployment dell'interfaccia a riga di comando ADK:

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

Al termine del deployment, l'interfaccia a riga di comando restituisce un endpoint ospitato in modo sicuro per l'agente. Ora puoi integrare questo endpoint in applicazioni frontend, chatbot o altri sistemi di backend. Puoi anche utilizzare Agent Runtime Playground per testare l'agente.

L'output è simile al seguente:

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

Puoi utilizzare lo script Python fornito per comunicare con l'agente.

  1. Copia il file di ambiente di esempio:
cp sample.env .env
  1. Apri .env e aggiorna il campo GOOGLE_CLOUD_PROJECT con l'ID progetto Google Cloud effettivo.

Il file dovrebbe avere il seguente aspetto:

GOOGLE_CLOUD_PROJECT=<YOUR_PROJECT_ID>
GOOGLE_CLOUD_LOCATION=us-west1
  1. Puoi elencare gli agenti nel tuo progetto.
python main.py list

Dovresti vedere qualcosa di simile

Listing deployed agents...

ID: <AGENT_ID> | Display Name: planner_agent

Una volta ottenuto l'ID agente di cui è stato eseguito il deployment, puoi inviare un prompt:

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"

Verrà restituito un output simile al seguente:

Streaming response from agent <AGENT_ID>:

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

9. Libera spazio

Per evitare addebiti continui sul tuo account Google Cloud, elimina le risorse create durante questo codelab.

Elimina il servizio Cloud Run creato dal deployment:

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

Se hai archiviato la chiave API di Google Maps in Secret Manager, elimina il secret:

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

Se hai creato un nuovo progetto Google Cloud per questo codelab, puoi eliminare l'intero progetto per rimuovere tutte le risorse e le API associate:

gcloud projects delete $PROJECT_ID

10. Complimenti

Complimenti! Hai creato un sofisticato agente di pianificazione della maratona utilizzando ADK.

Che cosa hai imparato

  • Inizializzare un progetto Agent Development Kit (ADK)
  • Utilizzare PromptBuilder per i prompt di sistema modulari
  • Integrare le funzionalità di mapping utilizzando gli strumenti MCP e ApiRegistry
  • Caricare le competenze in modo condizionale utilizzando SkillToolset
  • Testare in locale ed eseguire il deployment in Agent Engine

Documenti di riferimento