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 las habilidades. Considera un usuario que pregunta "¿Qué tan congestionada estuvo Storrow Drive ayer?". Para responder, el agente debe saber que 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. Un agente sin habilidades podría inventar una columna average_speed (RMI solo informa la velocidad categórica, nunca 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, colocar 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 grandes del sistema

Colocar todas las reglas y esquemas del 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 las instrucciones: A medida que una instrucción se alarga con casos extremos, es más probable que el modelo ignore o 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 interrumpir 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 de Markdown y un encabezado YAML.

En lugar de cargar todo por adelantado, el agente solo mantiene la description corta 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 inquietudes: 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 la description para decidir si se carga la habilidad. Como el modelo solo ve esta descripción antes de decidir cargar la habilidad, asegúrate de que se enumeren claramente los temas que se abarcan, 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 cargado. 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 los 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

Como 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 los cálculos estrictos, las validaciones y las interacciones con la API, mientras que la habilidad le indica al modelo cuándo y cómo usarlos.

Agrupar herramientas también evita la expansión del contexto global. En lugar de exponer todas las herramientas especializadas por adelantado, las herramientas se limitan para que se carguen solo cuando está activa su habilidad de dominio correspondiente.

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 consulta de congestión

  1. El usuario pregunta "¿Qué tan congestionada está Storrow Drive durante la hora pico de la tarde?"
  2. La instrucción base del sistema 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 consulta.
  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 con respecto a historical_travel_time en lugar de adivinar una fórmula.

Como el cuerpo de una habilidad solo se recupera cuando una consulta lo necesita, las habilidades que el agente nunca usa nunca ingresan al contexto, lo que mantiene pequeña la instrucción base del sistema.

Conclusiones principales

  • 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 gigante del sistema para guardar tokens, reducir la latencia y mejorar la precisión.
  • Escribe descripciones claras: Incluye frases de activación y palabras clave específicas en la descripción de cada habilidad para que el agente la cargue de manera 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.
  • Agrupa herramientas para el determinismo: Adjunta herramientas ejecutables a las habilidades para controlar la validación y la ejecución estrictas, mientras mantienes el conjunto de herramientas base reducido.

Próximos pasos

Colaboradores

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