The WAT framework: workflows, agent and tools

Module: 3. The WAT framework | Time: about 35 min theory + 30 min practice

The gist

A good kitchen has three parts: the recipe (what to do and in what order), the ingredients (the actual food), and the chef (the one who reads the recipe and uses the ingredients). Take away any part and nothing gets made. WAT applies the same logic to agent systems.

Key concepts

• WAT = Workflows + Agent + Tools, three inseparable parts of a system
• A workflow (a work process, a flow of tasks) = a recipe in plain language (written in Markdown, a simple text formatting language)
• Tools = specific actions (calls to an API, an application programming interface; scripts)
• The agent (an autonomous worker program) = the one who reads the recipe and uses the ingredients
• The folder structure of a WAT project
• How the agent improves the system over time

Theory

Three components: from abstraction to reality

Most people who hear "agentic AI" just picture a "smart chatbot." But real agent systems are built in a more complex way, and that complexity is where all the power lives.

The WAT framework is a simple way to think about the architecture of any agent system.

W: Workflows

A: Agent

T: Tools

Each component plays its own role. Together they make a system that can carry out complex, multi-step tasks.

W: The workflow, a recipe in plain language

🎨 Picture this: a workflow is like a recipe in a cookbook. It's written in everyday language that anyone who can read understands. You don't need to be a chemist to understand "add salt." You don't need to be a programmer to understand "find 5 news items and send an email."

A workflow is step-by-step instructions written in everyday language (Markdown). It's the recipe the agent will follow.

What goes into a workflow:

• Goal: what should happen as a result
• Steps: what to do and in what order
• Conditions: what to do if something goes wrong
• Tools: which tools to use at which step
• Checkpoints: where human confirmation is needed

A sample workflow for a weekly newsletter:

# Workflow: Weekly Real Estate Newsletter

## Goal
Collect 5 current news items, generate an HTML email,
send it to the recipient list every Monday at 9:00 AM.

## Steps

### Step 1: Collect news
Use the `research_news` tool to search.
Query: "real estate market [current week]"
Expected result: 5-7 news items with a headline, a short description and a link.

### Step 2: Generate the email
Use the `generate_newsletter_html` tool.
Pass: the news list from step 1, today's date.
Style: see /config/newsletter_style.json.

### Step 3: ⚠️ HUMAN REVIEW
Stop execution. Show an HTML preview.
Wait for confirmation before sending.

### Step 4: Send
Use the `send_via_gmail` tool.
Recipients: from /config/recipients.json.
Subject: "Real estate digest: [today's date]"

### Step 5: Archive
Save the final HTML to /archive/YYYY-MM-DD.html.
Write to the log: send date, number of recipients, subject.

Notice: the workflow is written in plain English, not in Python (a programming language). That's essential. Anyone can read and edit it, not just a developer. That makes the system understandable and manageable.

T: Tools, specific actions

🎨 Picture this: tools are like individual specialists on a crew. One only lays tile. Another only paints. A third only does electrical work. Each does their own job, and nobody wanders into someone else's area. The agent, as the foreman, decides whom to call at each stage.

Tools are executable functions. If the workflow says "use the research_news tool," that means call a specific script or API.

Each tool does one specific thing. The principle: one function, one responsibility.

Sample tools:

Structure of a typical tool (Python):

# tools/research_news.py

def research_news(query: str, num_results: int = 5) -> list[dict]:
    """
    Finds news for a query through the Perplexity API.
    
    Returns a list of dictionaries: [{title, description, url, date}]
    """
    # API call
    # process the response
    # return structured data

Tools don't make decisions. They just perform a specific action and return a result. The agent makes decisions based on the workflow.

A: The agent, the head chef

The agent is Claude Code itself (or another LLM, a large language model). It:

1. Reads the workflow (the recipe)
2. Chooses which tool to use at which step
3. Passes data between tools
4. Handles unusual situations
5. Stops in the right places for human review
6. Adapts if something goes wrong

The agent's main strength is adaptability.

If the research_news tool returns only 3 news items instead of 5, a rigid, rule-based automation will crash with an error. The agent adapts: it runs another search with a different query, or continues with three items, or asks you what to do.

