DEV Community: Stack Builders

Beyond AGENTS.md: Turning AI Pair Programming into Workflows

Stack Builders — Thu, 09 Apr 2026 13:00:30 +0000

In practice, the starting pattern for using AI to write code is usually the same: open the IDE, highlight some code, and ask an AI agent (like Copilot or a chat‑based assistant) to "write this feature" or "fix this bug." It can prove to be very powerful and time-efficient, but on the flip side, it can quickly run into predictable failure modes:

Context window overflow and degraded responses over time
Inconsistent architectural decisions across features
Superficial or self‑congratulatory test coverage
Features drifting away from original requirements
Hidden technical debt that's hard to detect in review

The issue isn't that AI is incapable or that the agent is the wrong tool. Instead, the problem lies in teams applying it without structure.

This is where the practice of Context Engineering becomes essential. It is the foundational layer that makes AI workflows actually function in a complex repository. Jumping straight into generating code workflows often fails because, in a real-world implementation, those workflows only work if the underlying context is structured, versioned, and explicitly dependency-loaded. Context Engineering solves the "blank slate" problem by systematically managing what the LLM knows at any given moment, ensuring it only acts after loading the exact architectural guardrails required for that specific task.

We're not introducing a new standard here. This post explores an approach that builds on the theoretical foundations of Context Engineering, alongside emerging patterns around agents.md, spec‑driven development, and agent skills. We will show how you can wire these structured contexts together into a simple, deterministic workflow for everyday coding.

What is an agents.md file

An AGENTS.md file is just a README written for your coding agent. In its simplest form, it looks like this:

# AGENTS.md
You are a Python expert. Follow PEP 8.
Write tests for all code.

You then prompt your tool with something like:

- "Read AGENTS.md, then refactor userservice.py."

This approach gives you a few immediate benefits, especially on smaller projects:

The agent gets project‑specific rules before you ask for anything.
You don't have to repeat basic constraints ("follow PEP 8", "write tests") in every prompt.
New developers can rely on the same base behavior.

So, what are the limitations?

Once you get into more complex projects or lean on that pattern a bit harder, there are some places where it falls short:

Generic Instructions: Lines like "write clean code" or "follow best practices" don't give the agent a concrete process.
No enforcement: Nothing in AGENTS.md prevents you from skipping important steps, such as design or review.
No shared workflow: Each developer works with the agent differently. Some use it to sketch designs, others ask for direct implementations, and others barely touch it.
No quality gates: There's no built‑in way to say, "Before we merge, check these architectural rules and stop if something is wrong."

The agent in itself can be brilliant, but it can also introduce technical debt since the team doesn't have a shared way of working with it.

Now, we'll introduce the workflow model we use in practice at Stack Builders.

Step 1: From generic agents to explicit personas

Before introducing workflows, it helps to refine agent definitions into explicit personas.

However, it's important to note that agents are not the system itself. They are activated and constrained by workflows, which define when and how they operate.

Instead of a single, generic agent, you define concrete personas. For example, let's take an @architect-reviewer persona:

# Architect Reviewer Agent

## Role
You are the primary Architectural Reviewer for the project 'Apollo Microservices'. Your job is to ensure every code change adheres to the system's core design principles before it is committed.

## Dependencies & Context
ALWAYS load the following files for context before beginning any audit:
1. docs/architecture/microservices-principles.md
2. docs/development/golden-rules.md (for anti-patterns)
3. src/config/layer-definitions.json (for module layer boundaries)

## Mandatory Audit Checklist
Review every change (file diff) against these non-negotiable points:
1. **Layer Violation:** Does new code in /engine import anything from /ui? (Violation based on layer-definitions.json)
2. **Configuration vs. Hard-Code:** Is business logic implemented directly in code when it should be driven by configuration files (e.g., in /config)?
3. **Immutability:** Are any core entity objects modified outside of their designated factory/repository methods?
4. **Security:** Are input sanitization checks present for all external API endpoints? (Reference golden-rules.md, section 4.1)

## Response Format
If violations are found, respond *only* with a numbered list of issues, referencing the specific line numbers and the rule violated. Do not offer solutions unless explicitly asked.

## Constraints
- **NEVER** permit changes that introduce global state.
- Your response must be concise, professional, and entirely based on the provided documentation.
- Your authority is final in matters of architectural integrity.

Compared to the more basic approach, this refined definition:

Names a clear role

Loads specific dependencies every time (architecture docs, golden rules, layer definitions)

Follows a concrete checklist
Uses a strict response format
Enforces hard constraints

You can do this across multiple personas and plug them into an explicit workflow.

Step 2: Introduce simple commands (workflows)

The next step is to stop free-styling prompts and start using a small set of named commands. These are not just convenient shortcuts for common prompts. They are deterministic workflow scripts: predefined execution paths that load the right context, activate the right persona, and enforce the right sequence of steps each time they run. A simple table like this can be enough:

Command	Purpose	Persona used	What it avoids
$prepare	Set up the session	(none/system)	Context amnesia
$start-design	Create or update a design spec	architect	Premature coding
$start-feature	Implement from a spec	engineer	Spec drift
$commit	Run final checks before merging any changes	reviewer	Hidden technical debt

Each command has a short script behind it. Each workflow also declares explicit context dependencies—a list of files that must be loaded before execution. For example:

Product requirements
Technical constraints
Golden rules

This ensures the AI operates with the correct and complete context, rather than relying on the developer to manually restate everything in each prompt. More importantly, these workflows are deterministic. They are not suggestions or flexible guidelines. They are executed step by step with predefined dependencies, constraints, and checks.

This structure helps ensure:

The same inputs produce consistent outputs
Critical steps (like design or review) cannot be skipped
AI behavior becomes predictable across sessions

You can still call these commands via natural language, e.g.:

"Run $prepare, then $start-design for 'new invoice export feature'."

The point is that you and your teammates are now using the same entry points instead of inventing new prompts every time.

Step 3: Make `"prepare"` non-optional

The $prepare command is the mandatory entry point of the system. Every session begins here.

Its purpose establishes a controlled environment by:

Loading core context (requirements, rules, constraints)
Verifying that context is present
Setting behavioral constraints on the AI

Without this step, the system degrades back into traditional, unreliable prompting.

