DEV Community: zkaria gamal

How I Built a Zero-Shared-State Auth Middleware for a Real-Time Voice AI Agent (WebRTC + FastMCP + Whisper)

zkaria gamal — Mon, 25 May 2026 19:17:58 +0000

I've been building an open-source real-time voice AI workspace for the past few weeks and I want to walk through the architecture decisions that were actually hard — not the happy-path stuff you see in tutorials.

The stack: React client → WebRTC Python backend → FastMCP server (Whisper STT, Mail, Calendar) → transcript delivered back over a WebRTC DataChannel. The LLM orchestration layer is still in progress, but the pipeline underneath it is fully live and tested.

Here's what I want to focus on: three engineering decisions that weren't obvious.

The Problem With Securing Local Microservices

When two services run on the same machine — in this case the WebRTC server and the MCP server — the standard advice is to put them behind a shared secret or an API key stored in an environment variable. That works, but it has failure modes: leaked .env files, rotation pain, and the cognitive overhead of managing secrets across services that should be able to trust each other without a database call.

I wanted something stateless and self-expiring.

The solution I landed on is a time-locked hash generator. Both servers independently compute the same key by applying deterministic math to the current UTC timestamp divided by a 5-second epoch window:

import math, hashlib, time

def generate_api_key() -> str:
    epoch_window = int(time.time()) // 5
    raw = math.sqrt(math.log10(epoch_window))
    return hashlib.sha256(str(raw).encode()).hexdigest()

The Starlette middleware on the MCP server recomputes this hash on every incoming request and compares it to the header. If the timestamp window is off by more than one epoch — five seconds — the request is rejected. No database lookup. No token storage. No rotation script. The key rotates itself every five seconds and both sides always agree on what it should be.

This is not production-grade for internet-facing services (TOTP with a proper shared seed is better for that), but for securing local inter-service communication during development and staging it is clean, auditable, and has zero ops overhead.

**The Dual-Rate Audio Pipeline**

WebRTC gives you audio at 48kHz. Whisper is happiest at 16kHz. `webrtcvad` only accepts 8, 16, or 32kHz. Feeding everything through one sample rate loses either fidelity for transcription or compatibility for VAD.

The backend handles both independently in the same 30ms processing loop:

- The full 48kHz PCM buffer accumulates separately for Whisper
- A parallel downsampled 16kHz frame array feeds `webrtcvad` at aggressiveness level 3
- A sliding window tracks the ratio of active to silent frames
- When fewer than 1 in 10 frames in the last 2.0 seconds are active — that's the boundary

python
SILENCE_RATIO_THRESHOLD = 0.1
SILENCE_DURATION_SECONDS = 2.0

active_frames = sum(vad_window)
total_frames = len(vad_window)
if active_frames / total_frames < SILENCE_RATIO_THRESHOLD:
trigger_pipeline()

Splitting the buffers means you get high-quality STT input and accurate VAD detection without either compromising the other.

Service Singletons and the Cold Start Problem

Whisper is not fast to load. If you initialize the model on the first request, your first transcription takes 3–6 seconds depending on hardware. Every user who speaks first gets a broken experience.

The fix is a LoadModelService singleton that runs at server startup:

class LoadModelService:
    _model = None

    @classmethod
    def get_model(cls):
        if cls._model is None:
            cls._model = whisper.load_model("small")
        return cls._model

This gets called inside the FastMCP lifespan hook, so by the time the first WebSocket connection arrives the model is already in memory. Every subsequent transcription call hits a warm model.

The same pattern applies to the mail and calendar services — singletons initialized once, reused across tool calls, with a token-bucket rate limiter (0.5 req/s for Gmail) sitting in front of anything that touches an external API.

**The Pytest Suite**

You can't calibrate a VAD pipeline without tests. The suite covers:

- Frame decimation accuracy at different sample rates
- Speech onset boundary detection under various silence patterns
- SMTP integration with mock SMTP server
- Calendar tool with automatic `.ics` fallback when no calendar service is configured

[ RUN ] test_frame_decimation_48k_to_16k
[ OK ] test_frame_decimation_48k_to_16k
[ RUN ] test_vad_silence_boundary_2s
[ OK ] test_vad_silence_boundary_2s
[ RUN ] test_smtp_send_integration
[ OK ] test_smtp_send_integration




Running `pytest tests/ -v` from the `mcp/` directory gives you live output with real pass/fail visibility — not just a summary at the end.

**What's Next**

The LLM orchestration and conversation routing layer is actively in development. Once that's in, the full loop closes: speech → STT → LLM agent → tool use → response.

The entire codebase is open source and structured as an educational reference for WebRTC, MCP, and secure microservices. If you're building anything in this space — voice agents, real-time audio pipelines, MCP tool servers — I'd love contributions, issues, or just a look.


