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 amplo conhecimento geral, 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 com habilidades. Considere um usuário que pergunta "Como estava o trânsito na 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 (os relatórios do RMI mostram apenas a velocidade categórica, nunca km/h) ou aplicar a fórmula errada, produzindo uma resposta confiante, mas incorreta.

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

Limitações de comandos grandes do sistema

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 a cada vez desperdiça tokens e aumenta a latência, mesmo para perguntas que não precisam dessas regras.
  • Pior capacidade de seguir instruções: à medida que um comando fica mais longo com casos extremos, o modelo tem mais chances de ignorar ou esquecer regras específicas.
  • Manutenção mais difícil: combinar tudo em um único comando dificulta a atualização ou o teste de regras individuais sem afetar 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 em Markdown e um cabeçalho YAML.

Em vez de carregar tudo de antemão, o agente mantém apenas a breve description de cada habilidade no comando básico. Quando um usuário faz uma pergunta relevante para uma skill, o agente carrega as instruções completas para essa vez. 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 responsabilidades: é 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 geralmente 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 o description para decidir se vai carregar a habilidade. Como o modelo só vê essa descrição antes de decidir carregar a skill, verifique se ela lista claramente os tópicos abordados, as frases típicas do usuário e quando acionar a skill.

2. Corpo em Markdown

O corpo fornece a orientação específica do domínio que o modelo segue depois de carregado. O corpo de habilidades de métricas de RMI inclui a fórmula exata de TTI (duration_in_seconds / static_duration_in_seconds), um modelo SQL do BigQuery verificado para cada métrica e frases de ativação que mapeiam a intenção do usuário para a métrica certa. Instruções estruturadas e verificadas mantêm o modelo fundamentado e evitam que ele adivinhe detalhes de esquemas ou fórmulas.

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 embasamento 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 lógicas complexas pode levar a inconsistências. Anexar ferramentas executáveis a uma skill oferece determinismo: o código processa cálculos estritos, validações e interações de API, enquanto a skill instrui o modelo sobre quando e como usá-los.

As ferramentas de agrupamento também evitam o aumento do contexto global. Em vez de expor todas as ferramentas especializadas de uma vez, elas são carregadas apenas quando a habilidade de domínio correspondente está 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: embasamento de uma consulta sobre congestionamento

  1. O usuário pergunta "Como está o trânsito na Storrow Drive durante o horário de pico da noite?"
  2. O comando do sistema básico 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 dessa 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 básico do sistema pequeno.

Pontos principais

  • Fundamentar com orientação do domínio: forneça instruções, restrições e lógica de negócios explícitas em vez de depender de proposições gerais do modelo.
  • Use habilidades modulares: divida o conhecimento em habilidades focadas em vez de um comando gigantesco do sistema para economizar tokens, reduzir a latência e melhorar a precisão.
  • Escreva descrições claras: inclua frases de ativação e palavras-chave 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.
  • Agrupar ferramentas para determinismo: anexe ferramentas executáveis a habilidades para processar validação e execução estritas, mantendo o conjunto de ferramentas básico enxuto.

Próximas etapas

Colaboradores

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