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

By the end of this module — you can 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

The agent IS Markdown + skills + tools — minimal glue, shipped inside a container.

M6·02

Naive RAG is passive — it always retrieves

Module 5's pipeline has no judgment: 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

Naive RAG can't decide, can't route, can't use tools — it only ever retrieves-then-generates.

M6·03

Onboard an engineer — don't script a robot

You don't hand a new hire a flowchart. You hand them three documents.

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

Write the three documents as Markdown; the model reads them and becomes the engineer.

M6·04

The anatomy of a 2026 agent

Five labelled parts — persona, instructions, skill, tools, guardrails — plus minimal glue.

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

No framework, no class hierarchy — just Markdown read at startup and stitched into the system prompt.

M6·05

Declarative Markdown vs a hand-coded robot

Changing Aria's tone or adding a guardrail is an edit — not a code change.

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

Declarative vs framework is decided up front — one agent + clear rules stays Markdown; frameworks wait for M7.

M6·06

Agentic RAG — decide first, then act

The agent routes each question before retrieving: does this need Acme's runbooks?

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

Routing at temperature 0 is deterministic — whether, what, multi-hop, self-correct — before any embedding call.

M6·07

A 1.5B model can route reliably

Two classes, temperature 0 — the decision is simple, so a laptop model nails it.

QUERY ROUTE "How do I restart the payments service?" "Where are database backups stored?" "What is 2+2?" YES — retrieve YES — retrieve NO — direct

Route deterministically at temp 0; generate the nuanced answer at higher temp, grounded in evidence.

M6·08

Real tools through an MCP gateway

ToolHive at the hub; each MCP server an isolated container on a spoke.

ToolHive virtual MCP web.fetch GitHub filesystem HTTP database

Per-request Cedar policy, per-server network isolation, no local creds — the agent points at one endpoint URL.

M6·09

Each tool server in its own sandbox

thv run fetch — ToolHive wraps the server in proxy + DNS containers.

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

You never install a tool server on your laptop — IDE mode for dev, stack mode for headless compose runs.

M6·10

Guardrails — refuse before the model runs

A hard regex gate in application code, not a soft plea in the system prompt.

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

A clever prompt can't bypass a gate that fires before any text reaches the model — plus memory: short & long term.

M6·11

Memory — a librarian who shelves by meaning

ChromaDB is Aria's long-term semantic 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

Same HTTP API, same collection — scales from five chunks to millions of vectors unchanged.

M6·12

The whole agent ships in a container

Markdown + skills + MCP config bundled — portable, reproducible, 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

Build the image once; the same agent runs identically on any laptop, CI, or headless compose stack.

M6·13

TO THE LAB

The agent IS Markdown + skills + tools

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

Read the three files that are Aria, start ChromaDB + the agent, then wire in a live MCP tool.

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

M6·14