![Stt Flow](https://dev-to-uploads.s3.amazonaws.com/uploads/articles/dapxxg3ypbj526ci35oh.jpeg)

GitHub: https://github.com/zkzkGamal/AI-RTC-Agent

I built a fully tested Agentic AI system with LangGraph + MCP and open-sourced the whole thing

zkaria gamal — Mon, 18 May 2026 10:24:32 +0000

Most LLM tutorials stop at "here's how to call the OpenAI API."

Mine doesn't.

I just shipped v1.1.0 of Agentic AI Tutorial — a 5-chapter open-source repo that takes you from your first raw API call all the way to a production-style multi-node autonomous agent with a CI pipeline, pytest suite, and MCP server integration.

Here's what's inside and why I built it the way I did.

🏗️ The Architecture (Chapter 5)

The final agent uses a LangGraph StateGraph with 4 decoupled nodes:

Router — classifies user intent with a cheap, fast LLM call
Execute — runs a LangChain ReAct agent bound to a local FastMCP server
Summarize — converts raw tool JSON into natural language
Conversation — handles chitchat directly, skipping tool execution entirely

The MCP server exposes math and email tools over SSE. The agent never touches your credentials directly — it talks to the server, which acts as a secure boundary.

🧪 Why I Added Tests to an AI Project

Here's the uncomfortable truth about agentic systems: they don't fail loudly. They drift.

Change one node prompt, and suddenly the router misclassifies 20% of requests. No exception thrown. No stack trace. Just wrong output that you may not catch until a user reports it.

So v1.1.0 ships with:

A pytest suite that validates each node's logic and MCP tool contracts independently — no live API calls needed
A GitHub Actions CI workflow that runs on every push across multiple Python versions
A custom conftest.py reporter that gives real-time output with zero buffering lag

pytest Chapter5/SimpleChatAgent/ -v

📚 Full Roadmap (All 5 Chapters)

Chapter	Focus
1	LLM fundamentals — OpenAI, Gemini, Ollama, streaming
2	LangChain, LCEL, chains, tool binding
3	Memory, entity tracking, RAG with Chroma/FAISS
4	LangGraph agents — ReAct, Router, Multi-Agent, Human-in-the-Loop
5	Multi-node agent + FastMCP Server + CI/pytest

🚀 Get Started in 3 Commands

git clone https://github.com/zkzkGamal/Agentic-AI-Tutorial.git
cd Agentic-AI-Tutorial
pip install -r requirements.txt

Each chapter has its own .env.example. Ollama users can run everything 100% locally, no API keys needed.

If this saves you time or teaches you something new, a ⭐ on the repo helps others find it.

👉 github.com/zkzkGamal/Agentic-AI-Tutorial

Happy to answer questions in the comments — what agentic patterns are you building?

Building Strong ML Foundations: Chapter 2 - Classification is Now Live

zkaria gamal — Sun, 10 May 2026 08:58:15 +0000

A few weeks ago I published Chapter 1 of my hands-on AI tutorial series, focused on Regression. Today, I'm excited to share that Chapter 2: Classification is complete.

This series isn't just another collection of notebook tutorials. I'm building it to truly understand how these algorithms work under the hood — implementing them from scratch where it makes sense, comparing them properly, and focusing on concepts that actually matter in interviews and real projects.

What’s in Chapter 2

I implemented and analyzed five core classification algorithms:

Logistic Regression (implemented from scratch with NumPy, plus scikit-learn version)
K-Nearest Neighbors (KNN) Classifier
Random Forest Classifier
XGBoost Classifier
Support Vector Classifier (SVC) with different kernels

Key Focus Areas

This chapter goes deeper than just training models. I spent a lot of time on:

Visualizing decision boundaries for each algorithm
Understanding probability estimates and calibration
Bias-variance tradeoff in classification problems
Precision vs Recall — one of the most important topics for ML interviews. I dedicated a good portion explaining when to optimize for precision, when to prioritize recall, and how to use F1-score effectively depending on the problem.
Confusion matrices, ROC-AUC, and proper model evaluation
Why ensemble methods (Random Forest and XGBoost) consistently outperform single models

Everything is implemented cleanly using NumPy, scikit-learn, and XGBoost, with real datasets and detailed explanations.

You can check out the full chapter here:

→ https://github.com/zkzkGamal/hands-on-ai-tutorial/tree/main/ml_fundamentals/chapter2

Chapter 1 (Regression) is available in the same repository.

Why I’m Doing This Publicly

I got tired of only knowing how to call model.fit() without understanding what was happening inside. This project is my way of forcing myself to learn deeply while creating a resource that can help others who want the same.

If you're a developer transitioning into ML, preparing for machine learning interviews, or simply want stronger fundamentals, I believe this series can be useful.

What's Next?

I'm planning Chapter 3 soon. I'm thinking about Dimensionality Reduction (PCA, t-SNE, UMAP) or Advanced Model Evaluation & Hyperparameter Tuning. Let me know in the comments what you'd like to see next.

Feedback is always welcome — whether it's about the code, explanations, or structure.

Happy to connect if you're on a similar learning journey.

I Built My Own Hands-on AI Tutorial – Chapter 1: Regression (From Scratch + XGBoost)

zkaria gamal — Tue, 05 May 2026 13:41:41 +0000

A few weeks ago, I revisited my old AI/ML projects.

As I looked through the code, I felt something was missing. I was using models like RandomForestRegressor and XGBRegressor, getting decent results… but I didn’t feel I truly understood what was happening under the hood.

So I made a decision:

Instead of consuming more tutorials, I would build my own comprehensive Hands-on AI Tutorial — first for myself, and then for the community.

Today, I’m happy to announce that Chapter 1: Regression is complete! 🎉

What’s Inside Chapter 1

I implemented and compared 5 different regression techniques on real-world datasets:

Linear Regression — Implemented from scratch using the Normal Equation (NumPy only)
Decision Tree Regression
Random Forest Regression
XGBoost Regression — This one consistently delivered impressive performance
Support Vector Regression (SVR) with linear, RBF, and polynomial kernels

For every algorithm, I did the following:

Built a from-scratch version (where applicable)
Compared it with the industry library version (scikit-learn / XGBoost)
Explained the math intuitively
Ran experiments on multiple datasets (House Prices, Life Expectancy, Advertising, Student Performance, etc.)
Evaluated using MSE, RMSE, R², and residual plots
Generated visualizations and saved models

Key Learnings

Why simple Linear Regression is still a powerful baseline
How Decision Trees can overfit and why ensembles (Random Forest & XGBoost) fix many of those issues
The real power of boosting vs bagging
The importance of hyperparameter tuning and model evaluation
How kernels work in SVR

The most satisfying moment was watching XGBoost and Random Forest outperform everything else — and finally understanding why that happens.

Project Structure (Clean & Practical)

ml_fundamentals/chapter1/
├── notebooks/          # Interactive Jupyter Notebook
├── src/                # From-scratch implementations
├── docs/               # Deep math explanations
├── configs/            # Easy-to-modify YAML configs
├── data/               # Real datasets
├── results/            # Plots + reports
└── models/             # Saved models

Who Is This For?

Beginners who know Python and want to start ML properly
Juniors who want to move from “copy-paste” to deep understanding
Anyone who wants both theory and practical code in one place

Try It Yourself

Repository:

https://github.com/zkzkGamal/hands-on-ai-tutorial

Just clone, install the dependencies, and start with the Chapter 1 notebook.

git clone https://github.com/zkzkGamal/hands-on-ai-tutorial.git
cd hands-on-ai-tutorial
pip install -r requirements.txt

I’m already working on Chapter 2: Classification.

I Spent 4 Hours Fixing Broken Imports – So I Built a Complete Agentic AI Tutorial

zkaria gamal — Mon, 06 Apr 2026 08:06:23 +0000

*A true story from last month: *

I was building an intelligent agent using LangGraph + MCP, and I asked Claude for the latest code to implement a Multi-Node Agent.

It gave me a clean-looking code. I copied it, ran it… Import error.

I went to GPT-4o. Different code, but still outdated imports.

Tried Gemini. Same problem.

I lost over 4 hours tweaking imports, updating StateGraph, digging through LangChain's changelog… until I hit complete frustration.

That's when I said: Enough.

I decided to do something completely different.

I started collecting only the modern code that actually works in 2026, tested it myself, fixed what was broken, and organized everything in one place.

The result?

🔥 Agentic AI Tutorial

A complete, up-to-date reference for building Agentic AI using the latest versions of LangChain + LangGraph + MCP.

Why I built this repo

To end the daily struggle of "outdated/copied-pasted-broken code"
To help you build powerful agents without wasting hours on debugging
To give you one trusted, updated reference where everything actually runs

What's inside?

Chapter	Content
1	LLM basics + Streaming + Advanced Prompts
2	LangChain LCEL + Tools + Chains
3	Advanced Memory + Full RAG (Chroma & FAISS)
4	Advanced LangGraph (ReAct, Router, Multi-Agent, Self-Refine, Human-in-the-Loop)
5	Complete MCP + FastMCP Server + Multi-Node Agent System (Router → Execution → Summary)

Everything is available as Jupyter Notebooks + Python files, ready to run.

Works locally (Ollama) and cloud (GPT-4o, Gemini).

A question for you:

Are you already at Chapter 5, or still at the beginning?

Drop a comment below 👇

AgenticAI#LangChain#LangGraph#MCP#Python#LLM#GenerativeAI#Opensource

Building Production-Ready Agentic AI: From Tutorial to High-Performance Serving (vLLM vs SGLang Benchmark)

zkaria gamal — Sun, 29 Mar 2026 11:14:24 +0000

Building Production-Ready Agentic AI: From Tutorial to Real-World Serving Benchmark

Hey devs 👋

If you’ve been building ReAct agents with LangGraph, you’ve probably faced the same question I did:

“I can build a cool agent in a tutorial… but which serving engine should I actually use in production?”

That’s why I connected my two repositories:

Agentic-AI-Tutorial → Learn how to build a full ReAct agent from scratch
concurrent-llm-serving → Benchmark vLLM vs SGLang under heavy agent load

Now the two repos are linked: the exact same agent from the tutorial is included as simpleagent/ inside the benchmark repo.

What’s Inside the Agentic AI Tutorial

You start with a clean, production-style LangGraph ReAct Agent that has three nodes:

Conversation – Handles multi-turn dialogue
Act – Calls real tools (DuckDuckGo Search + Calculator)
Summarize – Processes long document context (10k+ tokens)

Everything is explained step-by-step:

Tool calling
Structured outputs
Memory management
Error handling

Repo → https://github.com/zkzkGamal/Agentic-AI-Tutorial

The Missing Piece: Which Engine Should You Serve It With?

Tutorials usually stop at “run it locally.”

I wanted to go further.

So I took the exact same agent and stress-tested it under 3 concurrent sessions (5 turns each, up to ~25,000 tokens total context) using:

Model: Qwen3.5-0.8B (single GPU)
Engines: vLLM vs SGLang

Full benchmark report is here:

README_agent_benchmark.md

High-Level Results

|-------------------------------|---------------|----------------|-------------|

| Total Wall Time (3 sessions) | 229.8s | 255.8s | vLLM (-11%) |

| Context Limit Errors | 0 | 2 | vLLM |

| Successful Sessions | 3/3 | 3/3 | Tie |

Node-Level Breakdown (this is where it gets interesting)

Act Node (Tool Calling) → SGLang wins by 71%

Thanks to RadixAttention prefix caching — perfect for repeated tool calls.

Summarize Node (Long Context) → vLLM wins

Much more stable when context balloons to 10k+ tokens.

Verdict:

Use SGLang if your agents do a lot of tool calling in loops.
Use vLLM if your agents handle heavy RAG or summarization workloads.

How to Use Both Repos Together (The Full Flow)

Clone the tutorial and build your agent


   git clone https://github.com/zkzkGamal/Agentic-AI-Tutorial.git

   cd Agentic-AI-Tutorial

Move to the serving benchmark repo (now includes simpleagent/)


   git clone https://github.com/zkzkGamal/concurrent-llm-serving.git

   cd concurrent-llm-serving/simpleagent

Run the exact same agent with either engine using the provided launch scripts.

Everything is documented — you can literally go from learning the agent pattern to benchmarking production serving in minutes.

Why This Matters

Most agent tutorials leave you with a notebook.

This project gives you the complete pipeline:

Build the agent ✅
Understand the serving trade-offs ✅
Choose the right engine for your workload ✅
Deploy it at scale ✅

Try It Yourself

Tutorial repo: Agentic-AI-Tutorial
Benchmark repo (with integrated simpleagent): concurrent-llm-serving

Would love to hear from you:

What serving engine are you using for your agents today?
Have you noticed the same trade-offs between vLLM and SGLang?
Want me to add more models / workloads / frameworks (CrewAI, AutoGen, etc.)?

Drop your thoughts below 👇

Happy building!

— zkzkGamal

Concurrent LLM Serving: Benchmarking vLLM vs SGLang vs Ollama

zkaria gamal — Mon, 16 Mar 2026 08:47:59 +0000

I wanted to know exactly how the three most popular open-source LLM serving engines perform when real users hit your server at the same time. So I built this educational repo and ran identical tests on a single GPU.

Repo: https://github.com/zkzkGamal/concurrent-llm-serving

Model: Qwen/Qwen3.5-0.8B

Hardware: Single GPU

Concurrency: 16 simultaneous requests (only 4 for Ollama)

Task: Diverse AI & programming questions (max_tokens=150)

The Results (spoiler: one engine destroys the others)

|----------|----------|------------|-----------------------|----------------------------|

| SGLang | 16 | 2.47s | 0.68–2.46s | True parallel batching + RadixAttention |

| vLLM | 16 | 11.26s | ~10.25–11.26s | PagedAttention + continuous batching |

| Ollama | 4 | 134.72s| 26–134s | Sequential (time-sliced) |

SGLang was 4.6× faster than vLLM and completely smoked Ollama.

Why the huge difference? The Core Algorithms

1. KV-Cache & Memory Management

Every LLM needs to store Key/Value vectors for previous tokens. Without smart caching, you waste VRAM and kill concurrency.

vLLM → PagedAttention (treats KV cache like OS virtual memory pages → no fragmentation)
SGLang → RadixAttention (trie-based prefix tree → shares any common prefix across requests automatically)

2. Continuous Batching

Instead of waiting for a full batch, new requests join the GPU forward pass instantly. Both vLLM and SGLang do this. Ollama does not.

3. Other Tricks

SGLang: Chunked prefill + custom Triton kernels + zero warm-up
vLLM: Broad model support + CUDA graph warm-up
Ollama: GGUF quantization + llama.cpp (great for single-user, terrible for concurrency)

When Should You Use Each Engine?

SGLang → Maximum throughput, structured JSON/regex output, production serving
vLLM → Stability, 50+ model architectures, when you need reliability over raw speed
Ollama → Quick prototyping, local development, zero-config experience

How to Reproduce the Tests Yourself

The repo includes everything:

install.sh (one-click setup)
sglang_concurrent_test.py / vllm_concurrent_test.py / ollama_concurrent_test.py
Raw logs + result markdowns
Video demos (test_sglang.mkv, ollama_test.mkv)

Just clone and run:


git clone https://github.com/zkzkGamal/concurrent-llm-serving

cd concurrent-llm-serving

bash install.sh

(Full startup commands and API compatibility notes are in the README.)

Project Structure


├── sglang_concurrent_test.py     # 16 concurrent requests

├── vllm_concurrent_test.py

├── ollama_concurrent_test.py

├── install.sh

├── *_results.md                  # Formatted benchmark outputs

└── README.md                     # Full deep-dive guide

Final Thoughts

Concurrent serving is no longer optional — it's table stakes for any serious LLM application. The difference between "works on my machine" and "handles 16 users at once" is huge, and the right engine choice can save you GPUs (and money).

If you're building anything with local LLMs — agents, RAG, chat apps, etc. — I highly recommend trying SGLang first.

⭐ Star the repo if you found it useful!

Feedback, PRs, and questions are all welcome.

What engine are you using right now? Have you hit concurrency limits yet? Drop a comment below 👇

llm #vllm #sglang #ollama #aiserving #machinelearning #opensource #gpu #inference

Building a Production-Ready Agentic AI System with LangGraph and MCP

zkaria gamal — Tue, 10 Mar 2026 12:57:31 +0000

As AI engineers, we often start by giving a massive LLM (like GPT-4) a giant prompt and a long list of Python functions (tools) it can call. This monolithic approach works for simple scripts, but it quickly becomes expensive, slow, and a security risk when the LLM has direct access to sensitive resources like email passwords or file systems.

To move beyond prototypes, we need to separate the "thinking" from the "doing." In this chapter of my open‑source tutorial, we rebuild an agentic assistant using two powerful technologies:

LangGraph – for routing logic across specialized nodes.
Model Context Protocol (MCP) – for secure, decoupled tool execution.

The result is a production‑ready, decoupled AI system that is safer, faster, and more reusable.

👉 GitHub Repository: Agentic-AI-Tutorial

🏗️ Architecture: Brain vs. Hands

Instead of a single monolithic agent, our application consists of two distinct parts communicating over Server‑Sent Events (SSE).

1. The Hands: FastMCP Server

All physical tools (math logic, Python SMTP/IMAP email operations) live in a standalone ASGI server running on port 8000. Using the Model Context Protocol (an open standard), we expose these functions securely.

# McpServer/tools/weather.py
from server import mcp

@mcp.tool()
def get_temperature(city: str) -> str:
    """Get the current temperature for a given city."""
    return f"The weather in {city} is 72°F."

Thanks to MCP, the server automatically reads the docstrings and type hints, generating a standardized JSON schema. Crucially, the LangGraph agent never possesses your passwords nor directly executes this code – it only sends requests via the protocol.

2. The Brain: LangGraph Orchestrator

On the other side, we built a StateGraph with distinct nodes to handle user requests efficiently.

router.py (The Fast Path)

Uses a fast, cheap LLM to classify the user's intent: math, email, or conversation.
execute.py (The Heavy Lifter)

If the router chooses a tool‑based intent, this node takes over. It uses LangChain’s create_tool_calling_agent and dynamically binds to the remote MCP server.
summarize.py (The Formatter)

Takes the raw JSON output from the MCP server and uses an LLM to synthesize a polite, conversational response for the user.
conversation.py (The Chitchat Fallback)

If the user just says “Hello,” we skip all heavy execution. This node feeds the conversation history directly to the LLM, saving tokens and time.

🚀 Why This Matters

Security & Isolation

The MCP server acts as a secure boundary. You can host the LangGraph agent in the cloud while running the MCP server on your local corporate intranet to access private databases – all without exposing credentials.

Reusability

Once you build an MCP server (like our Mail/Math server), you can plug it into any MCP‑compatible client. The same tools work in LangChain, Claude Desktop, Cursor, or your own custom UIs – no rewriting needed.

Run It 100% Offline with Ollama

Don’t want to pay for OpenAI API keys? Standardising with LangChain and MCP makes swapping LLMs trivial. You can run the entire workflow locally and for free using Ollama!

Simply update the agent nodes (e.g., router.py, execute.py) from:

from langchain_openai import ChatOpenAI
llm = ChatOpenAI(model="gpt-3.5-turbo")

to:

from langchain_ollama import ChatOllama
llm = ChatOllama(model="llama3.1", temperature=0)

Because LangChain provides unified interfaces, the node routing and tool calling continue to work seamlessly with your local Llama 3 model.

💻 Try It Yourself!

All code, diagrams, and step‑by‑step instructions are available in Chapter 5 of my open‑source tutorial repository:

👉 GitHub: Agentic-AI-Tutorial

Clone it, spin up the FastMCP server, and watch the LangGraph nodes gracefully orchestrate tool execution!

📸 Demo: From User Request to Delivered Email

Here’s a real example of the agent in action, showing the entire flow from a user asking to send an email to the confirmation that it actually arrived.

1. The User Request & Agent's Execution

In the screenshot below, you can see the user submitting a request: "send email to Gamal saying hello from the agent". The LangGraph router correctly classifies this as an email intent, and the execute node invokes the remote MCP server's email tool. The agent then reports back that the email was sent successfully.

2. Proof of Execution

To verify that the MCP server actually performed the task—and that the agent wasn't just "hallucinating" success—we can check the real destination. The following screenshot shows the actual "Gamal" inbox with the email delivered exactly as requested. This confirms the secure, end-to-end functionality of the decoupled architecture.

This walkthrough visually confirms that the brain (LangGraph agent) correctly interprets the request and delegates to the hands (MCP server), which securely performs the action without exposing any credentials or internal logic to the agent itself.

🧠 What’s Next?

What tools are you planning to build for your MCP servers? Let me know in the comments below – I’d love to hear about your ideas and see what you create!

Follow me for more tutorials on production‑ready AI systems.

I Built a Local AI Agent That Plans Before Executing Linux Commands (Now Fully Dockerized)

zkaria gamal — Tue, 03 Mar 2026 11:05:29 +0000

I Built a Local AI Agent That Plans Before Executing Linux Commands (Now Fully Dockerized)

Most “AI agents” that run shell commands follow a simple flow:

User prompt → LLM → Execute command

That’s powerful.

It’s also dangerous.

So I built ZkzkAgent, a fully local Linux AI assistant that thinks and routes before it acts.

🚨 The Problem with Most Terminal AI Wrappers

A lot of open-source agents do this:

Send user prompt to an LLM
Generate shell command
Execute immediately

There’s:

No routing logic
No conditional branching
No confirmation flow
No safety model

For real system environments, that’s risky.

🧠 What Makes ZkzkAgent Different

ZkzkAgent introduces a structured agent architecture:

User
  ↓
Router Node
  ├── Conversation Node
  ├── Retrieval Node
  └── Tool Execution Node
        ↓
  Confirmation (if needed)
        ↓
  Execution

Instead of blindly executing:

✔ It decides what type of task this is
✔ It branches based on context
✔ It enforces confirmation for dangerous actions
✔ It logs and returns results back into the conversation loop

Built with:

LangGraph (stateful agent flow)
Ollama (local LLM execution)
Explicit tool safety filters

🔐 Safety Design Principles

I designed ZkzkAgent with 5 rules:

No hidden execution
Human confirmation for destructive commands
Deterministic routing
Full local-first architecture
Transparent tool layer

This makes it suitable for:

Developers
Linux power users
Self-hosted environments
AI experimentation

🐳 New: Docker Support

One of the biggest barriers to adoption was setup complexity.

Now ZkzkAgent includes official Docker support.

You can spin it up in a clean, isolated environment without touching your base system.

git clone https://github.com/zkzkGamal/zkzkAgent
cd zkzkAgent
docker build -t zkzkagent .
docker run -it zkzkagent

Reproducible.
Isolated.
Clean.

🎯 Why I Built This

I’m deeply interested in agentic AI systems — not just chatbots.

I wanted to experiment with:

Router-based architectures
Branching decision logic
Human-in-the-loop safety
Local execution models

Instead of building another “AI assistant,” I focused on architecture control.

🔮 What’s Next

Planned improvements:

More granular permission layers
Plugin-style tool system
Sandboxed execution modes
Better observability dashboard

💬 Feedback Welcome

If you’re experimenting with:

AI agents
LangGraph workflows
Local-first LLM systems
OS-level automation

I’d love your thoughts.

Repository:
https://github.com/zkzkGamal/zkzkAgent

I Gave an Open-Source AI Full Access to My Linux Terminal (And Lived to Tell the Tale)

zkaria gamal — Thu, 26 Feb 2026 11:16:55 +0000

The Problem with Cloud AI

We all love ChatGPT and Claude, but there is a fundamental disconnect for developers: they can't actually do things on your machine.

If I want an AI to install a package, troubleshoot my system logs, run a script, or clean up my temporary files, I have to constantly copy-paste commands back and forth.

That felt incredibly outdated for 2026.

So, I decided to build zkzkAgent: a fully autonomous, local AI assistant designed specifically for Linux System Management. No expensive API keys, no data leaving my machine, and full terminal execution capabilities.

Here is how I built it—and how you can build one too.

🚀 Meet zkzkAgent v3

zkzkAgent (now in v3!) is a human-in-the-loop autonomous agent that runs entirely on your local machine using Ollama, LangChain, and LangGraph.

It doesn't just answer questions. It takes action.

Key Features:

🛠️ Autonomous System Management: It can find files, read logs, check running processes, and kill rogue nodes.
📦 Safe Package Management: It features conflict-aware package management, meaning it knows how to install dependencies without breaking your Debian/Ubuntu setup.
🗣️ Voice Interactive: Integrated with Kokoro TTS and Whisper for seamless voice interactions. I built it so we can just talk to our systems.
🛡️ Human-in-the-Loop Security: It can read files and search the web by itself, but for dangerous actions (like rm or installing packages), it strictly requires your explicit confirmation before executing.

🏗️ How It Works (The Architecture)

To make it reliable, I used a Router-Planner-Executor architecture built with LangGraph:

The Router: When you prompt the agent, a sophisticated classification node decides if the request is "Conversational", needs "Direct Execution" (like a simple ping), or requires "Planning" (multi-step complex tasks).
The Planner: For complex tasks, the agent drafts a step-by-step execution plan natively.
The Executor: The agent loops through the plan, sequentially using specific tools (like run_command, check_internet, find_file) one at a time. It observes the output of each command before deciding to proceed.

Because it runs entirely locally, it's fast, free, and completely private. It feels like having a junior sysadmin sitting in your terminal.

🎓 Want to Build Your Own? (Free Tutorial!)

see this post

Learn Agent AI

💬 Let's Discuss

I'm currently working on improving its contextual awareness and adding a sleek web UI.

I'd love to hear your thoughts!
Would you trust an autonomous agent to run commands on your system? What safety checks would you consider absolutely mandatory?

Let me know in the comments below! 👇

If you found this interesting, I'd appreciate a 💖 or 🦄 to help others find it!

Build Autonomous AI Agents Step-by-Step – My Free LangChain + LangGraph Tutorial (2026 Edition)

zkaria gamal — Tue, 24 Feb 2026 13:20:05 +0000

Hey dev community! 👋 **
I'm Zkzk from Cairo, and I've been deep in agentic AI lately. After struggling to find a clear, hands-on path from "hello LLM" to "production-ready autonomous agent," I built my own tutorial repo: **Agentic-AI-Tutorial.

It's a 5-chapter progression (4 complete, Chapter 5 launching soon) with executed Jupyter notebooks, local Ollama support, OpenAI/Gemini options, and a real-world capstone: a Personal Finance Tracker Agent that tracks expenses, analyzes patterns with RAG, and gives smart advice via FastAPI + ChromaDB.

If you're in Cairo or anywhere grinding on AI agents in 2026, this is for you. Let's break it down!

Why Agentic AI Matters Right Now

LLMs are powerful, but they're stateless chatbots without memory or tools.

Agentic AI changes that: agents reason, use tools, remember context, self-refine, and even collaborate.

My tutorial shows you how — practically, reproducibly, and locally-first (privacy + zero cost with Ollama).

Chapter Breakdown: The Journey

Chapter 1: LLM Foundations

Call models from Ollama (local Gemma/Qwen), OpenAI (gpt-4o-mini), Gemini.

Learn streaming, system prompts, token counting.

Notebook highlights:

Simple chat
Emoji-styled responses
Multi-provider switching

Great for beginners testing local vs. cloud.

Chapter 2: LangChain Chains & Tools

Build interactive workflows with LCEL.

Add memory (RunnableWithMessageHistory), bind tools, create routers/parallel chains.

Demo: Stateful chat that remembers your name + routes queries dynamically.

Chapter 3: Memory + RAG Pipelines

Persistent memory types + local embeddings (sentence-transformers).

RAG setup with ChromaDB prep (full vector store coming in Ch5).

Focus: Cost/privacy with everything local.

Chapter 4: LangGraph Orchestration (My Favorite!)

Move from chains to graphs.

Build ReAct agents, multi-agent collab, self-refinement loops.

Notebook magic:

Graph visualization with Graphviz (nodes/edges appear live!)
State updates in real-time
Tool calls (e.g., math/search)
Conditional routing + human-in-the-loop

This chapter feels "alive" — agents actually think!

Chapter 5: Real-World Capstone – Personal Finance Tracker Agent

Tying it all together:

FastAPI backend for API endpoints (/track_expense, /query_budget)
ChromaDB for embedding/storing transactions + finance tips (local RAG)
LangChain chains for parsing/categorizing/calculating
LangGraph for orchestration: Parse → Retrieve → Analyze → Advise (ReAct + refinement)
Stateful memory per user/session

Example flow:
User: "Groceries at Carrefour, 500 EGP"
Agent: Queries patterns → "Your food spending up 20% this month – try these local deals!"

Deploy locally with uvicorn, ready for extensions (Streamlit UI, EGP exchange rates).

Tech Stack (All Reproducible)

Python 3.10+
LangChain, LangGraph
Ollama (local), OpenAI, Google Gemini
ChromaDB + sentence-transformers
FastAPI + uvicorn
.env for keys, venv for isolation

No paid walls — run everything locally!

Quick Start

Clone: git clone https://github.com/zkzkGamal/Agentic-AI-Tutorial
cd into folder → python -m venv venv → activate
pip install -r requirements.txt
Set up .env (API keys if using cloud)
Run notebooks in order (Chapter1 → Chapter5)

What's Next?

Chapter 5 notebook + deployment guide dropping soon.

Planning extensions: Streamlit frontend, more tools (e.g., currency API), multi-user persistence.

Call to Action

If this resonates:

⭐ Star the repo – it really helps!
🍴 Fork & build your own agent (maybe a Cairo event planner next?)
Comment below: What real-world agent would YOU build with these tools?

Repo: https://github.com/zkzkGamal/Agentic-AI-Tutorial

Let's build agentic AI together

AIAgents #LangGraph #LangChain #OpenSource #Python #Tutorial

zkzkAgent v3 – now with safe, conflict-aware package management

zkaria gamal — Sun, 22 Feb 2026 15:54:02 +0000

Managing Linux is powerful but exhausting. Remembering exact commands, hunting down files, killing rogue processes, checking network, deploying scripts — it adds up fast.

What if you had a local AI that doesn’t just tell you what to do — it actually executes safely, with your approval every time anything dangerous happens?

That’s why I built zkzkAgent — fully offline, no cloud, no telemetry, privacy-first Linux system manager.

Repo → https://github.com/zkzkGamal/zkzkAgent

🚀 What’s Working Really Well

🛠 1. Real System Control
zkzkAgent can:

Search files & folders intelligently
Find & kill processes
Run safe shell commands (ls, date, whoami, etc.)
Deploy scripts with AI help choosing options
Handle all destructive actions (rm, install, remove) with explicit human confirmation

It reads your intent, plans the safest path, and streams results live.

🌐 2. Network Smarts

Auto-checks internet before any web/search/browser task
Reconnects Wi-Fi via nmcli if dropped
Searches DuckDuckGo or grabs images straight to your media folder

Makes remote work, quick lookups, and downloads seamless.

🎤 3. Optional Voice Mode

Whisper for speech-to-text
Coqui TTS (working on XTTS-v2 cloning for better anime-ish voices)
Hands-free control — talk to your system like a real assistant

Type or speak — it responds either way.

🔥 New: Smart Package Management (the part I’m most excited about)
Just added a package tool that actually feels safe & useful for developers:

Human-in-the-loop on every install/remove/upgrade/clean
Detects OS once → uses safe priority to avoid dependency hell:
1. Special cases (no search needed):
  - postman → sudo snap install postman
  - code/vscode → sudo snap install --classic code
  - discord/slack → snap or flatpak
  - zoom → wget .deb + dpkg
2. Flatpak first for GUI/dev tools (sandbox + shared runtimes = fewer fights)
3. Snap next
4. apt only for CLI/system utils
Checks if already installed (command -v / snap list / flatpak list) before suggesting
Shows full command preview + explanation (dry-run style)
Logs every command + your approval
No blind runs — always "yes/no" for anything that touches the system

Example flow — "install postman":

→ planner sees snap path
→ executor: check_internet() once → propose "sudo snap install postman"
→ shows preview → waits for "yes"
→ runs → verifies with postman --version

Why this matters for devs:

Avoids the classic "apt install nodejs → wrong/old version" nightmare
Reduces snap vs flatpak vs apt version conflicts (huge pain on Ubuntu)
Everything is auditable — you see exactly what ran

🧠 How I Built It

LangGraph → stateful agent graph (planner → executor → tools → human interrupt)
Ollama → local inference (Llama 3.1 8B or whatever model you run)
Tools → simple Python wrappers (subprocess for shell, etc.)
Safety → interrupt + input() for confirmation on dangerous actions

Everything 100% local — no data leaves your machine.

🧪 Honest Limitations Right Now

Only tested on Ubuntu/Debian (apt/snap/flatpak paths)
No automatic rollback if install fails (yet)
Voice TTS prosody still needs work (switching to XTTS-v2 cloning soon)
Package tool is smart but not perfect — edge cases exist

Quick Start (try it in ~2 minutes)

git clone https://github.com/zkzkGamal/zkzkAgent.git
cd zkzkAgent
chmod +x install.sh
./install.sh
source venv/bin/activate
python main.py

Then just type:

"install postman"
"install discord"
"check node version"
"find all python files in my project"
"kill firefox"

🎯 Looking for Dev Feedback

Better conflict detection? (e.g. dpkg -s / snap list before proposing apt?)
Should it auto-suggest nvm/pyenv/volta for node/python/go runtimes?
Flatpak vs snap — which should be default for GUI apps in 2026?
Any scary package edge cases I missed? (PPA hell, broken deps, etc.)

PRs, issues, forks, brutal roasts — all welcome.
Built in Cairo with ❤️ by zkaria (@zkzkgamal11)

This version keeps your voice: honest, technical enough for devs, shows real value, admits limitations, and invites collaboration — just like your original example.

Let me know if you want it shorter, more code-heavy, or tweaked for a specific platform (X thread, Reddit, DEV.to, etc.). Ready to ship! 🚀