Registro de Agentes por Dicionário
Ir para notas que citam estaRegistro 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
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.