Intensivo Grátis 21–22/11Intensivo gratuito de 2 dias em Vibecoding (21–22/11 às 16:00 MSK) · Turma 3 começa 23/11Inscrever-se grátis →Turma 3 (23/11)
LançamentoAnálise · No radarHabr AI→ original

Desenvolvedor trancou um agente de código numa gaiola de YAML: 18 ferramentas e 12 skills

Um agente de código escreve bem, mas em automações de negócio ele costuma quebrar algo silenciosamente na décima edição: por exemplo, reescreve um prompt e ninguém percebe. O autor da AQVEN descreveu o workflow em YAML sobre o Pydantic AI e permitiu que o agente acessasse o grafo apenas por meio de um servidor MCP: 18 ferramentas e 12 skills (instruções prontas). Os erros aparecem já na fase de build, como num type checker. Se um agente escreve seus pipelines de IA, primeiro construa para ele um ambiente rígido.

Processado por IA de Habr AI; editado por Hamidun News
Desenvolvedor trancou um agente de código numa gaiola de YAML: 18 ferramentas e 12 skills
Fonte: Habr AI. Colagem: Hamidun News.
Ouvir artigo
Ficha técnica e números-chave
ParâmetroDados
Fonte originalHabr AI ↗
Editor-chefe
Dado-chave #1O comando aqven check executa o flow com stubs: sem chaves, sem rede e sem custo de tokens
Dado-chave #2Os casos de teste não são entregues ao agente, então não é possível ajustar a edição para passar nos testes
Dado-chave #3O Studio mostra o preço e o tempo de cada nó e permite executar o flow a partir do meio

Imagine que você pediu a um agente de código que montasse uma automação de IA para o suporte ao cliente. As primeiras edições saem bem. Mas na décima ou décima quinta, o agente reescreve um prompt sem alarde ou quebra uma etapa vizinha, e você só descobre isso quando o cliente reclama.

O autor da ferramenta AQVEN resolveu o problema assim. Todo o workflow é descrito em arquivos YAML e Markdown sobre o framework Pydantic AI (uma biblioteca Python para trabalhar com LLMs). O agente acessa o grafo somente por um servidor MCP, ou seja, um conjunto padrão de ferramentas para agentes de IA.

São 18 ferramentas, além de 12 skills, isto é, instruções prontas para tarefas típicas. Juntos, eles formam um ambiente rígido do qual o agente não sai. Trata-se de experiência de engenharia pessoal, não de um benchmark, e é útil para quem coloca pipelines com LLMs em produção.

Uma ressalva importante: o autor também é o criador da AQVEN. É um wrapper sobre o Pydantic AI com licença source-available. O material não traz números como "erros caíram N%", então o que segue descreve uma abordagem, não um efeito comprovado.

Por que frameworks prontos não resolvem

LangGraph, Pydantic AI, CrewAI, Mastra e VoltAgent oferecem streaming, ramificações paralelas, saída JSON estruturada e schemas de entrada. Observability, ou seja, rastreamento de chamadas, também existe: Langfuse, LangSmith, Arize Phoenix, Braintrust. Segundo o autor, isso não basta quando o workflow é escrito por um agente.

Um pipeline complexo é montado a partir de padrões: map-reduce, LLM-as-a-judge (um modelo avalia as respostas de outro), ciclo de repair (correção de uma resposta falha), geração divergente e convergente. Cada padrão multiplica o número de chamadas. Depois de algumas iterações, o trace tem milhares de registros, e modelos multimodais ainda recebem tipos de dado diferentes em cada chamada. Entender o que o modelo recebeu como entrada, sobretudo quando o prompt é montado a partir de muito contexto, é quase impossível. O framework entrega o trace, mas não oferece uma forma de o humano lê-lo.

Três camadas: YAML, harness e Studio

Camada 1: workflow declarativo. Todo o flow fica em arquivos Markdown e YAML, e o código só é conectado onde é necessário. O grafo é descrito no arquivo Flow: entrada, saída, contexto e ordem dos nós. No exemplo do autor, há um caso de suporte para uma marca de iluminação inteligente com 17 nós. Ali estão a análise de anexos, a votação sobre a intenção do cliente, um formulário com repair, uma resposta da base de conhecimento e um painel de juízes.

Cada nó é uma pasta com três arquivos. O .node.yaml guarda as conexões; o .inference.yaml define o contrato de entrada e saída, com tipos e limites (por exemplo, texto de no máximo 4000 caracteres e no máximo 20 sinais). O prompt fica em *.prompt.md como um template com ramificações e fragmentos reutilizáveis. Por isso os erros aparecem na fase de build, como num type checker estático. O comando aqven check valida cada arquivo e simula a execução de cada flow com stubs no lugar dos modelos. Não são necessárias chaves nem rede, e nenhum token é gasto, então a verificação pode rodar após cada alteração.

