Fundamentar agentes do ADK de RMI em experiência no domínio com habilidades

Visão geral

Os modelos de linguagem grandes têm um conhecimento geral amplo, mas não conhecem as métricas específicas, os esquemas de banco de dados ou as fórmulas de cálculo do seu domínio. Sem esse contexto, o modelo faz suposições, o que leva a SQL incorreto e análises falhas.

O agente do ADK do RMI resolve essa limitação usando habilidades. Considere um usuário que pergunta "quão congestionada estava a Storrow Drive ontem?". Para responder, o agente precisa saber que o RMI expressa o congestionamento como o Índice de tempo de viagem (TTI), a proporção de duration_in_seconds em tempo real para static_duration_in_seconds de fluxo livre na tabela historical_travel_time. Um agente sem habilidades pode inventar uma coluna average_speed (o RMI informa apenas a velocidade categórica, nunca km/h) ou aplicar a fórmula errada, produzindo uma resposta confiante, mas errada.

Embora o agente precise desse conhecimento de domínio, colocar todas as definições de métricas, esquemas de tabelas e ressalvas de SQL em um único comando do sistema é ineficiente.

Limitações de comandos de sistema grandes

Colocar todas as regras e esquemas de domínio em um único comando do sistema causa vários problemas:

  • Custos mais altos e respostas mais lentas: enviar um comando enorme em cada turno desperdiça tokens e aumenta a latência, mesmo para perguntas que não precisam dessas regras.
  • Pior acompanhamento de instruções: à medida que um comando fica mais longo com casos extremos, o modelo se torna mais propenso a ignorar ou esquecer regras específicas.
  • Manutenção mais difícil: combinar tudo em um comando dificulta a atualização ou o teste de regras individuais sem quebrar outras.

Habilidades

As habilidades do agente organizam o conhecimento do domínio em pastas modulares que o agente carrega apenas quando necessário. Cada habilidade é um diretório que contém um arquivo SKILL.md com instruções Markdown e um cabeçalho YAML.

Em vez de carregar tudo antecipadamente, o agente mantém apenas a description curta de cada habilidade no comando base. Quando um usuário faz uma pergunta relevante para uma habilidade, o agente carrega as instruções completas para esse turno. Isso mantém os comandos pequenos e economiza espaço de contexto para o histórico de conversas real.

As habilidades também oferecem uma separação clara de preocupações: é possível escrever, testar e atualizar recursos individuais de forma isolada, sem correr o risco de efeitos colaterais não intencionais em domínios não relacionados. Um agente de produção normalmente usa várias habilidades focadas em vez de um comando gigante.

Anatomia de uma habilidade

Um arquivo SKILL.md tem duas partes: um cabeçalho YAML para roteamento e um corpo Markdown para instruções.

1. Cabeçalho 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.
---

O modelo usa a description para decidir se vai carregar a habilidade. Como o modelo só vê essa descrição antes de decidir carregar a habilidade, verifique se ela lista claramente os tópicos abordados, a fraseologia típica do usuário e quando acioná-la.

2. Corpo Markdown

O corpo fornece a orientação específica do domínio que o modelo segue quando carregado. O corpo da habilidade de métricas do RMI inclui a fórmula exata do TTI (duration_in_seconds / static_duration_in_seconds), um modelo SQL do BigQuery verificado para cada métrica e frases de acionamento que mapeiam a intenção do usuário para a métrica correta. Fornecer instruções estruturadas e verificadas mantém o modelo fundamentado e impede que ele adivinhe detalhes do esquema ou da fórmula.

Registrar habilidades com o ADK

Agrupe as habilidades em um SkillToolset e adicione-as à lista de ferramentas do 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])

Aqui, TRAFFIC_METRICS_SKILL_DIR aponta para o diretório que contém a habilidade de fundamentação de métricas de tráfego.

Agrupar ferramentas com habilidades

Como as habilidades são instruções baseadas em texto, confiar apenas no modelo para interpretar e executar uma lógica complexa pode levar a inconsistências. Anexar ferramentas executáveis a uma habilidade fornece determinismo: o código processa cálculos, validações e interações de API rigorosos, enquanto a habilidade instrui o modelo sobre quando e como usá-los.

O agrupamento de ferramentas também evita o inchaço do contexto global. Em vez de expor todas as ferramentas especializadas antecipadamente, as ferramentas são definidas para serem carregadas apenas quando a habilidade de domínio correspondente estiver ativa.

É possível anexar ferramentas específicas diretamente a uma habilidade no cabeçalho YAML dela:

metadata:
  adk_additional_tools:
    - calculate_custom_metric

Isso garante que o modelo receba o esquema da ferramenta e as instruções de uso juntos, mantendo o conjunto de ferramentas básico enxuto.

Exemplo: fundamentar uma consulta de congestionamento

  1. O usuário pergunta "Quão congestionada está a Storrow Drive durante o horário de pico da noite?"
  2. O comando do sistema base anuncia apenas o nome e a descrição de cada habilidade. Assim, o agente vê que rmi-traffic-metrics-grounding abrange "congestionamento" e chama load_skill para extrair as instruções completas para essa consulta.
  3. Com a habilidade carregada, o agente aplica a definição de TTI e o modelo SQL verificado que ele fornece, calculando a proporção em relação a historical_travel_time em vez de adivinhar uma fórmula.

Como o corpo de uma habilidade só é buscado quando uma consulta precisa dele, as habilidades que o agente nunca usa não entram no contexto, mantendo o comando do sistema base pequeno.

Pontos principais

  • Fundamentar com orientação de domínio: forneça instruções explícitas, restrições, e lógica de negócios em vez de confiar em suposições gerais do modelo.
  • Use habilidades modulares: divida o conhecimento em habilidades focadas em vez de um comando de sistema gigante para economizar tokens, reduzir a latência e melhorar a acurácia.
  • Escreva descrições claras: inclua frases e palavras-chave de acionamento específicas na descrição de cada habilidade para que o agente a carregue de forma confiável.
  • Inclua exemplos concretos: adicione exemplos verificados e fluxos de trabalho de referência aos corpos de habilidades para manter as saídas consistentes e precisas.
  • Agrupe ferramentas para determinismo: anexe ferramentas executáveis a habilidades para lidar com validação e execução rigorosas, mantendo o conjunto de ferramentas básico enxuto.

Próximas etapas

Colaboradores

Nathaniel Thomas | Estagiário de engenharia de software, Plataforma Google Maps