Free Intensive Nov 21–22Free 2-day hands-on Vibecoding Intensive on Nov 21–22 at 16:00 MSK (Sat–Sun) · Live Cohort 3 starts Nov 23Join Free →Cohort 3 (Nov 23)
ReleaseInsight · On RadarHabr AI→ original

A Developer Locked a Coding Agent in a YAML Cage: 18 Tools and 12 Skills

A coding agent writes code well, but on the tenth edit to a business automation it quietly breaks things, for example by rewriting a prompt, and nobody notices. The author of AQVEN described the workflow in YAML on top of Pydantic AI and let the agent touch the graph only through an MCP server: 18 tools and 12 skills (ready-made instructions). Errors show up at build time, the way a type checker catches them. If an agent writes your AI pipelines, build a strict environment for it first.

AI-processed from Habr AI; edited by Hamidun News
A Developer Locked a Coding Agent in a YAML Cage: 18 Tools and 12 Skills
Source: Habr AI. Collage: Hamidun News.
Listen to article
Article Fact Sheet & Key Figures
ParameterDetails
Primary sourceHabr AI ↗
Editor-in-Chief
Aqven check runs the flow on stubsno keys, no network, no token costs
Key metric #2The agent is not given test cases, so it cannot tune an edit to pass them
Key metric #3Studio shows the price and time of each node and can run a flow from the middle

Imagine you have asked a coding agent to build an AI automation for a customer support team. The first edits go fine. But by the tenth or fifteenth, the agent quietly rewrites a prompt or breaks a neighboring step, and you learn about it from a customer.

The author of the AQVEN tool solved this problem as follows. The entire workflow is described in YAML and Markdown files on top of the Pydantic AI framework (a Python library for working with LLMs). The agent has access to the graph only through an MCP server, that is, the standard set of tools for AI agents.

There are 18 such tools, plus 12 skills, meaning ready-made instructions for typical tasks. Together they form a rigid environment that the agent does not leave. This is personal engineering experience, not a benchmark, and it is useful for those shipping LLM pipelines to production.

An important caveat: the author makes AQVEN himself. It is a wrapper over Pydantic AI with a source-available license. The material contains no figures such as "errors dropped by N%," so what follows describes an approach, not a proven effect.

Why ready-made frameworks don't solve it

LangGraph, Pydantic AI, CrewAI, Mastra, and VoltAgent support streaming, parallel branches, structured JSON output, and input schemas. Observability, meaning call tracing, exists too: Langfuse, LangSmith, Arize Phoenix, and Braintrust. According to the author, this is not enough when an agent writes the workflow.

A complex pipeline is assembled from patterns: map-reduce, LLM-as-a-judge (one model evaluates another model's answers), a repair loop (fixing a failed response), and fan-out/fan-in generation. Each pattern multiplies the number of calls. After a few iterations, the trace contains thousands of records, and multimodal models accept different data types in their calls. It is almost impossible to understand exactly what the model received as input, especially when the prompt is assembled from a pile of context. The framework provides a trace, but gives a human no practical way to read it.

Three layers: YAML, harness, and Studio

Layer 1: declarative workflow. The whole flow lives in Markdown and YAML files, and code is attached only where it is needed. The graph is described in a Flow file: inputs, outputs, context, and the order of nodes. In the author's example, a support case for a smart lighting brand has 17 nodes. It includes attachment parsing, a vote on the customer's intent, a form with repair, an answer from a knowledge base, and a panel of judges.

Each node is a folder of three files. The .node.yaml file holds the connections, and the .inference.yaml file holds the input and output contract with types and limits (for example, text no longer than 4000 characters, no more than 20 signals). The prompt is stored in *.prompt.md as a template with branching and reusable fragments. As a result, errors surface at build time, like with a static type checker. The aqven check command validates every file and simulates a run of each flow with stubs in place of models. No keys or network are needed and no tokens are spent, so the check can run after every edit.

Layer 2: harness for the agent. This is the environment in which the agent lives and from which it does not escape. It includes an MCP server with 18 tools and 12 skills.

The agent edits the graph not by writing files directly but through the flow_patch tool with CAS: an edit made against an outdated version simply won't apply. Claude Code hooks automatically run aqven check, pyright, and pytest after every change. The prompt_preview tool shows the exact assembled prompt of a node.

Test cases for evaluating results are not given to the agent, so it cannot tune an edit to fit the tests. The aqven new command creates a project with AGENTS.md, CLAUDE.

md, and .mcp.json right away, so the agent is ready to work without setup.

Layer 3: Studio. An agent can change a thousand lines at once, and that cannot be reviewed by hand. So the debugger shows not a tree of spans but the structure of the flow: each node displays its type, status, cost, and time. Nested branches expand as call matrices, and each cell contains the model, input, prompt, output, and validation result.

What this gives in practice

From a cost standpoint, two things are useful. First, you can run not the whole flow but a range of nodes, including starting from the middle using the outputs of previous runs. A single step can be rechecked without paying for the entire pipeline. Second, experiment panels let you compare models on quality, price, and behavior in different situations. This matters for multimodal inputs, where models behave differently and have their own bugs.

The limitations are clear. The tool is tied to the Pydantic AI and Python ecosystem and is configured primarily for Claude Code. The license is source-available, not classic open source. There are no public reliability measurements. But the underlying idea transfers to other stacks. If an agent writes your automations, give it a narrow editing channel with versioning, a check that runs without calling a model, a test set hidden from the agent, and a run breakdown that a human can read. Then a silent prompt corruption becomes a red status on the build.

The code and documentation are on GitHub (lastonoga/AQVEN) and at aqvenstudio.com.

Story

Key Questions Answered

Why ready-made frameworks don't solve it?

LangGraph, Pydantic AI, CrewAI, Mastra, and VoltAgent support streaming, parallel branches, structured JSON output, and input schemas. Observability, meaning call tracing, exists too: Langfuse, LangSmith, Arize Phoenix, and Braintrust. According to the author, this is not enough when an agent writes the workflow. A complex pipeline is assembled from patterns: map-reduce, LLM-as-a-judge (one model evaluates another model's answers), a repair loop (fixing a failed response), and fan-out/fan-in generation.

What are the key details on Three layers: YAML, harness, and Studio?

Layer 1: declarative workflow. The whole flow lives in Markdown and YAML files, and code is attached only where it is needed. The graph is described in a Flow file: inputs, outputs, context, and the order of nodes. In the author's example, a support case for a smart lighting brand has 17 nodes. It includes attachment parsing, a vote on the customer's intent, a form with repair, an answer from a knowledge base, and a panel of judges. Each node is a folder of three files.

What this gives in practice?

From a cost standpoint, two things are useful. First, you can run not the whole flow but a range of nodes, including starting from the middle using the outputs of previous runs. A single step can be rechecked without paying for the entire pipeline. Second, experiment panels let you compare models on quality, price, and behavior in different situations. This matters for multimodal inputs, where models behave differently and have their own bugs. The limitations are clear.

ZK
Zhemal Khamidun — CPO at Alpina Digital, product manager of AlpinaGPT. Building AI products since 2019. Hamidun News is a pet project that grew into a production aggregator with 6,000+ readers.
✦ 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
What do you think?
Loading comments…