Once that's in place, your interaction pattern changes from:

"Here's a random chunk of context, please do X."

to:

"First, prepare. Then, run $start-design / $start-feature / $commit."

Step 4: Design before code with `$start-design`

A lot of issues with AI‑assisted coding come from skipping design. The model writes code fast, but it doesn't force you to think.

$start-design is intentionally about thinking.

A reasonable flow:

Create a new design document based on a simple template.
Have the architect persona ask you clarifying questions about the feature:
What problem are we solving?
Which parts of the system are in scope?
What can't change?
Fill out the design doc: scope, impacted modules, data changes, APIs, test plan, risks, edge cases, open questions.
Switch to the reviewer persona and have it scan the design for obvious gaps or rule violations.
Stop and hand the design back to you.

You then review the design like you would any other spec: edit, push back, refine. Only when you're comfortable with it do you move on.

Rule of thumb: If you wouldn't merge the design doc as a human‑written spec, don't ask the agent to implement it.

This keeps you in the role of architect instead of solely a "prompter."

Step 5: Implement the spec with `$start-feature`

With a solid design doc in place, $start-feature does something very simple, yet very important: it treats design as the single source of truth.

A typical $start-feature command might:

Load the design document.
Activate the engineer persona.
Optionally follow a test‑first loop: outline or generate tests, then implement code until they pass.
Ask the reviewer persona for a first pass on the changes.
Stop and present the result.

Because the design doc is always in view, the implementation is less likely to wander off as the conversation evolves. If something does drift, you have a concrete spec to compare against. In this workflow, the design document is treated as the immutable source of truth.

The agent is not allowed to reinterpret or extend requirements beyond what is defined in the design. This constraint is critical—it prevents scope drift and ensures implementation remains aligned with agreed specifications.

Step 6: Use `$commit` as a gate

The last command, $commit, is your pre‑merge checklist.

Load the files changed by this feature.
Load the relevant design document and "golden rules".
Use the reviewer persona to apply its checklist:
Are there forbidden dependencies between layers?
Are we leaking implementation details across boundaries?
Are there obvious security or validation gaps?
Return a list of issues, with file and line information.
Let the engineer address every issue and rerun $commit until all violations are resolved. No commit, merge, or final code integration may happen without explicit human approval.
Only then, ask for explicit human approval to merge.

This doesn't replace human review or tests, but it gives you a consistent, automated gate that catches many of the "we'll fix it later" problems before they hit main.

One key detail is that the $commit workflow is not a single-pass check. It introduces a correction loop:

If issues are found, they must be fixed
The system re-runs the review
This repeats until all violations are resolved

Only then is the user asked for explicit approval. This ensures that quality gates are not just advisory—they are enforced.

Why does this work better than AGENTS.md alone?

Once you've layered these pieces on top of your basic AGENTS.md, a few things change:

Everyone follows roughly the same path
"Prepare → design → feature → commit" becomes the default, instead of each person inventing their own approach.

Design becomes a normal artifact, not an afterthought
The agent helps you write and review specs, but you still own them. That alone reduces rework.

Context is more stable
Each command is responsible for loading what it needs. You're not constantly juggling which files to paste in or which rules to remind the model about.

You stay in charge
The model drafts, checks, and suggests. You decide what gets built, what's acceptable, and when something is done.

There is some overhead: you write a bit more up front and agree to use the commands. But for any non‑trivial feature, that cost tends to be smaller than the time you'd lose to "fast but wrong" implementations.

A key distinction in this approach is separating context from prompts:

Prompts are interactions
Context is the environment in which the AI operates

By engineering context as a system, prompts become lighter, more consistent, and less error-prone.

How to get started & where this is heading

If you're already using AGENTS.md, you don't need to adopt all of this at once. Start small: tighten your agent instructions, introduce a couple of clear personas, and add one or two commands that you actually use day‑to‑day.

What matters most is not workflows in isolation, but the combination of three elements working together:

Context engineering to ensure the AI operates with a structured, versioned, dependency-loaded context
Deterministic workflows to enforce repeatable execution and prevent critical steps from being skipped
Role-based agents to keep behavior controlled, specialized, and easier to trust

The broader ecosystem is already moving in this direction. Instruction formats like AGENTS.md help standardize how we guide agents. Skill systems package reusable capabilities. And clearer distinctions between agents, skills, and commands make it easier to design workflows that are both practical and reliable.

The approach outlined here fits into that larger evolution rather than competing with it. In our experience, the real value comes from combining these pieces into a system that gives AI enough structure to be useful without giving up engineering control. You can begin by layering that structure around the patterns you already use: a lightweight prepare step, design-first execution, explicit personas, and a commit gate with human approval.

Rule of thumb: Treat workflows and specs as the "operating system" around your agents. The more deliberate that layer becomes, the more you can trust AI to handle real work without giving up control of your engineering process.

AI-Assisted Visual QA for Figma AEM Workflows

Stack Builders — Thu, 02 Apr 2026 14:12:14 +0000

Visual QA is one of those activities everyone agrees is important…right up until it becomes the bottleneck.

A page looks “basically right,” you’re under deadline, and that last review pass turns into a game of spot the difference: margin tweaks, heading sizes, tiny spacing inconsistencies that are easy to miss and painful to repeat across dozens (or hundreds) of pages.

In a recent Quito Lambda talk at Stack Builders, our team explored a practical approach to reducing manual visual QA time using AI-assisted development and pixel-based visual comparison: pulling a baseline from Figma, capturing the “about to go live” view from Adobe Experience Manager (AEM), and generating a visual diff report that shows exactly where the UI diverges.

Stack Builders works extensively with AEM and is an official Adobe Experience Manager partner, so this kind of workflow is directly aligned with the kind of enterprise-grade content operations we help teams modernize.

The Pain: Manual Visual QA Doesn’t Scale

If you’ve ever reviewed two screenshots that look identical, you know how this goes:

A paragraph is shifted by ~40px.
A heading is an H2 instead of an H3—visually “almost the same,” but not quite.
Spacing changes by a couple of pixels, and nobody notices until a stakeholder does.

Manual checks are:

Repetitive and tiring
Time-consuming
Inconsistent (different reviewers notice different things)
Risky (small UI regressions slip through and show up in production)

