[Pitch] Criei a AAL (Agent Architecture Language): uma especificação em YAML para desenhar sistemas de IA · arpavan

Estou na área de tecnologia há muitos anos e passei por diferentes fases e ferramentas. Desde 2012, venho trabalhando com dados, Machine Learning e Deep Learning. Quando os Transformers ganharam força, passei a trabalhar cada vez mais com soluções de IA e nos últimos anos, com arquiteturas desse tipo em aplicações de produção que atendem milhões de usuários.

Sempre gostei de desenhar as soluções antes de iniciar o desenvolvimento para ter uma visão geral e tentar pensar em todos os cenários, para isso usei ferramentas como Lucidchart, Draw.io, Excalidraw, entre várias outras. O problema é que diagramas visuais podem acabar separados do código e ficar desatualizados conforme a arquitetura muda.

Com LLMs capazes de gerar e revisar código, comecei a pensar: por que não descrever a arquitetura em um formato que também possa ser versionado, validado e transformado em um diagrama?

Mermaid já resolve muito bem a criação de diagramas a partir de texto e continuo gostando da ferramenta, mas no meu caso senti falta de representar componentes específicos de sistemas com agentes, como modelos, tools, memória e guardrails, além de validar as referências entre eles. Foi daí que surgiu a AAL (Agent Architecture Language), uma especificação declarativa em YAML para descrever arquiteturas de agentes.

Criei também o Graphen Studio, uma ferramenta open source para editar e visualizar essas definições no navegador. A ideia nasceu de uma necessidade minha e ainda está evoluindo.

Como funciona a AAL?

A ideia foi criar uma especificação declarativa e simples em YAML (que todo dev já conhece), onde você descreve cada componente e cria as conexões entre eles para formar o diagrama da sua arquitetura.

Exemplo de um agente com duas tools básicas em .aal.yaml:

version: "1.1"
metadata:
  name: Assistant

models:
  - id: claude_sonnet
    provider: anthropic
    model: claude-sonnet-4-5

agents:
  - id: assistant
    name: Assistant
    role: General purpose assistant
    model: claude_sonnet
    tools: [calculator, web_search]

tools:
  - id: calculator
    name: Calculator
    mechanism: function
  - id: web_search
    name: Web Search
    mechanism: webhook
    endpoint: "https://api.example.com/search"

topology:
  - from: assistant
    to: calculator
    label: Math operations
  - from: assistant
    to: web_search
    label: Information lookup

As referências em tools registram as dependências do agente. Já topology define as conexões direcionadas que aparecem no canvas. Separar essas duas coisas permite declarar o que o agente usa e, independentemente, o que quero destacar visualmente na arquitetura.

O que o Graphen faz (e o que não faz)

O Graphen Studio lê esse YAML em tempo real no navegador, faz a validação do schema e constrói o grafo interativo da arquitetura. A AAL também tem campos para grupos, MCPs, memórias, guardrails e componentes de condição ou ação.

Um ponto importante: AAL e Graphen Studio não executam os agentes, chamam tools nem avaliam condições. A proposta é descrever, validar e visualizar a arquitetura, não substituir o framework ou runtime que implementa o sistema.

Imagem do Graphen

Teste ou explore o projeto

Graphen Studio: https://graphen-studio.github.io/graphen/studio/
Landing Page: https://graphen-studio.github.io/graphen/
Documentação da AAL: https://graphen-studio.github.io/graphen/docs/
Repositório GitHub: https://github.com/graphen-studio/graphen

E para quem quiser testar a geração automática via LLM, criei uma SKILL que facilita esse trabalho:
AAL Architecture Skill no GitHub

Espero que seja útil para alguém! Fiquem à vontade para mandar dúvidas, sugestões ou críticas.

Vocês costumam usar Mermaid no dia a dia ou acham que uma DSL em YAML faz sentido para esse cenário?