Cómo fundamentar los agentes del ADK de RMI en la experiencia del dominio con habilidades

Descripción general

Los modelos de lenguaje grandes tienen un amplio conocimiento general, pero no conocen las métricas específicas, los esquemas de bases de datos ni las fórmulas de cálculo de tu dominio. Sin este contexto, el modelo adivina, lo que genera un SQL incorrecto y un análisis defectuoso.

El agente del ADK de RMI aborda esta limitación a través de habilidades. Considera un usuario que pregunta "¿qué tan congestionada estuvo Storrow Drive ayer?". Para responder, el agente debe saber que el RMI expresa la congestión como el Índice de tiempo de viaje (TTI), la proporción de duration_in_seconds en tiempo real con respecto a static_duration_in_seconds de flujo libre en la tabla historical_travel_time. En cambio, un agente sin habilidades podría inventar una columna de average_speed (los informes de RMI solo registran la velocidad categórica, nunca en km/h) o aplicar la fórmula incorrecta, lo que produciría una respuesta segura, pero incorrecta.

Si bien el agente necesita este conocimiento del dominio, incluir cada definición de métrica, esquema de tabla y advertencia de SQL en una sola instrucción del sistema es ineficiente.

Limitaciones de las instrucciones del sistema grandes

Colocar todas las reglas y esquemas de dominio en una sola instrucción del sistema causa varios problemas:

  • Costos más altos y respuestas más lentas: Enviar una instrucción enorme en cada turno desperdicia tokens y aumenta la latencia, incluso para las preguntas que no necesitan esas reglas.
  • Peor seguimiento de instrucciones: A medida que una instrucción se vuelve más larga con casos extremos, es más probable que el modelo ignore u olvide reglas específicas.
  • Mantenimiento más difícil: Combinar todo en una sola instrucción dificulta la actualización o la prueba de reglas individuales sin afectar a otras.

Habilidades

Las habilidades del agente organizan el conocimiento del dominio en carpetas modulares que el agente carga solo cuando es necesario. Cada habilidad es un directorio que contiene un archivo SKILL.md con instrucciones en Markdown y un encabezado YAML.

En lugar de cargar todo por adelantado, el agente solo mantiene el description corto de cada habilidad en su instrucción base. Cuando un usuario hace una pregunta relevante para una habilidad, el agente carga las instrucciones completas para ese turno. Esto mantiene las instrucciones pequeñas y ahorra espacio de contexto para el historial de conversación real.

Las habilidades también proporcionan una separación clara de las preocupaciones: puedes escribir, probar y actualizar capacidades individuales de forma aislada sin correr el riesgo de efectos secundarios no deseados en dominios no relacionados. Por lo general, un agente de producción usa varias habilidades enfocadas en lugar de una instrucción gigante.

Anatomía de una habilidad

Un archivo SKILL.md tiene dos partes: un encabezado YAML para el enrutamiento y un cuerpo de Markdown para las instrucciones.

1. Encabezado 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.
---

El modelo usa description para decidir si carga la habilidad. Dado que el modelo solo ve esta descripción antes de decidir cargar la habilidad, asegúrate de que se indiquen claramente los temas que abarca, las frases típicas del usuario y cuándo activarla.

2. Cuerpo de Markdown

El cuerpo proporciona la orientación específica del dominio que sigue el modelo una vez que se carga. El cuerpo de la habilidad de métricas de RMI incluye la fórmula exacta del TTI (duration_in_seconds / static_duration_in_seconds), una plantilla de SQL de BigQuery verificada para cada métrica y frases de activación que asignan la intención del usuario a la métrica correcta. Proporcionar instrucciones estructuradas y verificadas mantiene el modelo fundamentado y evita que adivine detalles del esquema o la fórmula.

Registra habilidades con el ADK

Agrupa las habilidades en un SkillToolset y agrégalas a la lista de herramientas del 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])

Aquí, TRAFFIC_METRICS_SKILL_DIR apunta al directorio que contiene la habilidad de fundamentación de métricas de tráfico.

Agrupa herramientas con habilidades

Dado que las habilidades son instrucciones basadas en texto, depender únicamente del modelo para interpretar y ejecutar una lógica compleja puede generar incoherencias. Adjuntar herramientas ejecutables a una habilidad proporciona determinismo: el código controla cálculos, validaciones e interacciones con la API estrictos, mientras que la habilidad le indica al modelo cuándo y cómo usarlos.

Las herramientas de agrupamiento también evitan la sobrecarga del contexto global. En lugar de exponer todas las herramientas especializadas por adelantado, las herramientas se limitan para que se carguen solo cuando su habilidad de dominio correspondiente esté activa.

Puedes adjuntar herramientas específicas directamente a una habilidad en su encabezado YAML:

metadata:
  adk_additional_tools:
    - calculate_custom_metric

Esto garantiza que el modelo reciba el esquema de la herramienta y sus instrucciones de uso justo a tiempo, lo que mantiene el conjunto de herramientas base reducido.

Ejemplo: Fundamentación de una búsqueda de congestión

  1. El usuario pregunta "¿Qué tan congestionada está Storrow Drive durante la hora pico de la tarde?"
  2. La instrucción del sistema base solo anuncia el nombre y la descripción de cada habilidad, por lo que el agente ve que rmi-traffic-metrics-grounding abarca la "congestión" y llama a load_skill para extraer sus instrucciones completas para esta búsqueda.
  3. Con la habilidad cargada, el agente aplica la definición de TTI y la plantilla de SQL verificada que proporciona, y calcula la proporción en función de historical_travel_time en lugar de adivinar una fórmula.

Dado que el cuerpo de una habilidad solo se recupera cuando una búsqueda lo necesita, las habilidades que el agente nunca usa no ingresan en el contexto, lo que mantiene pequeña la instrucción base del sistema.

Conclusiones clave

  • Fundamenta con orientación del dominio: Proporciona instrucciones, restricciones y lógica empresarial explícitas en lugar de depender de suposiciones generales del modelo.
  • Usa habilidades modulares: Divide el conocimiento en habilidades enfocadas en lugar de una instrucción del sistema gigante para ahorrar tokens, reducir la latencia y mejorar la precisión.
  • Escribe descripciones claras: Incluye palabras clave y frases de activación específicas en la descripción de cada habilidad para que el agente la cargue de forma confiable.
  • Incluye ejemplos concretos: Agrega ejemplos verificados y flujos de trabajo de referencia a los cuerpos de las habilidades para mantener los resultados coherentes y precisos.
  • Incluye herramientas para el determinismo: Adjunta herramientas ejecutables a las habilidades para controlar la validación y la ejecución estrictas, y mantener el conjunto de herramientas básico reducido.

Próximos pasos

Colaboradores

Nathaniel Thomas | Pasante de ingeniería de software, Google Maps Platform