And importantly, you repeat the same effort for every page, every time.

The Real-World Workflow: From Content to “Live”

In many organizations (especially those running AEM), the pipeline often looks like this:

Content writing (messaging, paragraphs, structure)
Design in Figma (layouts, tokens, components, specs)
Authoring in AEM (drag-and-drop components, build pages from templates)
Visual QA (verify AEM matches Figma)
Publish (page goes live)

AEM is particularly powerful here because it enables non-developers to assemble pages using controlled templates and components, great for scale, but it also means small configuration differences can produce subtle visual drift.

The Goal: Faster QA, More Consistency, Better Evidence

The objective isn’t to “remove QA,” it’s to make QA more reliable and dramatically less manual.

A good automated approach should:

Reduce the time spent visually inspecting pages
Increase consistency across reviews
Produce evidence (diff images + percentage change) that teams can act on quickly

This is where pixel-based visual comparison shines.

Pixel-Based Comparison: Simple Idea, Huge Leverage

At the core is a straightforward method:

Capture Screenshot A (baseline, e.g., from Figma export)
Capture Screenshot B (actual UI, e.g., AEM preview)
Compare pixels (RGB values by position)
Output:

Diff image/heatmap
Percent difference
Optional: segmented diffs per section (header, hero, etc.)

This is a classic form of visual regression testing, where you compare screenshots to catch unintended UI changes.

Where AI Fits: Building the Tool Faster (and Better) with “Vibe Engineering”

A key theme from the talk was the difference between:

Vibe coding: “Prompt it and ship it.”
Vibe engineering: Use AI for speed, but keep engineering discipline—security, reliability, maintainability, and real-world scalability.

The AI helped accelerate:

Rapid prototyping of integrations (Figma + AEM preview capture)
Refactoring guidance
Documentation generation
Security improvements (e.g., safer credential/token handling)

But the takeaway was clear: AI is strongest when paired with experienced engineering judgment, setting constraints, reviewing outputs, and enforcing standards.

A Practical Architecture: Figma + AEM + Screenshot Diffing

A lightweight architecture for AI-assisted visual QA looks like this:

Inputs

Figma: design source of truth
AEM Preview: “view as published” preview before release

Pipeline

Pull/export the relevant frame from Figma (via API)
Use browser automation to load AEM preview and capture a screenshot
Normalize: crop / resize, reduce whitespace, align viewport
Compare images (pixel-by-pixel)
Produce a report: baseline, actual, diff/heatmap, percent change

Example Tech Stack

Node.js + TypeScript
Express for APIs + Helmet for security headers
Playwright (Chromium) for headless browser automation + screenshot capture
Sharp for image preprocessing (crop/resize/cleanup)
pixelmatch for pixel-based diffs

This combination is popular because it’s scriptable, fast, and easy to run locally or in CI.

What the Report Gives You (and Why it Matters)

Instead of “it looks off somewhere,” you get:

A diff heatmap that pinpoints the UI drift
A different percentage that helps establish thresholds
A repeatable process that’s consistent across reviewers/pages

A “good” page might show ~3% difference (often driven by tiny nav or content mismatches), while subtle layout issues (like heading sizing + a 40px indentation) pushed the diff higher (~5%), and the heatmap immediately highlighted the problem areas.

This is the big win: you can move from subjective review to actionable evidence.

Why “AI Image Analysis” Didn’t Fully Replace Pixel Diffs (Yet)

We’ve also experimented with using an AI model to interpret differences more semantically (“this heading should be smaller,” “this padding is off”). That part didn’t work as reliably as hoped.

The likely reason: pure screenshot-based AI analysis can struggle to infer intent and structure unless it’s grounded in the design system and underlying specs.

Which leads to the most important next step…

Roadmap: From Pixel Diffs to Design-System Validation

Pixel diffs are powerful, but the long-term path is even better:

1) Tighten Your Design System Bridge (Figma ↔ Implementation)
If Figma tokens and component structure map cleanly to your code (or CMS components), you can validate:

typography scales
spacing rules
component variants
layout constraints

This reduces false positives and moves QA closer to “verify intent,” not just pixels.

2) Use Design Tokens Consistently
Define tokens once (e.g., “Small = 14px”) and ensure they’re respected across:

Figma
CSS / component library
AEM component styles

3) Expand Breakpoints
Desktop-only diffs are a start. Add:

tablet
mobile
responsive states

4) Batch Runs
Instead of page-by-page:

run an entire path, site section, or folder of pages
produce a consolidated report for review

5) Broaden CMS Compatibility
AEM is a great first target, but the concept generalizes to other CMS platforms.

Conclusion: Make Visual QA Faster in Your AEM Pipeline?

If your team is authoring high volumes of pages in AEM and spending too much time on repetitive reviews, this kind of workflow can pay off quickly, especially once it’s wired into CI or editorial release processes.

How to Build Multi-Agent Architectures with Google ADK

Stack Builders — Thu, 02 Apr 2026 14:01:01 +0000

Why Single Agents Don't Scale Well

Whenever we’re prototyping an AI application, we begin by creating a single agent that’s in charge of everything, from understanding the request, planning, calling tools, and generating the final response. This is fine for a simple use case, as this is easy to implement.

However, as complexity grows, the agent must manage a lot of different tasks, like validation and multiple tool calls in the same iteration loop. This can make context difficult to debug and understand because everything is happening inside a single model call.

This would mean adding more instructions and tools to our agent that don’t actually fix the structural issue. This increases the complexity and unpredictability of our agent. While single-agent systems are excellent for prototypes, we require multi-step workflows that actually separate responsibilities and are more reliable. This is where multi-agent systems shine and become a more scalable solution in the long term.

What are Multi-Agent Systems (MAS)

A Multi-Agent System "MAS" is an architecture in which multiple agents collaborate to achieve a shared objective. Instead of using a single agent to handle every responsibility, tasks are divided into smaller parts, where each agent focuses on a specific task.

Multi-agent systems patterns
Designing a multi-agent system is about choosing what pattern to use for the problem. There are some common patterns that have emerged to structure collaboration among agents.

