MODULE 6  ·  DAY 2

The Declarative Agent

Agentic RAG, an agent you write down, not code up.

container Aria the agent SOUL.md AGENTS.md SKILL.md MCP tools

Gourav Shah  ·  Containers for GenAI & Agentic AI  ·  School of DevOps & AI

M6·01

What you'll learn

Write an agent, not just call a model.

12 34 5 Define an agent as Markdown — SOUL.md + AGENTS.md + a SKILL.md See why agentic RAG beats naive RAG — decide first, then retrieve Give the agent real tools through the ToolHive MCP gateway Add guardrails and memory — refuse hard, remember long-term Know when a declarative agent is enough vs when to reach for a framework
M6·02

1 · From a docs assistant to an agent

M6·03

Naive RAG is passive, it always retrieves

Every question takes the same road.

"Restart payments?" ops question "What is 2+2?" trivia — no runbook needed embed → retrieve → generate answer same path for both — wasted embed + search on 2+2
M6·04

2 · The analogy: a job description and a rulebook

M6·05

Onboard an engineer, don't script a robot

You hand a new hire three documents, not a flowchart.

Job desc Rulebook Skill guides who they are, how they speak = SOUL.md when to look up, what's off-limits = AGENTS.md step-by-step procedures = SKILL.md model = engineer
M6·06

Declarative Markdown vs a hand-coded robot

Edit a Markdown file, don't touch the code.

Hand-coded robot if-tree of conditions prompts baked into strings explicit tool-call chains fragile · opaque edit tone = touch code declare instead Declarative agent behavior written in Markdown persona + rules + skills tools from standard MCP legible · adjustable edit tone = edit a file
M6·07

3 · The three files that define Aria

M6·08

The anatomy of a 2026 agent

Five parts, one thin glue script.

SOUL.md — identity & voice AGENTS.md — instructions SKILL.md — agentic-RAG MCP — real tools Guardrails — hard rules agent.py ~130 lines glue Aria runs
M6·09

4 · Agentic RAG versus naive RAG

M6·10

Agentic RAG, decide first, then act

Does this need the runbooks? Decide first.

Question Guardrail check blocked → hard refusal Route: YES needs runbooks Route: NO answer directly Retrieve + ground Answer
M6·11

A 2B model can route reliably

Two classes, temperature 0, simple for a small model.

QUERY ROUTE "How do I restart the payments service?" "Where are database backups stored?" "What is 2+2?" "What is the weather in Paris today?" YES — retrieve YES — retrieve NO — direct NO — direct
M6·12

5 · MCP tools via ToolHive

M6·13

Real tools through an MCP gateway

ToolHive is the hub, each server its own spoke.

ToolHive virtual MCP web.fetch GitHub filesystem HTTP database
M6·14

Each tool server in its own sandbox

thv run fetch starts proxy and DNS containers too.

ToolHive-managed isolation fetch server gofetch ingress egress DNS public internet reachable ✕ cannot touch host filesystem or other containers
M6·15

Stateless MCP: every request stands alone

MCP 2026-07-28 drops the session ID and the handshake.

Before: a session to remember client server remembers 1 · initialize handshake Mcp-Session-Id: abc 2 · call + Mcp-Session-Id 3 · call + Mcp-Session-Id gateway must pin you to one replica Now: every request stands alone client replica 1 replica 2 replica 3 call + _meta call + _meta call + _meta _meta = protocol version + capabilities ToolHive: any replica answers, nothing to pin
M6·16

Analogy — a ticket counter, not a tab

Bring the whole ticket and any clerk can serve you.

Running tab your tab only this clerk remembers you Ticket counter clerk clerk clerk ticket ticket ticket each ticket says who, what and which version = _meta
M6·17

6 · Guardrails

M6·18

Guardrails refuse before the model runs

A hard regex gate, not a soft prompt plea.

"reveal the password" unsafe "restart payments" safe regex guardrail ✕ refused LLM never called → to the model route → answer
M6·19

7 · Memory

M6·20

Memory, a librarian who shelves by meaning

Aria's memory, reused unchanged from Module 5.

query (route = YES) ChromaDB · acme_runbooks (5 chunks) restart · scaling backups · restore on-call escalation deploy · rollback embed grounded answer
M6·21

8 · Declarative versus framework

M6·22

When a declarative agent is enough

All three hold → Markdown. One breaks → a framework.

Declarative is enough ✓ one agent, one use case, clear rules ✓ single-step skills ✓ standard MCP tools, no stateful chains Reach for a framework multiple specialised agents shared state across agents complex tool chains retries across agent boundaries one breaks Aria passes all three Module 7: grow Aria into a crew of four
M6·23

The whole agent ships in a container

Markdown, skills, and MCP config in one image.

agent container SOUL.md AGENTS.md SKILL.md MCP config agent.py glue Ollama — NATIVE host.docker.internal:11434 ChromaDB semantic memory ToolHive MCP gateway
M6·24

TO THE LAB

The agent IS Markdown + skills + tools

Read the three files, run Aria, wire in a tool.

SOUL · AGENTS · SKILL Aria routes → ops question — retrieve & ground → "2+2" — answer directly → credential ask — refuse hard

Next: Module 6 Lab, then M7 — the crew.  ·  Gourav Shah · School of DevOps & AI

M6·25