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 1.5B 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?" YES — retrieve YES — retrieve 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

6 · Guardrails

M6·16

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·17

7 · Memory

M6·18

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·19

8 · Declarative versus framework

M6·20

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·21

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·22