Coordinator/Dispatcher Pattern
For this pattern, you have a central agent that acts as an orchestrator, which receives the user request and decides how to delegate the parts needed to complete the task. This orchestrator tasks other agents and gathers the results to produce the final response. The most typical example of this is a customer support chatbot, which delegates requests to particular areas depending on the expertise needed (eg, billing agent, technical support agent) and returns a response to the user's query.

Sequential Pipeline Pattern
Here, you set a linear flow where each agent executes a specific transformation and gives the output to the next agent. Each step depends on the previous one's execution, making the workflow predictable. An example of this can be an agent to make a financial report, where an agent first gets structured data from a file, another analyzes that data, and the final agent gathers all the insights in a report.

Parallel Fan-Out/Gather Pattern
This makes it possible to divide a task into independent subtasks that are executed simultaneously and gathered into a single result at the end. This pattern is perfect to reduce latency in the agent calls. An example of this can be having a research agent that gets multiple documents and summarizes them in parallel, and a final agent consolidates them into an overview.

Hierarchical Task Decomposition
Structures agents into multiple levels of responsibility, where the top agent breaks down the complex objective into manageable components, then all the sub-agents handle the components with the capability to decompose and delegate them further. For example, we can use this pattern for an agent that produces code where the sub-task would look like: creating the actual requirements, designing the solution, implementing the solution, and testing it.

Review/Critique Pattern (Generator-Critic)
We separate the generation from the evaluation; an agent produces an output, and another independently reviews it to see if there are areas of improvement, introducing an internal quality control system. This pattern can be used in code generation, where one agent produces the code and another reviews it for logical flaws, edge cases, security vulnerabilities, etc.

Iterative Refinement Pattern
This allows you to collaborate over multiple cycles to progressively improve an output, permitting other patterns into the mix to obtain a better result. For example, you might have an agent to generate initial article drafts and another agent to evaluate them and give them revisions. You can go through multiple iterations until your revisions don’t have any comments and you have an article that fits your quality criteria.

Human-in-the-Loop Pattern
For this pattern, we allow for human oversight into the workflow at defined checkpoints. The agents perform the task, but a human reviews, adjusts, and approves the output before continuing. This might be necessary in high-risk environments where accountability is crucial. For example, if you have an agent to generate and review a contract, you will still need to go through a lawyer who provides the final touches and approves it for delivery.

Google’s Agent Development Kit 101

Google’s Agent Development Kit, or ADK, is a framework designed to build, orchestrate, and deploy multi-agent systems where structure is prioritized. ADK provides a formal way to define agents instead of having ad hoc solutions. ADK also allows us to define interaction between agents, tool calls, and hierarchies that allow us to benefit from the patterns explained above.

Basic concepts to know about ADK
To actually use ADK, we should be familiar with the basic concepts that enable us to build working agent applications with ADK. The following are the most important things to know about ADK:

Agents
In ADK, an agent is the most atomic unit. They have their own instructions, model configuration, and access to tools.

Tools
Tools in ADK are structured functions that agents can invoke to accomplish a specific task. You can have tools that allow you to search the internet, format information in a particular format, send emails, etc.

Workflows and Orchestration
ADK allows for explicit orchestration. Instead of embedding multi-step reasoning inside a single prompt, ADK allows you to define how agents interact in code through the patterns explained in the previous section.

What about memory and state?
Managing state is a common challenge in AI systems, where you sometimes pass long context prompts that can get overlooked by agents. ADK provides a structured way to handle session state and memory. In this way, agents can maintain contextual information across the whole workflow without relying on prompt accumulation.

How does ADK help with observability?
This visibility is crucial for debugging and auditing. In case of an error in production environments, you need to understand how a result was generated by looking at the steps the agents took. In ADK, this is integrated within the framework, allowing you to see which agent was invoked, what context and tools were used, and how the overall workflow worked.

ADK vs other frameworks

As multi-agent systems become more common, several frameworks have emerged to help developers to implement them. They share similar goals, but they differ in their focus. Comparing ADK with other popular frameworks like LangChain and LangGraph helps us clarify where each of them fits in different projects.

LangChain is one of the most flexible frameworks available. It supports many model providers. This makes it attractive for teams that value vendor neutrality and ecosystem breadth. Despite this, we see that large systems may require additional architectural decisions to allow for maintainability.

LangGraph builds on the LangChain ecosystem by introducing explicit graph-based orchestration. It allows for complex workflows that require different states and workflow management. It’s as flexible as LangChain while offering structural control.

Google ADK takes a more structured and opinionated approach. It encourages architectural clarity and production readiness, but it is closely aligned with Google’s model ecosystem and cloud infrastructure. This makes it a strong option for teams already in that stack; this can limit flexibility for teams that value vendor portability.

In conclusion, ADK focuses on structured design and ecosystem integration. LangChain and LangGraph prioritize flexibility. As with everything in software, the right choice depends on what your project priorities are and what are the constraints you have.

A practical look into a MAS project with ADK

We’ll build a small ADK multi-agent system for expense tracking that helps an individual log transactions, auto-categorize them, track budgets, and generate a monthly summary. The goal is to show how ADK’s agent composition feels in a real project by getting hands-on experience.

This follows ADK’s standard project and root_agent entrypoint, and uses Gemini as an LLM Agent plus a Workflow Agent to orchestrate steps.

Project setup
Create a new ADK agent project and install dependencies.

> pip install google-adk
> adk create finance_tracker
> cd finance_tracker

ADK’s Python quickstart uses google-adk and a root_agent defined in agent.py.

The multi agent design
We’ll use these agents:

Intake agent: turns user text into a clean transaction payload
Gate agent: this agent is in charge of allowing the actual execution of the flow if all required data is present.
Categorizer agent: assigns a category to the expense (groceries, rent, transport, etc.)
Ledger agent: writes and reads transactions using tools, in our case SQLite
Insights agent: creates summaries and the reports

Then we connect them with a LoopAgent workflow, which is one of ADK’s deterministic Workflow Agents, this allows us to ask the user for clarification in case it is needed. This would look something like this:

Minimal implementation

from __future__ import annotations


import sqlite3
from datetime import datetime
from pathlib import Path
from typing import Any, List, Optional


from google.adk.agents.llm_agent import Agent
from google.adk.agents.loop_agent import LoopAgent
from google.adk.tools import exit_loop




DB_PATH = Path(__file__).with_name("finance.db")