Camada 2: harness para o agente. É o ambiente em que o agente vive e do qual não sai. Ele inclui o servidor MCP com 18 ferramentas e 12 skills.

O agente não altera o grafo por escrita direta de arquivos, mas pela ferramenta flow_patch com CAS: uma edição feita sobre uma versão desatualizada simplesmente não é aplicada. Os hooks do Claude Code executam automaticamente aqven check, pyright e pytest após cada mudança. A ferramenta prompt_preview mostra o prompt exato montado para cada nó.

Os casos de teste para avaliar o resultado não são entregues ao agente, e não é possível ajustar a edição para passar nos testes. O comando aqven new cria o projeto já com AGENTS.md, CLAUDE.

md e .mcp.json, de modo que o agente começa a trabalhar sem configuração adicional.

Camada 3: Studio. Um agente pode alterar mil linhas de uma vez, e revisar isso manualmente é inviável. Por isso o depurador mostra não uma árvore de spans, mas a estrutura do flow: para cada nó aparecem tipo, status, custo e tempo. Ramificações aninhadas se expandem como matrizes de chamadas, e cada célula traz modelo, entrada, prompt, saída e resultado da verificação.

O que isso traz na prática

Do ponto de vista de custo, há duas vantagens. Primeiro, é possível executar não o flow inteiro, mas um intervalo de nós, inclusive a partir do meio, usando as saídas de execuções anteriores. Um passo pode ser reverificado sem pagar pelo pipeline completo. Segundo, os painéis de experimento permitem comparar modelos em qualidade, preço e comportamento em diferentes situações. Para entradas multimodais isso é importante, porque os modelos se comportam de forma diferente nesses casos e apresentam bugs próprios.

As limitações são claras. A ferramenta está presa ao ecossistema Pydantic AI e a Python, e é configurada sobretudo para o Claude Code. A licença é source-available, não open source clássica. Não há medições públicas de confiabilidade. Mas a ideia em si pode ser transposta para outras stacks. Se um agente escreve suas automações, dê a ele um canal estreito de edições com versionamento, verificação sem chamadas ao modelo, um conjunto de testes oculto dele e um relatório de execução legível para humanos. Assim, a corrupção silenciosa de um prompt vira um status vermelho no build.

O código e a documentação estão no GitHub (lastonoga/AQVEN) e no site aqvenstudio.com.

História

Perguntas frequentes sobre a notícia

Por que frameworks prontos não resolvem?

LangGraph, Pydantic AI, CrewAI, Mastra e VoltAgent oferecem streaming, ramificações paralelas, saída JSON estruturada e schemas de entrada. Observability, ou seja, rastreamento de chamadas, também existe: Langfuse, LangSmith, Arize Phoenix, Braintrust. Segundo o autor, isso não basta quando o workflow é escrito por um agente.

O que se sabe sobre Três camadas: YAML, harness e Studio?

Camada 1: workflow declarativo. Todo o flow fica em arquivos Markdown e YAML, e o código só é conectado onde é necessário. O grafo é descrito no arquivo Flow: entrada, saída, contexto e ordem dos nós. No exemplo do autor, há um caso de suporte para uma marca de iluminação inteligente com 17 nós. Ali estão a análise de anexos, a votação sobre a intenção do cliente, um formulário com repair, uma resposta da base de conhecimento e um painel de juízes. Cada nó é uma pasta com três arquivos.

O que isso traz na prática?

Do ponto de vista de custo, há duas vantagens. Primeiro, é possível executar não o flow inteiro, mas um intervalo de nós, inclusive a partir do meio, usando as saídas de execuções anteriores. Um passo pode ser reverificado sem pagar pelo pipeline completo. Segundo, os painéis de experimento permitem comparar modelos em qualidade, preço e comportamento em diferentes situações. Para entradas multimodais isso é importante, porque os modelos se comportam de forma diferente nesses casos e apresentam bugs próprios.

ZK
Zhemal Khamidun — CPO da Alpina Digital, gerente de produto do AlpinaGPT. Cria produtos de IA desde 2019. O Hamidun News é um projeto pessoal que virou um agregador em produção com mais de 6.000 leitores.
✦ Hands-On AI Engineering · Hamidun Academy

Build & Ship Production AI Agents Without Boilerplate Code

Start your free 72-hour trial at Hamidun Academy (academy.hamidun.com) — interactive lessons on Claude Code & Cursor, live Tech Radar, and production agent templates.

Start 72h Free Trial →Vibe-Coding Intensive
O que você acha?
Carregando comentários…