Pular para o conteúdo
LabS Atlas
AI For Devs
Entrar

Registro de Agentes por Dicionário

Ir para notas que citam esta
atualizado há 25 diasEntre para perguntar ao Labinho sobre esta notaO Labinho é o assistente que responde com as notas e as sessões do LabS e mostra de onde tirou cada resposta.

Registro de agentes por dicionário é um padrão em que cada agente vira um dicionário Python com campos fixos, e o grafo de nós e arestas é montado a partir dessa lista.

O padrão nasce de um limite prático do LangGraph: da forma que a documentação e a maioria dos tutoriais ensinam, cada nó e cada aresta são criados à mão, o que só funciona para poucos agentes. O registro troca esse desenho manual por uma descrição declarativa: quem adiciona um agente preenche uma entrada padronizada, e a montagem do grafo e o roteamento leem essa lista.

Por que criar nós e arestas à mão não escala

Até um exemplo mínimo de LangGraph, com um único nó chamando um LLM, já exige um volume de código grande para o pouco que faz. Um agente simples de interpretação de histórias de usuário, com analisador, interpretador, revisor, um nó que grava a saída em JSON e o nó final, já soma sete conexões entre nós, entre arestas sólidas e condicionais, e cada uma é uma linha de criação explícita.

Num sistema com mais de trinta agentes, como o QAssist, o código manual de nós e arestas condicionais chegou a quase mil linhas cobrindo só metade dos agentes. O arquivo fica gigante e difícil de ler, e a imagem do grafo que o próprio projeto gera ao rodar fica tão grande que nem com zoom dá para enxergá-la sem pixelizar.

Campos de uma entrada no registro

Cada agente é uma entrada de dicionário com as mesmas chaves:

  • Nome do nó, que identifica o agente no grafo.
  • Tipo de artefato que o agente trata: história de usuário, plano de teste, cenário de teste, código ou repositório. Um tipo bem especificado ajuda o roteador a achar o agente certo.
  • Categoria: interpretação ou geração. É a principal distinção funcional do registro, e o resto da configuração segue o mesmo formato nas duas categorias.
  • Função de execução, que faz o trabalho pesado: monta o prompt, chama o modelo e usa ferramentas quando precisa. Uma docstring descreve a especialização do agente.
  • Campos de interface, com as informações que a tela em Streamlit usa para mostrar o agente.

Funções auxiliares filtram o registro por categoria. Cada função de agente carrega um prompt de sistema especializado, com boas práticas, exemplo de um bom artefato e instruções de formato, o que liga o padrão à Especialização de Prompts para Agentes.

Como o roteador usa o registro

O registro em si é código Python comum, sem nenhuma inteligência: ele não escolhe agente nenhum. Quem decide é um nó analisador, no papel de Agente Roteador. A partir do registro ele monta a lista de agentes válidos para a mensagem, inclui essa lista no prompt de classificação junto com exemplos de mapeamento (um link de repositório, por exemplo, deve sempre ir para o agente que clona e analisa código) e devolve a escolha numa saída estruturada em JSON. Se a resposta foge desse formato, o fluxo não avança.

No grafo, isso vira uma única aresta condicional do analisador para todos os agentes cadastrados. Por cima dela vale a regra dos Times de Agentes de Interpretação e Geração: nenhum agente de geração é acionado antes de um agente de interpretação ter lido o artefato de entrada.

Ganhos e custo do padrão

Onde fica a complexidade

O padrão tira a complexidade do desenho do grafo e a leva para o nó analisador. Como cada time tem o mesmo comportamento de entrada e saída (recebe de um agente, devolve ou finaliza), o grafo fica genérico e o controle fica concentrado num ponto só.

Adicionar um agente para uma nova linguagem ou um novo tipo de teste se resume a acrescentar uma entrada, sem redesenhar conexões. Isso também resolve a colaboração: várias pessoas criam agentes em paralelo sem mexer no mesmo emaranhado de arestas, e quem trabalha com Python pela primeira vez consegue criar o primeiro agente olhando uma entrada pronta e depois produzir vários outros. O registro continua grande, porque cresce com o número de agentes, mas é simples de ler e de estender.