# Simple SQLite-based ledger for transactions and budgets.
# This is a minimal implementation for demonstration purposes.
def _get_conn() -> sqlite3.Connection:
   conn = sqlite3.connect(DB_PATH)
   conn.execute(
       """
       CREATE TABLE IF NOT EXISTS transactions (
           id INTEGER PRIMARY KEY AUTOINCREMENT,
           ts TEXT NOT NULL,
           amount REAL NOT NULL,
           currency TEXT NOT NULL,
           merchant TEXT,
           category TEXT,
           note TEXT
       )
       """
   )
   conn.execute(
       """
       CREATE TABLE IF NOT EXISTS budgets (
           category TEXT PRIMARY KEY,
           monthly_limit REAL NOT NULL,
           currency TEXT NOT NULL
       )
       """
   )
   conn.commit()
   return conn




# Tools (callable functions) that agents can use.
def add_transaction(
   amount: float,
   currency: str = "USD",
   merchant: Optional[str] = None,
   category: Optional[str] = None,
   note: Optional[str] = None,
   ts: Optional[str] = None,
) -> dict:
   """Insert a transaction into the local ledger."""
   conn = _get_conn()
   if ts is None:
       ts = datetime.utcnow().isoformat()
   conn.execute(
       "INSERT INTO transactions (ts, amount, currency, merchant, category, note) VALUES (?, ?, ?, ?, ?, ?)",
       (ts, amount, currency, merchant, category, note),
   )
   conn.commit()
   return {"status": "success", "inserted": True, "ts": ts}




def list_transactions(
   month: Optional[str] = None,
   limit: int = 50,
) -> dict:
   """
   List transactions.
   month format: YYYY-MM, e.g. 2026-02
   """
   conn = _get_conn()
   params: List[Any] = []
   q = "SELECT ts, amount, currency, merchant, category, note FROM transactions"
   if month:
       q += " WHERE substr(ts, 1, 7) = ?"
       params.append(month)
   q += " ORDER BY ts DESC LIMIT ?"
   params.append(limit)


   rows = conn.execute(q, params).fetchall()
   items = [
       {
           "ts": r[0],
           "amount": r[1],
           "currency": r[2],
           "merchant": r[3],
           "category": r[4],
           "note": r[5],
       }
       for r in rows
   ]
   return {"status": "success", "items": items}




def set_budget(category: str, monthly_limit: float, currency: str = "USD") -> dict:
   """Set or update a monthly budget for a category."""
   conn = _get_conn()
   conn.execute(
       "INSERT INTO budgets(category, monthly_limit, currency) VALUES(?, ?, ?) "
       "ON CONFLICT(category) DO UPDATE SET monthly_limit=excluded.monthly_limit, currency=excluded.currency",
       (category, monthly_limit, currency),
   )
   conn.commit()
   return {"status": "success", "category": category, "monthly_limit": monthly_limit, "currency": currency}




def get_budgets() -> dict:
   """Return all configured budgets."""
   conn = _get_conn()
   rows = conn.execute("SELECT category, monthly_limit, currency FROM budgets").fetchall()
   items = [{"category": r[0], "monthly_limit": r[1], "currency": r[2]} for r in rows]
   return {"status": "success", "items": items}


# Agents definitions. Each agent has a specific role and can call tools or other agents as needed.


intake_agent = Agent(
   model="gemini-2.5-flash",
   name="intake_agent",
   description="Extracts transaction details from user messages.",
   instruction=(
       "Turn the user message into a transaction JSON.\n"
       "Required: amount.\n"
       "Optional: currency (default USD), merchant, note.\n\n"
       "If amount is missing or ambiguous, ask ONE short question and output:\n"
       "{ \"complete\": false }\n\n"
       "If ready, output:\n"
       "{ \"complete\": true, \"amount\": <number>, \"currency\": \"USD\", \"merchant\": null|\"...\", \"note\": \"...\" }\n"
       "Merchant may be null. Do not ask for merchant.\n"
   ),
   output_key="tx",
)


gate_agent = Agent(
   model="gemini-2.5-flash",
   name="gate_agent",
   description="Stops the workflow if intake is incomplete.",
   instruction=(
       "Look at tx in state.\n"
       "If tx.complete is false, call the exit_loop tool immediately and output nothing.\n"
       "If tx.complete is true, do nothing."
   ),
   tools=[exit_loop],
)


categorizer_agent = Agent(
   model="gemini-2.5-flash",
   name="categorizer_agent",
   description="Assigns a category to a transaction.",
   instruction=(
       "Given a transaction JSON, assign one category from this list:\n"
       "Groceries, Dining, Rent, Utilities, Transport, Health, Entertainment, Shopping, Income, Other.\n"
       "Output JSON with all original keys plus category."
   ),
)


ledger_agent = Agent(
   model="gemini-2.5-flash",
   name="ledger_agent",
   description="Writes and reads transactions and budgets using tools.",
   instruction=(
       "You manage the personal finance ledger.\n"
       "Use tools to add transactions, list transactions, set budgets, and get budgets.\n"
       "Never invent ledger entries.\n"
       "If asked for a summary, list transactions and budgets first, then compute."
   ),
   tools=[add_transaction, list_transactions, set_budget, get_budgets],
)


insights_agent = Agent(
   model="gemini-2.5-flash",
   name="insights_agent",
   description="Creates summaries and budget insights based on ledger data.",
   instruction=(
       "You produce a short monthly summary with totals by category and budget status.\n"
       "Be concrete, use numbers, and keep recommendations practical.\n"
       "If there is not enough data, say what is missing and suggest the next best action."
   ),
)


# The root agent orchestrates the workflow.
# It runs the intake agent first, then the gate agent to check if we can proceed.
# If the intake is complete, it continues to categorizer, ledger, and insights agents in sequence.
# The max_iterations=1 means it will run through this sequence once per user message.
#
# For a real application, you might want a more complex loop with conditions to
# allow for follow-up questions, corrections, etc.
root_agent = LoopAgent(
   name="root_agent",
   description="Personal finance tracking assistant.",
   sub_agents=[
       intake_agent,
       gate_agent,
       categorizer_agent,
       ledger_agent,
       insights_agent,
   ],
   max_iterations=1,
)

