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
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.
- 21 de nov. de 2026Anthropic cortou em 20% o preço do Claude Fable 5.2, e no teste de código ele quase empata com o Opus 5.5
- 21 de nov. de 2026Dreamteam capta US$ 53 milhões para um CRM que se preenche sozinho a partir de e-mails e ligações
- 21 de nov. de 2026Claude Opus 5.5 completa o horror Dimension 9 a partir de 15 salas criadas pelo autor
- 21 de nov. de 202622 agentes Claude passaram seis semanas atrás de respostas sobre buracos negros e resolveram dois problemas
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.
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.
O essencial da IA — uma vez por semana
Sete histórias que realmente importaram, escolhidas a dedo. Sem ruído nem releases.
Pronto! Verifique seu e-mail para a confirmação.