agentic-workflows-masterclass MCP server

Production-Grade Agentic Workflows & Multi-Agent Orchestration

While prototyping basic LLM workflows is straightforward, scaling autonomous systems to production introduces complex software engineering constraints:

1. Context Expansion & Latency: Compounding token histories increase inference costs and latency.
2. State & Concurrency Control: Complex, cyclic workflows require structured state validation and session synchronization to prevent state corruption or infinite execution loops.
3. Execution Safety: Dynamic, agent-initiated tool execution demands containerized compute environments to protect underlying systems.
4. Telemetry & Tracing: Non-deterministic agent trajectories require standardized execution traces for performance inspection and debugging.

This repository provides reference architectures, implementation labs, and capstones for building stateful, multi-agent systems, focusing on runtime optimization, state persistence, and systematic evaluation.

---

Table of Contents

• The Production Agent Gap
• Architectural Paradigm Matrix
• Prerequisites & Environment Setup
• EU AI Act Technical Documentation (Annex IV)
• Architecture Decision Records (ADRs)
• Curriculum Syllabus
  • Theory: Chapters
  • Practice: Labs
  • Production Recipes
  • Mastery: Capstone Projects
• Enterprise Tooling Stack
• Contributing
• License

---

The Production Agent Gap

Modern AI engineering requires a transition from stateless prompting to stateful cyclic workflows and specialized multi-agent teams.

graph LR
    A["Stateless Prompting<br/>(Zero Context/Tools)"] -->|"Add Search Context"| B["Static RAG<br/>(One-Shot Search)"]
    B -->|"Add Planning Loop"| C["Autonomous Agent (ReAct)<br/>(Dynamic Tool Reasoning)"]
    C -->|"Decouple Concerns"| D["Multi-Agent Orchestration<br/>(Specialized Pipelines)"]

By adding a stateful planning loop, persistent memory checkpointers, and isolated worker boundaries, we upgrade fragile chains into resilient systems that can self-reflect, plan, and gracefully recover from execution errors.

---

Architectural Paradigm Matrix

Paradigm	Primary Limitation	State Scope	Concurrency Safety	Cost Profile	Production Reliability
Stateless Prompting	Lacks iteration, cannot correct intermediate logic errors.	None (Stateless)	N/A (Atomic)	Low (Fixed)	High (But limited capability)
Static RAG	Passive lookup; fails if search terms are suboptimal.	Single Query	N/A	Low-Medium	Medium-Low (Prone to retrieval noise)
Autonomous Agent (ReAct)	Attention degradation, tool hallucination, infinite loops.	Local Loop	Low (Requires session locks)	High (Compounding prefill tokens)	Low (Hard to predict/assert)
Multi-Agent Systems	High coordination latency, complex state merges.	Decoupled / Shared Graph	High (Via isolated actor queues)	Optimized (Via cached context & small scopes)	High (Deterministic boundaries & isolated fallbacks)

---

Prerequisites & Environment Setup

To run the labs and capstone projects, your development environment must satisfy:

• Python 3.13+ (leveraging modern typing and async primitives)
• Docker Desktop (required for sandbox execution labs and project containment)
• LLM Provider API Keys: Google Gemini (via GEMINI_API_KEY), Anthropic (via ANTHROPIC_API_KEY), OpenAI (via OPENAI_API_KEY)

Quick Start

# 1. Clone the repository
git clone https://github.com/FirdowsRahaman/agentic-workflows-masterclass.git
cd agentic-workflows-masterclass


# 2. Establish python environment
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt

# 3. Initialize verification run (Vanilla ReAct Loop)
cd labs/lab-01-vanilla-react
python agent.py

---

Course Curriculum

This repository follows a theory-first, implementation-focused learning path.

Theory: Chapters

Deep dive into architectural patterns, mathematical mechanics, and engineering design.

• Level 1: Foundations of Agentic Reasoning
  • Chapter 1: Defining the Agent Paradigm — Autonomy boundaries, agentic loops, and context constraints.
  • Chapter 2: Moving Beyond Static RAG — Resolving retrieval failure modes via active retrieval loops.
  • Chapter 3: Cognitive Design Patterns — Plan-and-Execute, ReAct, and Self-Reflection frameworks.
  • Chapter 4: Tool Use & Stateless Core — Structured tool output, timeout handles, and error recovery loops.