Results
To test the system, we can run the agent using ADK’s development server. From the project root, execute:

adk web

This starts a local web interface, available at (http://127.0.0.1:8000), where you can interact with the agent in real time. The web environment allows you to: Send natural language prompts Observe how each agent in the workflow is executed Inspect tool calls and intermediate outputs Debug the flow of state between agents

Using a simple prompt such as:

“Spent 250 on a new monitor yesterday.”

We can see the full multi-agent workflow in action, where ADK shows us each agent's output and the tools that are called. We can inspect each request to see, for example, the shared state present between the call of the intake agent and the rest of the agents. Then, this interactive environment is useful during development because it makes the orchestration visible, allowing you to see how each decision is made at each stage.

I’ve added more transactions to see how the insight agent behaves once we have enough data to generate a monthly report. This helps us test the flow as a whole, which results in the following:

Conclusion

Multi-agent systems mark a shift from prompt engineering to system design. Rather than asking one large model to act like an entire team, we delegate tasks to specialized agents with clear boundaries and controlled workflows.

With Google’s Agent Development Kit, we can progress beyond experimental setups and create organized systems that are observable, modular, and ready for production. The finance tracker example may seem straightforward, but the underlying structure can scale to much more complex areas.

As AI agents become more embedded in real products, the ability to design systems instead of just prompts will set apart prototypes from actual, used software.

Increasing confidence in your software with formal verification

Stack Builders — Thu, 21 Mar 2024 20:06:04 +0000

Testing can help you rule out some bugs in your software, but in general, it cannot ensure that your software behaves exactly like it is expected to. When you need this level of confidence in your software, formal verification comes into play!

Software is an integral part of modern society. We use it every day, directly or indirectly, to make our lives easier. We find it in our phones, it is used to run companies and governments all over the world, and it is also found on vehicles like cars and airplanes.

Naturally, given how ubiquitous software is, we would want it to be as free of bugs as possible. Errors in software affect us in different ways, like leading us to conclude inaccurate information or causing companies to lose money. In the more extreme cases, they could even cause fatal consequences resulting in deaths, for instance in a vehicle failure. These kinds of errors have happened in the past:

Therac-25, a machine unit used to treat cancer patients with radiotherapy, had several failures due to race conditions and ended up administering lethal doses of radiotherapy to six people, killing some of them and leaving the others with permanent injuries.
The Ariane 5 rocket had a software failure due to an integer overflow which resulted in the explosion of the rocket, causing a loss of $370 million. Fortunately, the Ariane 5 was unmanned.

We as developers understand the importance of correct software. At Stack Builders, we are committed to delivering high-quality code. To achieve this, we continuously explore cutting-edge techniques and tools to ensure the correctness of the software we develop. In this blog post, we will provide an introduction to formal verification, a technique used to rigorously prove that a program is correct. Later on, we will dig a bit deeper into the more precise meaning of what the term "correct" entails in the context of software programs.

Wanting our programs to be free of these critical bugs brings us to the question: how can we increase our confidence in the software we are developing? One way to do that, and the most widespread approach, is testing. This includes all sorts of tests: unit tests, integration tests, end-to-end tests, etc. Testing helps us spot potential bugs in our software earlier before it gets shipped, and can also help prevent regressions.

Testing and the absence of bugs

Tests can help us find bugs in our programs, especially when covering corner cases. However, tests cannot, in general, ensure the absence of bugs. Testing is an approach that aims to check the behavior of software against a given set of test cases. Ensuring the absence of bugs with testing requires us to define a set of test cases that covers the entirety of the domain of any given function that we want to test.

// Logical AND
function and(x: Bool, y: Bool) -> Bool {
    if (x == False) then
        return False;
    else
        return y;
}

// Tests
assert(and(False, False) == False)
assert(and(False, True) == False)
assert(and(True, False) == False)
assert(and(True, True) == True)

In this example (in a made-up programming language, to keep things simple) we have defined an and function which takes two boolean arguments and returns a boolean value. We have defined four tests to check the behavior of and. These four tests ensure the absence of bugs in the function since we have defined tests that cover the entire domain of the function; that is, we have one test for every possible combination of the arguments' values.

The easiest way to know how many test cases we need for a particular function is to calculate the size of its domain. In this case, we have two possible values for the first argument and two possible values for the second argument, so the size of and's domain is 2 * 2 = 4.

Easy, right? Well, let's try to use the same testing approach in another example:

function square(x: Int32, y: Int32) -> Int32 {
    return x * y;
}

Uh-oh... what happens if we try to cover the whole domain of the square function? Let's see: the first argument has 2^32 possible values, and the second argument has 2^32 possible values, so the size of the square's domain is... 2^32 * 2^32 = 18446744073709551616.

It is clearly unfeasible to have that many test cases written! But it can get worse:

function toUppercase(name: String) -> String {
    for (letter in name) do
        uppercase(letter);
    return name;
}

The toUppercase function takes a string and returns that string with every letter turned into uppercase. In this case, the domain is theoretically infinite, so it's straight out impossible to write test cases for every input. Realistically, if we assume that a String is arbitrarily large and allocated in dynamic memory, the number of possible values depends on the free memory of the system, which is still an astronomical number.

As we were saying earlier, to ensure the absence of bugs with testing, we need to cover the domain of the function we are testing. We have seen that in general, this is not doable or practical.

However, there are other techniques more effective than testing when we aim to ensure that our program is correct. Many of these techniques come from formal methods research efforts.

One of the most well-known and widely applied techniques, and the one we will be focusing on, is formal verification.

Formal verification in short

Formal verification is a technique used to prove the correctness of a program against a given specification. That might be a lot to take in, so let's break it down.

The first important term to introduce is specification. A specification, simply put, is a description of what a program should do. The concept of specification appears in other areas of software engineering, and we as developers often encounter specifications in its informal form. One example of a specification, taking the toUppercase function we defined earlier, would be:

The toUppercase function receives a string argument and returns a matching string in which every letter appearing in the argument is turned into uppercase. Every other character is left untouched.

In formal verification, as the name suggests, we deal with formal specifications of our programs. A formal specification is a more mathematical and rigorous description of what our program does. Formal specifications are written in what's called a specification language; the specifications we write might look like code written in a conventional programming language, but specification languages are usually much limited in their expressive power. The goal of a specification language is not to be a programming language on its own, but rather to describe particular properties of our programs. For example, going back to our toUppercase function:

function toUppercase(name: String) -> result: String {
    satisfies:
        - result.length == name.length
        - forall (i <- 0..result.length-1). result[i] == uppercase(name[i])
}

This could be an example of a specification for our toUppercase function in a specification language I just made up purely for illustrative purposes. In our specification, we unambiguously state:

The toUppercase function receives a string argument name, and returns a string result, satisfying the two following conditions:

"the length of result (the returned string) must be equal to the length of name (the argument string)."
"for all indices i from 0 to the length of result minus 1, the character at index i in the result string must be equal to the character at index i in the name string applied to the uppercase function."

This is relatively similar to our informal specification we gave earlier! Just a bit more math-y.

The properties we can describe of our software are determined by the focus and intent of the specification language. A specification language can be aimed at checking the kinds of data our programs deal with, or whether our programs return values satisfying some properties (like in our example), or even more general semantic properties, like how a program behaves when seeing it from a concurrency point of view.

Now that we have introduced the concept of a specification for our functions or programs, we can now answer the question of what we mean when we say that a program is correct. As you might have guessed, we say that a program is correct when it adheres to the specification we have given for that program. It's as simple as that! It also relates to our intuitive notion of correctness: we would say that a program is correct when it behaves exactly like it is supposed to. A specification describes this behavior.

This naturally implies that the program is free of bugs! ...well, while being true, this is kind of inaccurate. The kinds of bugs that get ruled out depend on the kind of behavior that can be expressed by our specification language. One specification language could be great at allowing you to express concurrency behavior, but not have support for modeling memory access behavior. The fact that our program is correct against a specification written in such a specification language means that it is free of concurrency bugs, which is still great if that's what we're looking for! But it means nothing in terms of memory safety.

Finally, we can go back to our main topic. We stated at the beginning of this section that formal verification is the process of verifying (i.e. checking) that a program adheres to the formal specification we have given for that program. With everything we have introduced so far, we can now make sense of this definition.

Here is what a general process of formal verification looks like:

Using formal verification

Now, how can I as a developer make use of this? You might have already been using a form of verification all this time without realizing it! If you have developed programs in a statically typed language such as Java, C/C++, C#, Go, Rust or Haskell, you have used one of the most common and useful verification tools out there: static type checking. With static types, you are describing the expected behavior of your program when it comes to data: if an argument is tagged as a string, then it must be treated as a string or it will result in a compiler error (meaning that your program is not correct). The specification for your program is comprised of the type annotations.

float findArea(float x, float y) { ... }

In this example of a function definition in C, we have just provided a specification for how you expect your function to behave:

The **findArea* function receives two floating-point numbers as arguments and returns another floating-point number.*

Admittedly, this specification is fairly limited in expressing the behavior of our function: it says nothing about what the function does, and there are many other functions that we could come up with that would fit in that description. But it still does a very good job of ruling out potential bugs when calling the findArea function with incorrect data (e.g. a string argument). The type systems found in Java or C are not particularly expressive, but you can find type systems like the ones found in Haskell or Rust that allow you to express much more nuanced properties of the kinds of data that your program can accept. Type systems keep being researched and taken even further to check for the correctness of other useful properties such as concurrency (e.g. session types) or memory access (e.g. linear types).

However, as we showed in the examples earlier, when relying on verification we usually want to have ways to describe in more detail how our program behaves. It's possible to find specification languages and tools that integrate tightly with a given programming language, allowing us to express formal properties as annotations in the source code. For example, Java Modelling Language (JML):

public static final int MAX_BALANCE = 1000; 
private /*@ spec_public @*/ int balance;

//@ requires 0 < amount && amount + balance < MAX_BALANCE;
//@ assignable balance;
//@ ensures balance == \old(balance) + amount;
public void addToAccount(int amount) { balance += amount; }

The formal specification in this case is given by the annotations just above the function. The required annotation is a precondition, a property that must hold right before the addToAccount function is called. The ensures annotation is a postcondition, a property that must hold right after the addToAccount function is called and has finished executing. This fashion of specifying a function's behavior is called design-by-contract.

The useful thing about functions that use design-by-contract is that if we are able to guarantee that when calling the function the stated precondition holds, then we can safely assume that the stated postcondition will hold when the function completes its execution. This is possible because a design-by-contract verification tool will try to ensure that the postcondition holds by formally reasoning about the implementation of the function. Otherwise, the verification tool will raise an error stating that the function is not correct! We will need to go back to the function and see how the implementation is violating the postcondition.

Other formal verification tools are independent of particular programming languages and are instead focused on verifying an abstract model of our program's behavior. A couple of examples:

TLA+ is a formal specification language with a complete toolchain and IDE, with a great focus on concurrent and distributed systems.
Coq is an interactive theorem prover that is also used to verify algorithms and programs. It provides a formal specification language called Gallina.

These kinds of tools can be extremely powerful if used properly, although admittedly they can also be pretty hard to use for people less familiar with formal verification. They can be used to verify very complex programs. For example, CompCert C is a verified compiler for C that can provide extra guarantees that there won't be bugs generated during compilation (compilers are also programs created by humans, and can have bugs!), intended for use in life-critical software. CompCert C is primarily written and verified in Coq.

Conclusions

Formal verification is not a substitute for testing. Given that it's noticeably harder and more time-consuming to ensure correctness for a program when compared to writing some relevant (even if they are not 100% exhaustive) test cases, it still makes more sense to simply rely on testing when deadlines are tight and what you care about is catching the most prominent bugs that could appear in your software.

However, we have seen that there are times when tests are not enough to ensure that our programs behave exactly as we expect them to. When we need such a high degree of confidence in our software, formal verification can help us accomplish that.

To get started with formal verification, you can try out one of the tools we mentioned earlier, or you can look up on the Internet what's currently available for a programming language of your choice. If your chosen programming language is mainstream enough, chances are there will be at least one tool to perform some degree of formal verification in your programs.

A QuickCheck Tutorial: Generators

Stack Builders — Mon, 11 Mar 2024 21:37:43 +0000

Learn how to use QuickCheck’s combinators to create simple generators of random values. From reversing lists to rolling dice and crafting generators for your data types, this tutorial will enhance your programming skills and help you get started with property-based testing in Haskell. This popular post was originally written in 2015 and updated in January 2024 to reflect QuickCheck library changes up to the most recent version (2.14.3) as well as other minor fixes.

QuickCheck is a Haskell library for testing properties using randomly generated values. It's one of the most popular Haskell libraries and part of the reasonwhy functional programming has mattered.

In short, we can use functions to express properties about our
programs and QuickCheck to test that such properties hold for large numbers of random cases.

For example, given a function to reverse the elements of a list:

import Prelude hiding (reverse)

reverse :: [a] -> [a]
reverse []     = []
reverse (x:xs) = reverse xs ++ [x]

We can define a property to check whether reversing a list (of
integers) yields the same list or not:

prop_ReverseReverseId :: [Integer] -> Bool
prop_ReverseReverseId xs =
  reverse (reverse xs) == xs

And QuickCheck will generate 100 lists and test that the property
holds for all of them:

ghci> import Test.QuickCheck
ghci> quickCheck prop_ReverseReverseId
+++ OK, passed 100 tests.

If we define a property to check whether reversing a list once yields the same list or not (which holds only for some lists):

prop_ReverseId :: [Integer] -> Bool
prop_ReverseId xs =
  reverse xs == xs

QuickCheck will generate lists until it finds one that makes the property fail:

ghci> quickCheck prop_ReverseId
*** Failed! Falsified (after 5 tests and 4 shrinks):
[0,1]

This is a simple example, but it's good enough for illustrating the basic idea behind testing real world Haskell libraries and programs using QuickCheck.

Now, a fundamental part of QuickCheck is random generation of values.
Let's take a look at some of the pieces involved in this process and some examples of how to generate our own random values.

To generate a random value of type a, we need a generator for values of that type: Gen a. The default generator for values of any type is arbitrary, which is a method of QuickCheck's Arbitrary type class:

class Arbitrary a where
  arbitrary :: Gen a
  ...

If we have a generator, we can run it with generate:

generate :: Gen a -> IO a

Let's run arbitrary to generate values of some basic types that have
an instance of Arbitrary:

ghci> generate arbitrary :: IO Int
27
ghci> generate arbitrary :: IO (Char, Bool)
('m',True)
ghci> generate arbitrary :: IO [Maybe Bool]
[Just False,Nothing,Just True]
ghci> generate arbitrary :: IO (Either Int Double)
Left 7

Additionally, QuickCheck provides several combinators that we can use to generate random values and define our own instances of Arbitrary.
For instance, we can use choose to generate a random element in a given range:

choose :: Random a => (a, a) -> Gen a

Let's define a dice with choose:

import Test.QuickCheck

...

dice :: Gen Int
dice =
  choose (1, 6)

And roll it:

ghci> generate dice
5

We can also generate a Bool with choose (in fact, this was
QuickCheck's default generator for Bool before switching to a faster implementation using chooseEnum):

arbitraryBool :: Gen Bool
arbitraryBool =
  choose (False, True)

As another example, we can use sized to construct generators that depend on a size parameter:

sized :: (Int -> Gen a) -> Gen a

Let's take a look at how QuickCheck generates lists:

arbitraryList :: Arbitrary a => Gen [a]
arbitraryList =
  sized $
    \n -> do
      k <- choose (0, n)
      sequence [ arbitrary | _ <- [1..k] ]

Given a size parameter n, QuickCheck chooses a k from 0 to n, the number of elements of the list, and generates a list with k arbitrary elements.

We can follow this pattern to construct generators for our own data types. Let's use (rose) trees as an example of how to do this:

data Tree a
  = Tree a [Tree a]
  deriving (Show)

A rose tree is just a node and a list of trees. Here's a sample tree:

aTree :: Tree Int
aTree =
  Tree 5 [Tree 12 [Tree (-16) []],Tree 10 [],Tree 16 [Tree 12 []]]

Given such a tree, we can ask for things such as the number of nodes:

nodes :: Tree a -> Int
...

Or the number of edges:

edges :: Tree a -> Int
...

The sample tree has 6 nodes and 5 edges, for instance:

ghci> nodes aTree
6
ghci> edges aTree
5

Given definitions for nodes and edges, we can test that they satisfy the theorem that every tree has one more node than it has edges:

prop_OneMoreNodeThanEdges :: Tree Int -> Bool
prop_OneMoreNodeThanEdges tree =
  nodes tree == edges tree + 1

But Tree a is not an instance of Arbitrary yet, so QuickCheck doesn't know how to generate values to check the property. We could simply use the arbitrary generator for lists:

instance Arbitrary a => Arbitrary (Tree a) where
  arbitrary = do
    t <- arbitrary
    ts <- arbitrary
    return (Tree t ts)

But we wouldn't be able to guarantee that such a generator would ever stop. Thus, we need to use the sized combinator:

instance Arbitrary a => Arbitrary (Tree a) where
  arbitrary =
    sized arbitrarySizedTree

arbitrarySizedTree :: Arbitrary a => Int -> Gen (Tree a)
arbitrarySizedTree m = do
  t <- arbitrary
  n <- choose (0, m `div` 2)
  ts <- vectorOf n (arbitrarySizedTree (m `div` 4))
  return (Tree t ts)

Given a size parameter m, we generate a value of type a, choose a number n to be the number of trees in the list, and then generate n trees using the vectorOf combinator. We use the div function to make sure that generation stops at some point.

Let's test the generator:

ghci> generate arbitrary :: IO (Tree Int)
Tree (-19) [Tree (-2) [Tree 15 [],Tree 28 []]]
ghci> generate arbitrary :: IO (Tree Int)
Tree 30 [Tree 15 [],Tree 19 [Tree 3 [],Tree (-28) []]]
ghci> generate arbitrary :: IO (Tree Int)
Tree (-11) [Tree (-6) [Tree (-6) [],Tree 1 []]]

Can you define the nodes and edges functions so that the tests pass?

ghci> quickCheck prop_OneMoreNodeThanEdges
+++ OK, passed 100 tests.

All of the examples were tested with GHC 9.6.4 and
QuickCheck 2.14.3. For more information, see the
QuickCheck manual