Basare gli agenti RMI ADK sull'esperienza nel dominio con le competenze

Panoramica

I modelli linguistici di grandi dimensioni hanno una vasta conoscenza generale, ma non conoscono le metriche specifiche, gli schemi di database o le formule di calcolo del tuo dominio. Senza questo contesto, il modello fa delle ipotesi, il che porta a SQL errati e analisi imperfette.

L'agente RMI ADK risolve questa limitazione tramite le skill. Considera un utente che chiede "quanto era trafficata Storrow Drive ieri?". Per rispondere, l'agente deve sapere che RMI esprime la congestione come indice del tempo di percorrenza (TTI), il rapporto tra il duration_in_seconds in tempo reale e il static_duration_in_seconds a flusso libero nella tabella historical_travel_time. Un agente senza competenze potrebbe invece inventare una colonna average_speed (i report RMI indicano solo la velocità categorica, mai in km/h) o applicare la formula sbagliata, producendo una risposta sicura ma errata.

Sebbene l'agente abbia bisogno di queste conoscenze del dominio, inserire ogni definizione di metrica, schema della tabella e avvertenza SQL in un unico prompt di sistema è inefficiente.

Limitazioni dei prompt di sistema di grandi dimensioni

L'inserimento di tutte le regole e gli schemi del dominio in un unico prompt di sistema causa diversi problemi:

  • Costi più elevati e risposte più lente: l'invio di un prompt enorme a ogni turno spreca token e aumenta la latenza, anche per le domande che non hanno bisogno di queste regole.
  • Aderenza peggiore alle istruzioni: man mano che un prompt diventa più lungo con casi limite, il modello ha maggiori probabilità di ignorare o dimenticare regole specifiche.
  • Manutenzione più difficile: combinare tutto in un unico prompt rende difficile aggiornare o testare singole regole senza interrompere le altre.

Competenze

Le skill dell'agente organizzano le conoscenze del dominio in cartelle modulari che l'agente carica solo quando necessario. Ogni competenza è una directory contenente un file SKILL.md con istruzioni Markdown e un'intestazione YAML.

Invece di caricare tutto in anticipo, l'agente mantiene solo la breve description di ogni skill nel prompt di base. Quando un utente pone una domanda pertinente a un'abilità, l'agente carica le istruzioni complete per quel turno. In questo modo, i prompt rimangono piccoli e lo spazio del contesto viene riservato alla cronologia delle conversazioni effettive.

Le skill forniscono anche una chiara separazione delle competenze: puoi scrivere, testare e aggiornare singole funzionalità in isolamento senza rischiare effetti collaterali indesiderati in domini non correlati. Un agente di produzione in genere utilizza più skill mirate anziché un unico prompt gigante.

Anatomia di una skill

Un file SKILL.md è composto da due parti: un'intestazione YAML per il routing e un corpo Markdown per le istruzioni.

1. Intestazione YAML

---
name: rmi-traffic-metrics-grounding
description: >
  Standard traffic performance metrics computable from RMI BigQuery
  tables. Covers congestion severity (TTI), delay, travel time
  reliability (LOTTR, BTI, PTI, CoV), congestion frequency, speed
  breakdowns, and network-wide congestion rates. Use when the user asks
  about traffic conditions, congestion, reliability, delay, or network
  health.
---

Il modello utilizza description per decidere se caricare la skill. Poiché il modello vede questa descrizione solo prima di decidere di caricare la skill, assicurati che elenchi chiaramente gli argomenti trattati, le frasi tipiche degli utenti e quando attivarla.

2. Corpo in Markdown

Il corpo fornisce le indicazioni specifiche del dominio che il modello segue una volta caricato. Il corpo della skill delle metriche RMI include la formula TTI esatta (duration_in_seconds / static_duration_in_seconds), un modello SQL BigQuery verificato per ogni metrica e frasi di attivazione che mappano l'user intent sulla metrica corretta. Fornire istruzioni strutturate e verificate mantiene il modello ancorato e impedisce di indovinare i dettagli dello schema o della formula.

Registrare le skill con ADK

Raggruppa le competenze in un SkillToolset e aggiungile all'elenco degli strumenti dell'agente:

from google.adk import skills
from google.adk.tools import skill_toolset

rmi_skill_toolset = skill_toolset.SkillToolset(
    skills=[
        # TRAFFIC_METRICS_SKILL_DIR points to the skill's SKILL.md folder.
        skills.load_skill_from_dir(TRAFFIC_METRICS_SKILL_DIR),
    ],
)

# root_agent = llm_agent.Agent(..., tools=[*bq_tools, rmi_skill_toolset])

Qui, TRAFFIC_METRICS_SKILL_DIR punta alla directory contenente la skill di base per le metriche sul traffico.

Raggruppare gli strumenti con le competenze

Poiché le skill sono istruzioni basate su testo, affidarsi esclusivamente al modello per interpretare ed eseguire una logica complessa può portare a incoerenze. L'allegato di strumenti eseguibili a una skill fornisce determinismo: il codice gestisce calcoli, convalide e interazioni API rigorosi, mentre la skill indica al modello quando e come utilizzarli.

Il raggruppamento degli strumenti evita anche l'aumento del contesto globale. Anziché esporre in anticipo ogni strumento specializzato, gli strumenti vengono caricati solo quando la corrispondente competenza di dominio è attiva.

Puoi allegare strumenti specifici direttamente a una skill nell'intestazione YAML:

metadata:
  adk_additional_tools:
    - calculate_custom_metric

In questo modo, il modello riceve lo schema dello strumento e le istruzioni per l'uso insieme appena in tempo, mantenendo snello il set di strumenti di base.

Esempio: grounding di una query relativa alla congestione

  1. L'utente chiede "Quanto è trafficata Storrow Drive durante l'ora di punta serale?"
  2. Il prompt di sistema di base pubblicizza solo il nome e la descrizione di ogni skill, quindi l'agente vede che rmi-traffic-metrics-grounding copre "congestione" e chiama load_skill per recuperare le istruzioni complete per questa query.
  3. Con la competenza caricata, l'agente applica la definizione di TTI e il modello SQL verificato che fornisce, calcolando il rapporto rispetto a historical_travel_time invece di indovinare una formula.

Poiché il corpo di una skill viene recuperato solo quando una query lo richiede, le skill che l'agente non utilizza mai non entrano nel contesto, mantenendo piccolo il prompt di sistema di base.

Concetti chiave

  • Fondati su indicazioni del dominio: fornisci istruzioni, vincoli e logica di business espliciti anziché fare affidamento su ipotesi generali del modello.
  • Utilizza competenze modulari: dividi le conoscenze in competenze mirate anziché in un unico prompt di sistema gigante per risparmiare token, ridurre la latenza e migliorare l'accuratezza.
  • Scrivi descrizioni chiare: includi frasi e parole chiave specifiche nella descrizione di ogni skill in modo che l'agente la carichi in modo affidabile.
  • Includi esempi concreti: aggiungi esempi verificati e flussi di lavoro di riferimento ai corpi delle skill per mantenere gli output coerenti e accurati.
  • Raggruppa gli strumenti per il determinismo: collega gli strumenti eseguibili alle skill per gestire la convalida e l'esecuzione rigorose mantenendo snello il set di strumenti di base.

Passaggi successivi

Collaboratori

Nathaniel Thomas | Software Engineering Intern, Google Maps Platform