• Level 2: Advanced Orchestration Frameworks
  • Chapter 5: Stateful Agent Workflows — Cyclic state graphs, node transitions, and thread checkpointers.
  • Chapter 6: Multi-Agent Collaboration Patterns — Supervisor routing, peer-to-peer choreography, and state boundaries.
  • Chapter 7: Human-in-the-Loop (HITL) — Interrupt conditions, manual state overrides, and time-travel debugging.
  • Chapter 8: Persistent Memory & Context Management — Episodic vs. semantic memory, associative indexing, and GraphRAG.
• Level 3: Enterprise-Grade AgentOps
  • Chapter 9: Agent Guardrails & Security — Prompt injection defense, PII scrubbing, and sandboxed execution rules.
  • Chapter 10: Observability & Tracing — Telemetry tracing, span collection, and path auditing (Phoenix/LangSmith).
  • Chapter 11: Evaluation Pipelines — LLM-as-a-judge patterns, golden evaluation datasets, and deterministic assertions.
  • Chapter 12: Production Deployment & Serving — Server-Sent Events (SSE), distributed session locking with Redis, and message queues.
  • Chapter 13: Context Caching & KV-Cache Optimization — KV attention math, prefix matching constraints, and token billing economics.
  • Chapter 14: The Future of Agents — Vision/voice loops, local runtimes (Ollama/SLMs), and desktop-automation environments.

Practice: Labs

Implement core components from scratch to master the low-level mechanics.

• The Vanilla ReAct Loop — Implement a complete planning, tool execution, and self-reflection loop in pure Python without framework wrappers.
• Stateful LangGraph — Design cyclic state graphs with node updates, state mergers, and thread-level state restoration.
• Supervisor Team — Implement a supervisor router that coordinates task delegation, output aggregation, and worker control loops.
• Human Interruption — Pause state graphs before high-risk operations to allow manual validation and state modifications.
• Dual-Core Memory Engine — Build a memory manager coordinating short-term conversational threads alongside long-term semantic embeddings in SQLite.
• Evals Pipeline — Configure automated evaluation suites that run test assertions and compute similarity/completeness scores via LLM judges.
• Corrective RAG (CRAG) Engine — Build an advanced RAG pipeline with document grading, query expansion, and web search fallback routes.
• Collaborative Agents with Google ADK — Orchestrate sequential collaborative workflows using Google's Agent Development Kit, exposing custom tools and native MCP server interfaces.
• Sovereign European Agent with Mistral AI & vLLM — Build a GDPR-compliant autonomous agent using Mistral Large / Codestral with private vLLM sovereign inference and zero data egress.

Production Recipes

End-to-end performance and infrastructure patterns combining state-of-the-art tools.

• Weaviate + Polars + Claude Context Caching — High-throughput columnar preprocessing (Polars Arrow SIMD), isolated vector memory (Weaviate v4 hybrid search), and 90% cost-reduced Claude prompt context caching, deployed via AWS CloudFormation in eu-central-1 (Frankfurt) or GCP Cloud Run in europe-west4 (Netherlands).

Mastery: Capstone Projects

Deploy production-ready solutions modeled after enterprise workloads.

• Autonomous Sandbox Dev Team: Build PM, Coder, and QA Tester agents that collaborate, write python scripts, and run automated unit tests inside secure, isolated Docker sandboxes.
• Clinical Support Agent with HITL: Deploy a clinical triage assistant with clinical guidelines RAG, safety policy guardrails, and human escalation checkpoints.
• Collaborative Market Research Engine: Build a multi-agent data aggregator, research compiler, and Neo4j GraphRAG explorer that builds structured reports from unstructured documents.
• Compliance & Risk Auditor: Architect a regulatory compliance engine that audits PDF financial files, validates outputs against strict Pydantic schemas, and triggers safety filters via Guardrails AI.

---

Enterprise Tooling Stack

• Agent Development Kit (ADK): Google's open-source framework for building multi-agent systems and workflows.
• LangGraph: Stateful orchestration library of choice for complex state management.
• Weaviate: Enterprise-grade open-source vector database supporting hybrid search and multi-tenancy.
• Polars: Lightning-fast DataFrame library written in Rust for parallel SIMD data preparation.
• Anthropic Claude: State-of-the-art frontier model with ephemeral prompt context caching.
• GenAI SDK: Official library for Google Gemini models.
• Phoenix: AI observability and tracing platform.

---

Contributing

We welcome contributions!

1. Fork the repo and create your feature branch (git checkout -b feature/AmazingFeature).
2. Commit your changes (git commit -m 'Add some AmazingFeature').
3. Push to the branch (git push origin feature/AmazingFeature).
4. Open a Pull Request.

---

License

Distributed under the MIT License. See LICENSE for details.

---