If a news item turns out to be in Spanish, the agent translates it on its own, because it understands the newsletter is in English (that's written in CLAUDE.md).

How the three components interact

Workflow (recipe)
       ↓ reads
    Agent
    ↙   ↘  calls
 Tool1    Tool2
    ↘   ↙  gets results
    Agent
       ↓ continues through the workflow
    ...next step...

A workflow without tools = a recipe without ingredients.

You wrote "mix the flour with the eggs," but there's no flour and no eggs. A workflow that says "find news" is useless if there's no tool that knows how to search.

Tools without a workflow = ingredients without a recipe.

You have flour, eggs, sugar, milk. What do you make? Too many choices, no direction. Tools without a workflow don't give the system a direction.

An agent without a workflow and tools = a chef without a kitchen.

Smart and experienced, but without a recipe and ingredients, it can't cook anything.

🎨 Picture this: WAT missing one part is like an orchestra without a conductor (the agent), without sheet music (the workflow) or without instruments (the tools). Each component is irreplaceable. You can play a concert with three violins, but not with a conductor and sheet music and no violins.

The folder structure of a WAT project

Here's the standard structure you'll use for every project:

my-project/
├── CLAUDE.md                    ← system prompt (the text instructions to the AI), see the lesson on CLAUDE.md
├── .env                         ← API keys (never in git, the version control system for code!)
├── main.py                      ← entry point
│
├── workflows/                   ← Workflows
│   ├── main_workflow.md         ← main workflow
│   └── fallback_workflow.md     ← backup for errors
│
├── tools/                       ← Tools
│   ├── research.py              ← finding information
│   ├── generate_content.py      ← generating content
│   ├── send_email.py            ← sending emails
│   └── archive.py               ← archiving
│
├── config/                      ← Configuration
│   ├── style.json               ← style, colors, settings
│   └── recipients.json          ← recipients/settings
│
├── brand_assets/                ← Brand materials
│   ├── logo.png                 ← logo
│   └── brand_guidelines.md     ← brand rules
│
├── docs/                        ← Documentation (optional)
│   └── api-reference.md
│
└── logs/                        ← Automatic logs
    └── (created automatically)

Why this exact structure:

• All workflows in one place → easy to find and change
• Each tool in its own file → easy to replace or improve one
• Configs separate from code → you change settings without touching code
• Brand assets separate → the agent knows where to get brand materials
• .env in the root → the standard place for keys

How the agent improves the system over time

🎨 Picture this: after the first season, the head chef looks at the feedback: "people love the chowder, the fish keeps coming back half-eaten." The chef improves the menu. The agent does the same with logs: it analyzes patterns and suggests improvements. The system gets smarter with use.

This is an important feature of WAT that people often underestimate.

After several runs of a workflow, the agent starts to see patterns:

• "Every time I search for news about existing-home sales, the results are worse. Maybe refine the query?"
• "This tool often returns duplicate news items. Add deduplication?"
• "Emails get opened more when the subject line includes the date. Build that into the template?"

You can ask the agent:

Analyze the last 10 runs of the newsletter workflow in /logs/.
What's working well? What should be improved?
Suggest specific changes to the workflow or tools.

The agent will read the logs, analyze them and suggest specific changes. That's what "the agent improves the system" means: not by magic, but through analysis of real data.

A real structure example: Lead Qualifier

lead-qualifier/
├── CLAUDE.md                        ← system prompt
├── .env                             ← API keys (CRM, Customer Relationship Management; email; Anthropic)
├── .gitignore                       ← exclude .env, logs/, node_modules/
├── main.py                          ← entry point
│
├── workflows/
│   ├── qualify_lead.md              ← main qualification workflow
│   └── escalate_to_human.md         ← workflow for tricky cases
│
├── tools/
│   ├── fetch_lead_from_crm.py       ← get lead data from the CRM
│   ├── enrich_company_data.py       ← add data about the company
│   ├── score_lead.py                ← score the lead
│   ├── send_notification.py         ← notify the manager
│   └── update_crm_status.py         ← update the status in the CRM
│
├── config/
│   ├── scoring_rules.json           ← scoring rules (industry, size, budget)
│   └── notification_templates.json  ← notification templates
│
├── docs/
│   └── crm-api-reference.md         ← CRM API documentation
│
└── logs/
    └── (created automatically)

Notice: each tool does exactly one thing. The workflow describes the order of calls. The agent coordinates.

Practice

Exercise: Draw a WAT diagram for an automation you want to build.

Step 1, Choosing a task (5 min):

Pick one:

• Automatic news emails to clients
• Automatic posting to social media
• An automatic sales report
• Automatic qualification of incoming leads
• Your own task

Step 2, The WAT diagram (15 min):

On paper or in any editor, draw three blocks:

[WORKFLOW]
1. First step
2. Second step
3. ⚠️ Human review
4. Fourth step

[TOOLS]
- Name → what it does → which API/service
- Name → what it does → which API/service

[AGENT]
- What the agent decides on its own
- Where the agent stops for review

Step 3, Creating the structure (10 min):

Create a project folder with an empty WAT structure using Claude Code:

Create a standard WAT project structure for [your task].
Create empty files with the right names.
In each file, write a comment about what should go in it.
Create a CLAUDE.md with a description of the project.

Common mistakes

❌ Mistake: Writing all the logic in one main.py file (the God Object pattern).

✅ Right: One tool = one file. The workflow coordinates the calls. This lets you change and test tools separately without breaking the whole system.

❌ Mistake: Writing the workflow in Python/JavaScript (a programming language) instead of Markdown.

✅ Right: A workflow is written in plain language (Markdown). That's its main advantage: anyone can read and edit it, not just a developer. The agent translates the instructions into actions itself.

❌ Mistake: Not adding a human checkpoint (human-in-the-loop) to the workflow.

✅ Right: Always put a HUMAN REVIEW marker before irreversible actions (sending email, publishing, changing the CRM). Especially on the first runs, while the system hasn't been proven.

Tools and resources

• Claude Code: for creating the project structure
• draw.io: a free online tool for drawing diagrams
• Excalidraw: a simple tool for sketching architecture diagrams
• trigger.dev: a platform for running workflows in production
• n8n: an alternative for building visually: you can run it on your own server (the Community Edition is free) or use a cloud plan. Current prices: What's current
• Claude Code GitHub: example projects and issues

→ See the lesson CLAUDE.md: the system prompt that describes a WAT project

→ See the lesson The Four C's framework: Context, Connections, Capabilities, Cadence

→ See the lesson Your first workflow LIVE: from idea to a working automation

Key takeaways

WAT = three inseparable parts. Take away any one, and the system doesn't work.

A workflow is written in plain language (Markdown), not code. Anyone can read and change it.

Each tool does one thing. The agent coordinates; the tools execute.

A standard folder structure speeds up the work: the agent knows where to look without explanations.

Next lesson

→ Your first workflow LIVE: newsletter automation from idea to launch