That leaves most people stuck. How do you get enterprise experience without already working at an enterprise?

This week’s answer is a dataset I keep coming back to, plus the lab I built around it.

Meet TechQA

TechQA is a free dataset of real IBM technical support questions, asked by real IBM customers. It isn’t synthetic and it isn’t tidy Wikipedia trivia.

Every question comes with 50 candidate documents (IBM “technotes”):

• One is the right page.

• The other 49 are look-alikes: same product, same error codes, almost the same title.

• And sometimes none of them are right.

That last point is the important one. It’s exactly what a client’s knowledge base looks like: messy pages that all sound the same, and questions where the honest answer is “I can’t find support for that.”

Learn to handle that and you’ve learned what clients actually pay for.

The lesson you can’t fake

Here’s what separates people who’ve built this from people who’ve watched videos about it.

TechQA tells you where each answer sits inside its source page (a start and end offset). So you can measure something most tutorials never check.

When I measured it, 16% of answers start after character 2,000.

Now look at what a lot of tutorials do:

text = doc[:2000]   # “just keep the opening of each document”

For that 16%, the answer is gone before search even begins. No retriever, re-ranker or prompt can recover text you’ve already thrown away.

You only learn this by measuring.

What you’ll build in the RAG Lab

The lab takes you from raw data to a measured baseline:

1. Inspect the data: splits, answerable vs. unanswerable questions, candidate lists.

2. Compare raw HTML with clean text: what does stripping actually change?

3. Measure answer positions: where do answers live, and what does truncation cost you?

4. Build a BM25 search: a simple, honest keyword baseline.

On 160 real questions, the BM25 baseline found:

• the right page first 47% of the time

• the right page in the top 5 63% of the time

That’s your number to beat. Even better, the failures tell you what to fix next: the query, the documents, or the ranking.

That’s the exact workflow you’d walk an interviewer through: data first, then measurement, then a baseline, then targeted fixes.

Real scale, on your laptop

You start with about 28,500 documents, then move to the full library of 802,000. That’s 28× bigger.

At that size you hit the problems you’d normally only meet on the job: indexing time, memory, and whether your results still hold up as the data grows.

Try this before next week

Even if you never open the lab, try this one exercise on whatever RAG project you have:

Find out where your answers live. For a handful of questions you know the answers to, record the character position of the answer in its source document. Then check whether your chunking or truncation keeps it.

If you find answers past your cut-off, you’ve just found a bug that no amount of prompt engineering will fix.

What’s next

This is Part 1 of a 3-part series on RAG for FDEs: retrieval, or finding the right source before you ask a model to answer.

You don’t need an enterprise job to build enterprise skills. You need the right dataset, honest measurement, and a system that knows when to say “I can’t find support for that.”

Hit reply and tell me your BM25 numbers (or where your answers ended up living). I read every reply.

See you in Part 2, Zahir The Adaptive Engineer

Share The Adaptive Engineer

Like many engineers, I associated it with companies like OpenAI, Anthropic, or Palantir.

Engineers who work directly with customers, helping them solve complex technical problems and deploy AI into production.

Then it hit me.

I’ve been doing a version of this for over a year now.

Not for external customers.

For internal ones.

And I think this is one of the most exciting AI career paths that almost nobody is talking about.

My customers aren’t outside the company.

They’re inside it.

I work in a central AI organization.

Across the company, different teams are trying to build AI.

• Marketing

• Supply Chain

• Customer Services

• IT

• E-commerce

Every team has different goals.

Every team has different data.

Every team has different constraints.

But they’re all trying to build on the same AI platform.

My job isn’t to build every AI solution.

It’s to help teams build the right one.

Sometimes that means helping design an agent architecture.

Sometimes it’s deciding between RAG and fine-tuning.

Sometimes it’s defining evaluation metrics before anyone writes a line of code.

Sometimes it’s debugging why an AI agent works perfectly in a demo—but fails in production.

The technology changes every week.

The real job doesn’t.

Bridge AI capability with business value.

Why companies need this role

Every large company eventually faces the same problem.

One team builds the AI platform.

Everyone else tries to use it.

In theory, that’s incredibly efficient.

In reality, application teams quickly discover problems the platform team never anticipated.

So they create workarounds.

They duplicate code.

They build custom orchestration.

They invent new evaluation methods.

Eventually, every team starts solving the same problems independently.

That’s expensive.

And it’s slow.

Companies need engineers who can move between both worlds.

People who understand the platform deeply...

but spend enough time with product teams to understand real business problems.

Every customer conversation becomes feedback for the platform.

Every production deployment improves the platform.

That’s what makes this role so valuable.

How do you become one?

If this sounds like a role you’d enjoy, here are the five things I’d focus on.

1. Ship something real.

Don’t build demos.

Solve a real business problem.

Have real users.

Measure the outcome.

Nothing builds credibility faster than software people actually depend on.

2. Learn to ask better questions.

When someone says:

“We need an AI agent.”

Pause.

Ask why.

Could automation solve it?

Could search solve it?

Would RAG work?

Do we really need fine-tuning?

Great AI engineers don’t start with models.

They start with the problem.

3. Leave behind reusable knowledge.

When you help another team...

Don’t just solve today’s issue.

Leave behind:

• a reference architecture

• a cookbook

• sample code

• evaluation criteria

Your impact grows when the next team can solve similar problems without needing you.

4. Teach instead of owning.

One trap I’ve seen repeatedly is becoming the AI person.

Every project comes through you.

Every deployment depends on you.

Every prompt gets reviewed by you.

Congratulations.

You’ve become the bottleneck.

The goal isn’t to own AI.

The goal is to make everyone around you better at building it.

5. Become a different kind of engineer.

This is probably the biggest lesson I’ve learned.

The technical skills are obvious.

You’ll work on:

• Agent architectures

• Retrieval systems

• Model selection

• Tool integration

• Evaluations

• Production debugging

• Observability

• AI platform design

But the soft skills are what really change your career.

You learn how to:

• Run discovery sessions.

• Communicate with non-technical stakeholders.

• Influence teams that don’t report to you.

• Present trade-offs instead of opinions.

• Build trust with customers.

• Manage expectations.

• Explain complex AI systems to executives.

Those skills are difficult to learn if you spend your entire career inside one product team.

An internal FDE develops both.

You become a stronger engineer.

And a stronger business leader.

Why I think this role matters

People often ask me:

“What’s the most important skill to learn in the AI era?”

They expect me to say:

• AI Agents

• MCP

• LangGraph

• Fine-tuning

Those are all important.

But my answer is different.

Adaptability.

Every customer is different.

Every business problem is different.

Every deployment teaches you something new.

That’s what this role forces you to become.

Not someone who knows every AI framework.

Someone who can apply AI to almost any business problem.

And I believe that’s going to be one of the most valuable engineering skills of the next decade.

Final thought

If you’re already the person people come to when they’re trying to build AI...

If you’ve helped multiple teams adopt AI inside your organization...

If you’ve spent as much time understanding business problems as writing code...

You might already be doing this job.

You just haven’t given it a name yet.

Before that, I was a journalist. Then I moved into operations. And for years, one thought sat at the back of my mind that I never said out loud:

I want to build things.

Today, I’m an architect. I design AI agent systems for a living.

That’s why one claim from Big Tech stopped me cold.

🎥 Watch: Could AI Predict My Career?

The race for your personal agent

Three of the biggest tech companies in the world are racing to build the AI that runs your life:

→ xAI’s Grok Bot runs on its own cloud computer and learns a task by watching you do it once.

→ Meta’s Muse hit #1 on the App Store within a week by cutting bills and chasing refunds.

→ OpenAI’s Dots is OpenAI’s own play for the same job.

Meta’s Chief AI Officer, Alexandr Wang, goes furthest. In his essay Why We’re Building Muse, he describes an AI that works like a “second mind.” It figures out what you want, then makes it happen.

His line: “Every unrealized want is a quiet tragedy of human potential.”

It’s a beautiful idea. I don’t think it could have worked for me.

Where Wang is right

Dreams rarely die in one big failure. They die from a thousand paper cuts: the form you keep postponing, the email you never send, the call you push to tomorrow.

An agent that clears those is genuinely useful. That’s especially true for people without time, money or a mentor.

But his essay makes two different promises and blends them together.

The intent ladder

Here’s the simplest way I know to see the gap. There are three levels of what you can ask an AI:

Level 1: “Do this.” Cancel my unused subscriptions. The goal is clear and the result can be checked.

Level 2: “Help me with this.” Help me save money. It takes several steps, but you can still measure it.

Level 3: “Figure out what I want.” “I feel like there’s something more I could be doing.”

Wang’s essay is about Level 3.

Now look at what Muse is actually being sold for: cable bills, insurance, refunds. Level 1 and Level 2.

The essay talks about dreams. The product handles bills.

Why Level 3 is so hard

It isn’t a marketing gap. It’s a technical one, and there are three reasons.

I break all three down in the video. One of them is personal.

Imagine an AI had read everything about me in my early thirties: my articles, my emails, my searches. I tell it I want something different.

It would have suggested senior editor. Content strategy. A communications job at a tech company.

It would never have said “learn to code at 35 and become an architect.” Nothing in my data pointed there.

AI guesses who you were. Not who you could become.

But what if they didn’t?

This week, I explored Laya, a new open-source decision model, to see whether it could handle the same enterprise workloads I previously tested with Jev - except this time, everything ran locally on my laptop.

No API key.

No hosted endpoint.

Just local inference.

Why I Wanted to Test Laya

A few days after TypeSafe AI released Jev, an open-source alternative called Laya appeared on GitHub and quickly gained significant attention.

On paper, the idea is compelling.

Like Jev, Laya isn’t designed to generate paragraphs of text. It’s built to answer structured questions such as:

• Is this message toxic?

• What sentiment does this review express?

• Which category does this belong to?

• Should this workflow continue?

Instead of generating text and asking software to parse it, the model returns calibrated decisions that applications can consume directly.

The big difference?

Unlike Jev, Laya is completely open source and can run entirely on your own hardware.

That raised an obvious question.

Can an open-source model deliver production-quality decision making without relying on the cloud?

So I decided to find out.

Four Demos. Same Challenges.

Rather than relying on benchmark numbers, I reran the exact same four demos from my previous Jev video.

1️⃣ Sentiment Analysis

Could Laya classify product reviews accurately while running completely offline?

It did - and every prediction happened locally on my CPU.

2️⃣ Chat Moderation

Could it detect toxic prompts before they reached an LLM?

Yes, but with an interesting twist.

The detailed prompt that worked perfectly with Jev caused Laya to classify almost everything as unsafe - even a simple “Hi, how are you?”

Once I simplified the prompt to a single sentence, the results improved dramatically.

Sometimes, smaller models really do prefer simpler instructions.

3️⃣ Sequential Decision Making

Next came the maze-solving challenge.

The goal wasn’t just making one correct prediction - it was making the correct decision repeatedly until reaching the destination.

Most mazes worked well.

One didn’t.

Laya entered an infinite loop on a maze that Jev solved with ease.

It was a useful reminder that zero-shot reasoning remains one of Jev’s biggest strengths.

4️⃣ Real-Time Video Moderation

Finally, I tested a complete pipeline.

GPT-4o Mini handled OCR by reading handwritten text from a webcam.

Laya then classified that text locally as Safe, Toxic, or Prompt Injection.

The only cloud call left was OCR.

Every moderation decision happened on-device.

The Biggest Surprise Wasn’t Accuracy

It was performance.

My first benchmark suggested Laya took roughly one second to classify a review.

That result was completely wrong.

I had accidentally benchmarked the model’s cold start instead of steady-state inference.

After warming up the model, reducing CPU thread oversubscription, and batching predictions together, inference became roughly 10× faster.

One review dropped to around 32 ms.

Batching reduced that to roughly 3.2 ms per review on my machine.

It was a great reminder that measuring AI systems correctly is just as important as choosing the right model.

My Biggest Takeaway

I don’t think this is a story about Jev versus Laya.

I think it’s a story about choosing the right tool.

If you need strong zero-shot performance with minimal setup, Jev remains incredibly impressive.

If your data can’t leave your environment, you want complete deployment control, or you’re willing to fine-tune a model for your own workloads, Laya is an exciting open-source alternative.

Both represent a shift away from using large language models for every decision.

As AI agents become more autonomous, they’ll constantly need to answer questions like:

• Should I continue?

• Which tool should I call?

• Is this request safe?

• Which workflow executes next?

• Should I ask for human approval?

Those aren’t generation problems.

They’re decision problems.

And it’s exciting to see both commercial and open-source models pushing this new category of AI forward.

Watch the Video

In this week’s video, I rerun all four enterprise demos using Laya and compare the results directly against Jev - including where it excelled, where it struggled, and the benchmarking mistake I almost published before catching it.

I’d love to hear which direction you think enterprise AI is heading: hosted decision models, open-source alternatives, or perhaps a combination of both.

What if the next breakthrough in AI isn’t another chatbot... but a model that simply makes better decisions?

Every week, another AI model launches promising to write better code, generate better text, or reason better.

JEV takes a completely different approach.

Instead of generating paragraphs, JEV is built to make decisions.

It’s the first System One Model from TypeSafe AI—a new class of AI models designed to produce fast, structured, type-safe decisions that software can consume directly.

Why I’m Paying Attention to JEV

One of the reasons JEV caught my attention isn’t just the technology—it’s who built it.

TypeSafe AI was founded by Diogo Almeida, a former OpenAI researcher who helped develop the Reinforcement Learning from Human Feedback (RLHF) methods that ultimately powered InstructGPT and ChatGPT.

After helping build conversational AI, he began asking a different question:

“If language models have become incredibly good at talking, why haven’t they become equally good at powering software?”

His conclusion was fascinating.

RLHF optimized models for conversation.

But enterprise software doesn’t need another chatbot.

It needs models that can make fast, reliable, calibrated decisions.

That realization led his team to spend two years building an entirely new category of AI called System One Models.

Instead of asking a model to generate text and hoping it follows instructions, JEV is trained to make structured decisions with confidence scores.

TypeSafe calls this new training paradigm Reinforcement Learning for Calibrated Decisions (RLCD).

The difference is subtle—but significant.

RLHF

Generate the response humans prefer.

RLCD

Return the correct decision—and tell me how confident you are.

That’s a very different optimization objective.

And it shows.

Why This Matters

Think about how most enterprise AI systems work today.

A customer message arrives.

We ask an LLM:

• Is this toxic?

• Which support queue should receive it?

• Is the customer frustrated?

• Should the agent continue?

• Which tool should execute next?

The LLM generates text or JSON.

We parse it.

Validate it.

Retry when formatting breaks.

Hope it doesn’t hallucinate.

JEV removes that entire layer.

Instead of generating text, you define the possible outputs up front.

For example:

• Billing

• Sales

• Technical Support

• Refund

Or perhaps:

• Safe / Unsafe

• Positive / Neutral / Negative

• Continue / Stop

JEV simply returns the decision—along with a calibrated confidence score.

No prompt engineering.

No parsing.

No “Please return valid JSON.”

Just a decision.

So I Wanted to Test It

Rather than talking about benchmarks, I wanted to see how JEV performs on problems AI engineers actually solve.

So I built four enterprise demos.

1️⃣ Sentiment Analysis

Can JEV classify thousands of customer reviews accurately and consistently?

2️⃣ Chat Moderation

Can it stop unsafe prompts before they ever reach your LLM?

3️⃣ Decision Making

Can it repeatedly make the correct next decision while solving a constrained problem?

4️⃣ Video Moderation

Can it analyze OCR text extracted from live video and detect unsafe content in real time?

These aren’t synthetic benchmark tasks.

They’re the kinds of decisions enterprise AI systems make every single day.

My Biggest Takeaway

I don’t think JEV replaces GPT-5, Claude, or Gemini.

I think it replaces thousands of tiny classification prompts we’ve been asking those models to perform.

As AI agents become more autonomous, they’ll constantly need to answer questions like:

• Should I continue?

• Which tool should I call?

• Is this safe?

• Which workflow should execute next?

• Should I ask for human approval?

Those aren’t generation problems.

They’re decision problems.

And that’s exactly what JEV was designed to solve.

Watch the Demos

I put JEV through four real enterprise challenges to see whether this new approach actually delivers in practice.

How do you prevent the model from drowning in tool definitions?

The answer is Progressive Discovery.

Instead of exposing every tool upfront, the client progressively reveals only the tools needed to solve the user’s request.

Let’s see how it works.

The Problem: Every Tool, Every Time

Imagine your MCP client is connected to Salesforce, GitHub, Slack, Google Drive, Stripe, Notion, and dozens of other services.

The traditional approach is straightforward:

1. Load every tool schema.

2. Send them all to the LLM.

3. Let the model figure out which one to use.

That means the model receives hundreds of tool definitions before it has even processed the user’s request.

A simple question like:

“Update the Salesforce lead for Acme Corp.”

still forces the model to inspect Slack tools, GitHub tools, Google Drive tools, Stripe tools, and everything else.

Most of those tools are irrelevant.

The result?

• Larger prompts

• Higher token usage

• Increased latency

• More expensive requests

• Harder tool selection

The bigger your MCP ecosystem becomes, the worse this problem gets.

The Solution: Progressive Discovery

Instead of exposing hundreds of business tools, the client exposes only three discovery tools:

• Search – Find relevant tools

• Inspect – Load a tool’s schema

• Call – Execute the selected tool

The interaction becomes incremental.

The model first searches the available catalog:

“Find tools related to Salesforce lead updates.”

The client returns only matching tools.

The model then requests the schema for the one it wants to use.

Only that schema is loaded into context.

Finally, the model executes the tool.

Rather than loading 200 tool definitions upfront, the model learns about exactly one tool when it needs it.

Same Capability. Much Smaller Context.

One of the biggest misconceptions is that Progressive Discovery reduces what the model can do.

It doesn’t.

The model still has access to every tool connected to the MCP client.

The difference is when those tools are introduced.

Instead of carrying hundreds of unused schemas inside the context window, the model only receives the definitions required for the current task.

This produces several practical benefits:

• Smaller prompts

• Lower token consumption

• Faster responses

• Better tool selection

• Support for much larger tool ecosystems

The capability remains identical.

The context becomes dramatically smaller.

The Complete Agent Loop

Here’s what actually happens during execution.

1. Application starts

The MCP client connects to its servers, downloads the available tool catalog, and caches it locally.

Nothing is sent to the model yet.

2. User submits a request

For example:

“Update the Salesforce lead for Acme Corp.”

3. The harness prepares the prompt

Instead of sending hundreds of business tools, it sends:

• The system prompt

• The user request

• Conversation history

• The three discovery tools

4. The model searches

Guided by the system prompt, the model decides it first needs to discover relevant tools.

It calls the Search tool.

5. The harness executes the search

The search runs against the MCP client’s cached catalog—not every external service.

The client returns only the relevant tools.

6. The harness updates the context

The next model request now includes only those relevant tool definitions.

7. The model executes the tool

With the schema available, the model selects the correct tool, the harness executes it, and the result is returned.

8. The model generates the final response

The user receives the answer.

The model never needed to inspect hundreds of unrelated tools.

The Key Idea

Progressive Discovery doesn’t make the model less capable.

It simply ensures the model only learns about the capabilities it needs when it needs them.

That’s what allows modern MCP clients to scale from a handful of tools to hundreds—or even thousands—without overwhelming the model with unnecessary context.

Share The Adaptive Engineer

Not because it broke the application.

Because it exposed a pattern I keep seeing with AI systems.

I picked the wrong model.

On paper, the choice looked reasonable. The model was capable, documented, and seemed like it should fit the task. But once the audio started flowing through the system, the cracks appeared.

And that’s the trap.

We spend a lot of time comparing benchmark scores, context windows, and model rankings. Then we deploy a system and discover that the real question wasn’t “Which model is best?”

It was “Which model is best for this specific job?”

A model that’s excellent at conversation might be a poor choice for transcription.

A model that’s great at reasoning might be unnecessarily expensive for routing tasks.

A model that’s technically capable might introduce latency that makes a voice experience feel broken.

The lesson wasn’t about audio.

It was about architecture.

As AI builders, we’re gradually shifting from prompt engineers to system designers. The challenge is no longer getting a model to work.

The challenge is assembling the right collection of models, tools, and workflows for the outcome we want.

The best AI systems aren’t built around the smartest model.

They’re built around the right decisions.

In this week’s video, I walk through the mistake, why it happened, how I diagnosed it, and what changed once I selected the right model for the job.

Here’s a demo that should make you nervous about the agent you shipped last sprint.

Same tools. Same model. Same task. Call it once: “Please cancel my order #9999.”

It comes back - cancelled, confirmed.

Call it again, thirty seconds later, and ask what happened to that same order. It has no idea. Nothing was kept.

No memory, no persistence - just whatever fit inside that one call’s messages.

That’s not a prompt problem. You could rewrite the wording a hundred ways and it wouldn’t matter, because the fact the model needed wasn’t in its context window when it answered. This is the gap context engineering exists to close.

Prompt Engineering vs. Context Engineering

The difference is one sentence: prompt engineering is wording. Context engineering is what information reaches the model, in what order, and for how long.

You can write the perfect instruction - if the right fact isn’t sitting in the window when the model answers, the wording doesn’t matter.

Why More Context Isn’t the Fix

The obvious instinct is to give the model a bigger window. It doesn’t work. Past a point, more context doesn’t make a model smarter it makes it slower to find the one fact that matters, and more likely to act on something stale or contradictory.

Four specific failure modes show up once you know to look for them in a trace:

• Context poisoning: a wrong fact enters early, and the agent keeps reasoning from it

• Context distraction: accumulated history buries what actually matters right now

• Context confusion: irrelevant information competes for attention and the model picks wrong

• Context clash: two contradictory facts in the window and the agent gets stuck

Every one of these is a management problem, not a model problem. The job isn’t to maximize what’s in context it’s to curate it, every turn, for the life of the task.

The Pipeline

Here’s the actual architecture, and this is the important part it reruns before every single turn, not once at the start of the conversation.

Query augmentation → retrieval → working memory → long-term memory → compression & budgeting → validation → assembly → the model call → tool output feeding straight back into working memory for the next turn.

One honest note: this build uses a scored keyword retriever over a small policy knowledge base, on purpose - the architecture is the point, not the search algorithm. Swap in a vector DB later and every other stage still works unchanged.

Query Augmentation: Clean the Input First

Real users don’t type clean queries. “can i get a refund on my order it hasnt shipped yet” — no structure, buried intent. Send that straight to retrieval and you get weak matches, and now the model is reasoning from context you polluted at step one.

A small, fast model rewrites the message into a clean query and pulls out anything structured - like an order number - before retrieval ever runs. Cheap model, one job: turn mess into signal.

Retrieval: Chunking Is a Trade-off

Chunk too small and you get a sentence with no surrounding context to make sense of it. Chunk too large and you dilute the match - a query about damaged items pulls back a chunk that’s mostly about something else.

This build chunks on sentence boundaries - sized to stay precise without cutting a fact in half — then scores and ranks each chunk against the query.

Memory Is Two Different Jobs

Working memory is scoped to the task in front of the agent right now: goals, facts, decisions, constraints, open questions. It exists for exactly one task, then it’s gone.

Long-term memory is what survives past that - and it’s not “save everything.” There’s an explicit graduation policy.

Decisions and constraints get promoted, because they’re durable. Open questions carry forward as follow-ups. Raw facts and goals get dropped - they were scratch space for a task that’s now done.

The Loop Learns As It Acts

Context isn’t decided once at the start. Every tool call - checking an order, trying a cancellation — folds its result into working memory before the next turn’s context is even assembled.

And what goes back in isn’t the raw tool response. Payment details, internal IDs, anything the model doesn’t need - stripped before it ever reaches the context window. Extract the signal, not the payload.

The Guardrails on the Pipeline Itself

What stops this pipeline from just recreating the same bloated-context problem it started with? Three things.

• Budgeting: every source gets a hard token cap. No source can quietly crowd out the others.

• Compression: over the cap, a source gets summarized down to what still matters. Hard truncation is a last resort, not a first move.

• Validation: three checks before anything reaches the model: Is it still fresh? Is it permitted for who’s asking (a customer never sees staff-only policy)? Does it contradict something already in the window?

Two real documents from this build’s knowledge base get caught by validation live: a 2025 shipping notice that’s simply expired, and a staff-only escalation policy that’s the wrong role for the asker.

It All Comes Back to One Thing

A context manager runs this entire sequence — augment, retrieve, load memory, budget, compress, validate - fresh, before every single call to the model. Not once per conversation. Every turn.

That’s the concept. Next up: opening the actual code and building it piece by piece, starting with the file that ties all of this together.

That’s why I was curious to know more about WebMCP.

And, it seems it might be the solution to the problem I stated above.

Full analysis in the video.

WebMCP lets a website register real, callable functions that an AI agent can invoke directly. No parsing, no reverse-engineering pixels.

If you want to enable WebMCP on your pages you need to simply add a method in your JS script or file.

await document.modelContext.registerTool({
  name: 'search_products',
  description: 'Search the site catalog by keyword',
  inputSchema: {
    type: 'object',
    properties: { query: { type: 'string' } },
    required: ['query'],
  },
  execute: async ({ query }) => {
    return await searchCatalog(query);
  },
});

Think of this as the tool decorator you add on the python functions.

Give it a name, description, input object and the execute function that “calls” the tool.

document.modelContext.registerTool

The Implementation

Lets say you have an ecommerce page that looked like this.

You can add all the operations on page as tools that you want the agents to use.

async function registerWebMcpTools() {
  if (!('modelContext' in document)) {
    setStatus(false,
      'WebMCP not detected in this browser. Enable <code>chrome://flags/#enable-webmcp-testing</code> ' +
      '(Chromium 146.0.7672.0+) and reload, or check developer.chrome.com/docs/ai/webmcp — this API is ' +
      'still an early preview and its enable-steps can change.'
    );
    return;
  }

  await document.modelContext.registerTool({
    name: 'search_products',
    description: 'Search the Comet Goods catalog by product name or keyword. Returns matching products with id, name, price, and description.',
    inputSchema: {
      type: 'object',
      properties: { query: { type: 'string', description: 'Keyword to search for, e.g. "headphones" or "lamp"' } },
      required: ['query'],
    },
    execute: async ({ query }) => {
      const results = searchProducts(query);
      logToolCall('search_products', { query }, { resultCount: results.length });
      return { results };
    },
  });

  await document.modelContext.registerTool({
    name: 'add_to_cart',
    description: 'Add a product to the shopping cart by its product id and quantity.',
    inputSchema: {
      type: 'object',
      properties: {
        productId: { type: 'string', description: 'The product id, e.g. "p1"' },
        quantity: { type: 'number', description: 'How many to add. Defaults to 1.' },
      },
      required: ['productId'],
    },
    execute: async ({ productId, quantity }) => {
      const result = addToCart(productId, quantity || 1);
      logToolCall('add_to_cart', { productId, quantity: quantity || 1 }, result);
      return result;
    },
  });

}

I couldn’t find a working WebMCP client to test so I wrote a custom one using Playwright.

class WebMCPClient:
    def __init__(self, page: Page):
        self.page = page

    def list_tools(self) -> list[dict]:
        print("-"*40)
        print("Listing registered WebMCP tools...")
        print("-"*40)
        tools = self.page.evaluate(
            """async () => {
                const tools = await document.modelContext.getTools();
                return tools.map(t => ({
                    name: t.name,
                    description: t.description,
                    inputSchema: JSON.parse(t.inputSchema),
                }));
            }"""
        )
        return tools

    def call_tool(self, name: str, arguments: dict) -> dict:
        print("-"*40)
        print(f"Calling tool {name} with arguments: {arguments}")
        print("-"*40)
        raw = self.page.evaluate(
            """async ([toolName, argsJson]) => {
                const tools = await document.modelContext.getTools();
                const tool = tools.find(t => t.name === toolName);
                if (!tool) throw new Error(`No such tool: ${toolName}`);
                return await document.modelContext.executeTool(tool, argsJson);
            }""",
            [name, json.dumps(arguments)],
        )
        try:
            return json.loads(raw)
        except (TypeError, json.JSONDecodeError):
            return raw

Below are some logs from the agent run.

Registered WebMCP tools:
----------------------------------------
Listing registered WebMCP tools...
----------------------------------------
  - add_to_cart: Add a product to the shopping cart by its product id and quantity.
  - checkout: Place an order for everything currently in the cart. This is a consequential action and will ask the user to confirm.
  - get_product_details: Get full details for a single product by id.
  - search_products: Search the Comet Goods catalog by product name or keyword. Returns matching products with id, name, price, and description.
  - view_cart: Get the current contents of the shopping cart, including line items and total price.

search_products('keyboard'):
----------------------------------------
Calling tool search_products with arguments: {'query': 'keyboard'}
----------------------------------------
  {'results': [{'id': 'p1', 'name': 'Orbit Mechanical Keyboard', 'price': 129, 'description': 'Hot-swappable switches, USB-C, tenkeyless.'}]}

add_to_cart(p1, 3):
----------------------------------------
Calling tool add_to_cart with arguments: {'productId': 'p1', 'quantity': 3}
----------------------------------------
  {'ok': True, 'message': 'Added 3 × Orbit Mechanical Keyboard to cart', 'cartCount': 3}

get_product_details(p3):
----------------------------------------
Calling tool get_product_details with arguments: {'productId': 'p3'}
----------------------------------------
  {'id': 'p3', 'name': 'Nebula Noise-Cancelling Headphones', 'price': 189, 'description': '30-hour battery, adaptive ANC.'}

Where it stands currently

It isn’t production-ready - and should not be used in production by you as well.

It has moved into a formal Origin Trial.

Key Takeaways

• WebMCP lets a page register real, callable functions for AI Agents using document.modelContext.registerTool

• It’s not an implementation of Anthropics Model Context Protocol

• It’s designed for a human-in-the-loop browser tab, not headless background

• It’s early: a Chrome Origin Trial, and explicitly not production-ready yet

Every few weeks a new model tops a leaderboard and the timeline loses its mind.

But if you’ve actually shipped agents in production, you already know the uncomfortable truth: the model is rarely why your agent fails.

The harness - the loop, the tool-calling contract, the memory, the guardrails around the model is what separates something that works from something that hallucinates, loops, or quietly does the wrong thing.

This week gave us a perfect case study.

DeepSeek's biggest launch of the week wasn't the model

On August 13, DeepSeek shipped DeepSeek Harness v0.1, a developer preview, MIT-licensed, open-sourced the same day as its DeepSeek-V4-Pro model GA release.

Repo: https://github.com/deepseek-ai/deepseek-harness

What’s notable is what they chose to open source alongside a flagship model launch: not another benchmark flex, but the scaffolding.

The core idea is “everything is a plugin” the inference layer, tool registry, session state, control loop, execution sandbox, even the web UI are all separately swappable pieces, built on what they call the Cordis meta-framework.

It’s DeepSeek’s answer to Claude Code: not a smarter model wrapped in a fixed harness, but a harness you can rebuild around any model.

The repo hit 100K+ GitHub stars and 11K+ forks within 3 days — one of the fastest adoption curves a dev tool has seen this year.

What people are saying about it specifically:

Within 24 hours - the OSS community contributed 365 plugins

Here’s what the creator of another famous harness “Pi” has to say

DeepSeek clearly read the room — they didn’t just ship a better model, they shipped the thing that lets any model perform better.

Why I went down the NVIDIA object-oriented agents rabbit hole

This is exactly why I spent this week digging into NVIDIA’s NOOA (NVIDIA Object-oriented Agents) because it’s one of the more radical harness redesigns I’ve seen, and it’s not just theory.
NVIDIA’s own benchmarks show NOOA agents solving more problems on SWE-bench while using roughly half the tokens - same underlying model, no prompt compression tricks.

The core idea: stop inventing a new agent language.
Your agent is just a Python class. Methods become tools, docstrings become instructions, type hints become runtime-enforced rules and you can leave a method body as just “..." and the framework writes and executes the implementation for you at runtime.

Three design choices do the heavy lifting:

• Code as the action — instead of the model emitting JSON that gets parsed into a function call every single turn, the model just writes Python directly. No parse/translate loop repeating on every tool call.

• Pass by reference — instead of serializing a whole object (think: an entire spreadsheet) into the prompt as text, NOA hands the model a reference to the actual object and lets generated code operate on it. The prompt only carries a tiny preview.

• Typed I/O as guardrails — Pydantic-style validation gets enforced automatically, and the agent self-corrects against validation errors without you writing retry logic.

In a live demo, a naive tool-calling loop burned 10,823 tokens across 10 LLM calls to check whether a shopping cart fit a budget; NOOA did the same task in 2 calls and ~7,194 tokens — a ~33% reduction, in line with NVIDIA’s own published numbers.

It’s still early — NVIDIA is upfront that this is research-stage, and letting a model generate and execute arbitrary code means you sandbox it, full stop, never run it against your primary filesystem. But as a glimpse of where harness design is heading — away from JSON tool-calling ceremony and toward “the agent is just... code” — it’s the most interesting thing I’ve read this month.

🎥 Full walkthrough with live demos:

The thread connecting both stories this week: nobody’s winning by having the smartest model anymore.
DeepSeek and NVIDIA, in completely different ways, are both racing to build the best scaffolding around models that are all converging toward “good enough.”

That’s where the real engineering work and the real differentiation is happening now.

Build AI Agents by Building a Real Project

Most LangChain tutorials teach APIs.

This one teaches AI engineering.

In this new video, we build Aria, an AI Executive Assistant, while learning LangChain the way production systems are actually built—one capability at a time.

You’ll hand-code tools, memory, agents, MCP, and more, so you don’t just know how to use AI agents—you understand how they work and how to debug them.

If you’re serious about becoming an AI Engineer, this is the series to follow.

🎥 Watch the video and start building Aria today.

A developer agent burned $12,000 in cloud costs overnight.

A coding agent deleted a startup’s entire production database—including backups—in nine seconds.

Another AI agent executed a stale terraform destroy command and wiped two and a half years of production data.

None of these failures were caused by hackers. None were caused by a “bad” LLM.

They happened because the agent had too much permission and too little supervision.

The real risk isn’t the model.

It’s the harness around it.

Subscribe now

A Tool Is Much More Than Code

Most people think of a tool as a Python function.

That’s implementationoduction systems care far more about the metadata around the tool.

Every tool should answer questions like:

• What is your name?

• What do you do?

• What inputs do you expect?

• What permissions do you require?

• Can you be retried?

• Can you be cached?

• How expensive are you?

• What happens if you fail?

• Should a human approve execution?

The actual business logic is often the smallest part.

Everything around it exists so the harness can use the tool safely.

Every Tool Needs a Lifecycle

Production systems shouldn’t invoke tools directly.

Instead, every tool should move through a lifecycle:

1. Register – Add the tool to the harness.

2. Advertise – Tell the LLM the tool exists.

3. Select – Let the model choose the tool.

4. Validate – Verify arguments and environment.

5. Permission Check – Confirm the user and agent are allowed to execute it.

6. Execute – Perform the action.

7. Observe – Capture success, failure, timeout, or partial completion.

8. Normalize – Convert outputs into a consistent format.

9. Return to the Loop – Feed results back to the reasoning engine.

Notice something interesting.

Only one stage actually touches the real world: Execute.

Everything else is architecture designed to prevent mistakes before they happen.

Guardrails Don’t Sit Outside the Lifecycle

Many people imagine guardrails as a separate security layer.

They’re not.

Guardrails belong inside the tool lifecycle.

Different stages require different protections:

• Registration → Should this tool even be exposed?

• Selection → Is this the right tool for this request?

• Permissions → Should this user execute it?

• Execution → Does it require sandboxing, rate limits, or human approval?

• Response → Does the output contain secrets, PII, or unsafe content?

Good harnesses don’t rely on a single guardrail.

They place the right guardrail at the right stage.

Principles of Good Tool Design

Over time, a few patterns consistently emerge:

• One tool should do one job well.

• Write descriptions for the model, not humans.

• Use structured JSON inputs and outputs.

• Never hide failures.

• Make tools idempotent whenever possible.

• Keep the number of exposed tools manageable.

A surprising lesson?

After about 15 tools, adding more highly specialized tools often reduces selection accuracy.

Sometimes fewer, broader tools perform better because they consume less context and make better decisions.

Production Starts Where Happy Paths End

A mature harness isn’t judged by whether a tool works.

It’s judged by what happens when it doesn’t.

Your harness should anticipate:

• Wrong tool selection

• Invalid arguments

• Hallucinated tools

• Infinite retries

• Slow APIs

• Network failures

• Permission denials

• Malformed outputs

• Timeouts

• Duplicate executions

• Partial success

These aren’t edge cases.

They’re everyday production scenarios.

Harness Engineering Is Everything Around the Tool

If you draw the architecture of an AI agent, the tool itself occupies surprisingly little space.

Almost everything else is harness:

• registering tools

• advertising capabilities

• validating requests

• enforcing permissions

• executing safely

• observing failures

• normalizing responses

• feeding results back into the reasoning loop

That’s why I say:

The model isn’t dangerous. The harness is.

The model can only act through the software architecture you build around it.

If that architecture is weak, the smartest model in the world will still make catastrophic mistakes.

A Simple Exercise

Find the riskiest tool in your system.

Look for one containing words like delete, deploy, or destroy.

Now walk it through each stage of the lifecycle.

If any stage is missing—validation, permissions, observability, normalization, or human approval—that’s your next engineering task.

Because production-grade AI isn’t about making the model smarter.

It’s about making the harness safer.

Share The Adaptive Engineer

Watch the full walkthrough:

For a long time, AI discussions revolved around one thing: the model.

GPTs. Claudes. Geminis, etc.

But if you’ve built even a single production-grade agent, you’ve probably realized something:

The model is only one part of the system.

Today, a much better definition is emerging:

Agent = Model + Harness

The model provides intelligence.

The harness makes that intelligence reliable.

And that’s where most of the engineering happens.

What is Harness Engineering?

Harness Engineering is the software architecture surrounding an LLM that transforms it into a production-ready autonomous system.

Think about everything that exists outside the model:

• Prompts

• Tool calling

• Feedback loops

• Memory

• Context management

• Human approval

• Guardrails

• Multi-agent orchestration

All of these components work together to create an agent that can reason, act, recover, and complete tasks reliably.

The harness is what connects all these pieces.

Layer 1: The Loop

I begin with what I believe is the most fundamental layer:

The Loop.

Its responsibilities are surprisingly simple:

1. Call the model.

2. Evaluate the response.

3. If the task isn’t finished, call the model again.

Repeat until the goal is complete.

Without a loop, an LLM performs exactly one inference:

Input → Output

That’s useful for chat.

It isn’t enough for autonomous agents.

The Anatomy of One Iteration

Every iteration of an agent loop follows the same fundamental lifecycle.

1. Assemble Context

Before the model is called, the harness gathers everything the model needs:

• User request

• Conversation history

• Previous tool results

• System prompt

• Available tools

This becomes the complete context for the next decision.

2. Invoke the Model

The harness sends the assembled context to the LLM.

At this point, the model has only two real choices:

• Return a final answer.

• Request one or more tool calls.

Nothing else.

3. Observe the Response

The harness inspects the model’s output.

If the response contains a tool call, it extracts:

• Tool name

• Arguments

• Metadata

If it’s a normal response, it may already be time to terminate the loop.

4. Execute the Tool

If the model requested a tool, the harness—not the model—executes it.

This could involve:

• Querying a database

• Calling an API

• Running code

• Searching the web

• Reading files

The model never executes tools directly.

It only decides which tool should run.

5. Update the Context

The tool result isn’t immediately returned to the user.

Instead, the harness appends it to the conversation history.

Now the model knows:

“I asked for this information, and here’s what I received.”

This allows the model to continue reasoning using fresh information.

6. Decide Whether to Continue

Finally, the harness determines whether another iteration is needed.

If the model has everything it needs, it responds to the user.

Otherwise, the loop repeats.

Every Major Agent Uses the Same Pattern

Whether it’s:

• Claude Code

• Codex CLI

• Hermes

• OpenClaw

• OpenAI Agents

...they all implement essentially the same loop.

The details differ.

The architecture doesn’t.

At a high level, every loop looks like this:

1. Assemble context.

2. Call the model.

3. Check whether it wants to use a tool.

4. Execute the tool if needed.

5. Add the result back into context.

6. Repeat until a stopping condition is reached.

Once you understand this pattern, reading agent frameworks becomes dramatically easier.

Production Loops Need Guardrails

A production loop can’t simply run forever.

Reliable systems need explicit termination conditions.

Some of the most important ones include:

• Maximum iteration limits

• Wall-clock timeouts

• Goal completion checks

• Repeated tool-call detection

• Handling unrecoverable errors

• Token budget limits

These aren’t optional.

They’re what prevent runaway loops, excessive API costs, and unreliable agent behavior.

The Loop Leaves Behind State

When a loop finishes, it doesn’t just return an answer.

It also leaves behind valuable execution state:

• Tool history

• Context

• Intermediate reasoning

• Progress

• Execution checkpoints

That state becomes the foundation for durable execution, resumable agents, and human-in-the-loop workflows.

In other words:

A good loop doesn’t just solve problems.

It creates the foundation for every layer that comes after it.

The Bigger Picture

This article is the first in a series on Harness Engineering.

We’ll progressively build the software architecture that surrounds modern LLMs:

• Layer 1 — Loops ✅

• Layer 2 — Tools & Permissions

• Layer 3 — Context Engineering

• Layer 4 — Durable Execution

• Layer 5 — Multi-Agent Orchestration

By the end of the series, you’ll understand not just how to use agent frameworks—but why they’re built the way they are.

If you’re serious about building production-grade AI agents, understanding the harness may be even more valuable than understanding the model itself.

Why Your Brand Needs to Show Up on Answer Engines (and How to Monitor It)

Over the past twenty years, we’ve all been conditioned to think in search-first workflows.

You type a query into Google, skim ten blue links, and decide whom to trust.

That mental model is disappearing—quietly, but fast.

Today, more users are skipping the “search → compare → decide” loop entirely and going straight to answer engines like ChatGPT, Perplexity, and Claude. These systems don’t present links; they present conclusions.

And that shift has enormous implications for brands.

The Rise of Answer-Led Discovery

According to data from multiple generative-AI usage studies, nearly 45–60% of new users now start with an AI assistant when exploring a product or service category for the first time. In fact, Perplexity itself claims a 20–30% month-over-month rise in “shopping and services queries.”

That means the customer’s first impression is no longer shaped by your homepage or your Google ranking. It’s shaped by whatever an LLM decides to say about you.

If your brand shows up in that answer, fantastic—you’ve just inherited pre-trained trust.
If it doesn’t, you’ve silently lost a high-intent customer without ever knowing they existed.

A Simple Visual Thought Experiment

Imagine this scenario:

A user asks:

“Who are the top curtain repair services near me?”

The LLM responds confidently, naming three providers.
Your brand is either:

• In the answer → instant credibility

• Not mentioned → invisible

• Misrepresented → losing trust without knowing why

This is the new discovery funnel.
And right now, most brands aren’t even aware it exists.

Why Monitoring Your Brand on ChatGPT & Perplexity Is No Longer Optional

Here’s the uncomfortable truth:
LLMs don’t pull answers from a single database—they synthesize information from various sources: review sites, listicles, Reddit threads, local directories, news mentions, and your own content (if it exists and is structured well enough to be recognized).

If they aren’t citing you, it’s usually because:

• Your content isn’t tuned for answer-engine style queries

• Your competitors have better-structured or more recent content

• Third-party sites describe your category better than you do

• Your brand simply isn’t “on the radar” of the model yet

In every case, the fix starts with monitoring.

What Monitoring Actually Gives You

By actively tracking your brand visibility across multiple queries, you begin to see:

• How often ChatGPT or Perplexity cite you

• Which sources they rely on

• Which competitors consistently show up

• What real customer queries in your category look like

• Which themes or topics you’re missing in your content

In Today’s Episode

In the video, I’ll walk you through a LangGraph agent that:

• Scrapes your website

• Identifies your domain, location, and service themes

• Generates likely customer queries

• Tests those queries against answer engines

• Monitors citations, competitor presence, and content gaps

So instead of guessing how answer engines perceive your brand, you’ll have a real-time dashboard telling you where you stand and how to improve.

Code

https://github.com/zahere-dev/agentexpert-labs/tree/main/business_use_cases/brand_monitoring

Hey everyone!

Have you ever wondered how AI agents like Claude, Anthropic’s Computer Use agent, Gemini’s CLI tools, or LangChain agents handle complex tasks so effectively?

There’s a powerful design pattern that all these top agents share - and today, I’m going to break it down for you.

It’s called write_todos or Todo Tool, and once you understand it, you’ll never build AI agents the same way again.

Full walkthrough of the custom write_todo implementation in Customer Service Agent.

In many AI agents, write_todos is used to create and manage TODO lists that help the agent stay organized and focused during long or complex tasks.

For example, Claude Code uses a feature called plan mode to generate a structured list of steps before starting any work. This is done using a tool called TodoWrite, which is based on a special prompt.

Each TODO item includes:

• A short, clear description of the task

• A status: pending, in progress, or completed

As tasks grow in size—sometimes involving 50 or more tool calls—it becomes harder for the agent to remember everything. This can lead to context rot, where the agent forgets earlier goals or drifts off-topic.

To prevent this, agents like Manus regularly rewrite and update their TODO lists. This helps them stay on track by constantly reminding themselves of their goals, reducing the risk of losing focus or deviating from the task.

There are 2 parts

Phase 1: Planning The agent receives a complex task and uses an LLM to decompose it into smaller, actionable subtasks. Think of it like a project manager breaking down a big project.

[Show example: “Handle customer complaint about delayed order”] The agent might plan:

• Todo 1: Search knowledge base for refund policy

• Todo 2: Look up similar past tickets

• Todo 3: Check shipping status

• Todo 4: Draft response with options

Phase 2: Writing (The Critical Part) [Highlight this]

Here’s the key difference: The agent writes these todos down - typically to a file, database, or persistent storage.

Why use ‘write_todos’?

Reason #1: Transparency and Debuggability

When your agent writes its plan to a file, you as a developer - or even the user - can see exactly what it’s planning to do BEFORE it does it.

Reason #2: Fault Tolerance and Recovery

Here’s where it gets really powerful. If your agent crashes halfway through a task, what happens?

Without write-todos: Everything is lost. Start over. With write-todos: Read the file, see what’s completed, continue where you left off.

Reason #3: Human-in-the-Loop Workflows

Sometimes you want human approval before execution. With write-todos:

1. Agent creates plan and writes it

2. Human reviews and approves (or modifies)

3. Agent reads the (potentially modified) plan and executes

When to use ‘write_todos’?

Multi-step tasks (3+ steps)

If your task naturally breaks down into multiple sequential or parallel steps, write-todos will help.

• Research and analysis

• Customer support workflows

• Data processing pipelines

• Code generation and deployment

• Content creation workflows

Long-running operations (minutes to hours)

Anything that takes significant time benefits from fault tolerance and observability.

High-stakes operations

Financial transactions, data deletion, production deployments - anything where you want a review before action.

Collaborative agent-human workflows

When humans need to be in the loop at any

❌ Don’t use write-todos when:

1. Simple, single-step tasks “What’s the weather?” - No need for todos.

2. Real-time, low-latency requirements File I/O adds overhead. If you need sub-second responses, keep it in memory.

3. Stateless, idempotent operations If the operation can be safely retried from scratch, the crash recovery benefit is less valuable.

The ToDo Methods in our Agent

Below is a simple implementation of the Todo tools for our Customer Service Agent.

Full source code here.

The generated Todo file

{

“created_at”: “2025-11-11T01:26:18.171559”,

“todos”: [

{

“id”: 1,

“task”: “Search knowledge base for \”refund policy\” to understand the guidelines for processing refunds.”,

“status”: “completed”,

“result”: “No relevant article found in knowledge base.”

},

{

“id”: 2,

“task”: “Look up the customer’s order status in the system to determine if the product has shipped or if there are any delays.”,

“status”: “completed”,

“result”: “Found 2 similar past tickets:\n- Ticket TICKET-2024-089: Order delayed - carrier issue\n Customer reported order stuck in transit for 8 days. Root cause: Holiday shipping backlog. Resolution: Expedited replacement sent, original order refu...\n Resolved in: 2 days\n- Ticket TICKET-2024-112: Package not delivered after 10 days\n Order placed 10 days ago, tracking shows ‘in transit’ with no updates. Customer requested refund. Resolution: Refund processed, new order sent with ex...\n Resolved in: 1 day\n”

},

{

“id”: 3,

“task”: “Check recent similar tickets or issues to see if other customers are experiencing similar delays with the same product.”,

“status”: “completed”,

“result”: “Found 2 similar past tickets:\n- Ticket TICKET-2024-089: Order delayed - carrier issue\n Customer reported order stuck in transit for 8 days. Root cause: Holiday shipping backlog. Resolution: Expedited replacement sent, original order refu...\n Resolved in: 2 days\n- Ticket TICKET-2024-112: Package not delivered after 10 days\n Order placed 10 days ago, tracking shows ‘in transit’ with no updates. Customer requested refund. Resolution: Refund processed, new order sent with ex...\n Resolved in: 1 day\n”

},

{

“id”: 4,

“task”: “Review current refund processing times to inform the customer about how long it may take to receive their refund if approved.”,

“status”: “completed”,

“result”: “Completed: Review current refund processing times to inform the customer about how long it may take to receive their refund if approved.”

}

]

}

I strongly recommend you go through the video or the code to full understand this pattern.

So there you have it - the write-todos pattern that powers some of the most sophisticated AI agents in production today.

To recap:

• What it is: Externalize the agent’s plan by writing it to persistent storage

• Why use it: Transparency, fault tolerance, human-in-the-loop, better planning, and testability

• When to use it: Multi-step tasks, long-running operations, high-stakes work, collaborative workflows

The complete code for this example is in the description below. I encourage you to:

1. Clone it and run it yourself

2. Modify it to handle different support scenarios

3. Try adding a “human approval” step before execution

4. Build your own agent using this pattern

Alright. So at work, I’ve been consulting a few teams to design MCP servers.

I have a solution in prod and some teams were interested to learn from my experience.

All my experiments on my blog, YouTube channel, and the solution at work were based on SSE—meaning the transport layer of my MCP servers was Server-Sent Events.

However, recently when one of the devs I was consulting told me that they read SSE transport was deprecated and only STDIO and Streamable HTTP were the only choices, I strongly denied such updates and told them there’s no way I would miss such an update.

They shared the link with me and I just couldn’t believe I had missed that update. An update that had come in late March 2025.

I felt embarrassed as I was recommending SSE transport for all our projects.

Luckily, the change to streamable_http wasn’t big and we could easily get on with the changes.

But I realized staying current with rapidly evolving AI protocols isn’t optional—it’s critical.

Missing a single protocol update can mean building on deprecated foundations, giving outdated advice, and potentially creating scalability issues that won’t surface until production load hits.

I know I’m a bit late here—but let’s understand why SSE was deprecated and learn how to build MCP servers with Streamable HTTP transport.

Why SSE Was Deprecated

The SSE (Server-Sent Events) transport was part of the original MCP specification, but it had fundamental architectural problems that became apparent at scale:

1. Two-Endpoint Architecture

SSE required maintaining two separate endpoints:

• GET /sse for server-to-client streaming

• POST /messages for client-to-server requests

This split architecture created complexity in connection management and made deployment harder.

2. Connection Limit Hell

SSE connections are long-lived HTTP connections. Under load, servers quickly hit OS-level file descriptor limits (~1024 on most systems). Performance testing showed:

• 1000+ concurrent TCP connections with SSE

• Execution times 4x slower than Streamable HTTP

• Success rates dropping sharply after ~1024 concurrent users

3. No Resumability

If an SSE connection dropped, there was no way to resume from where you left off. The entire operation had to restart.

4. One-Way Communication

SSE only supports server-to-client streaming. Client-to-server communication required separate HTTP POST requests, creating an asymmetric architecture.

5. Cloud Deployment Nightmare

Long-lived connections don’t play well with:

• Serverless functions (AWS Lambda, Cloud Run)

• Load balancers with connection timeouts

• Auto-scaling infrastructure

• Container orchestration platforms

Enter Streamable HTTP

Streamable HTTP was introduced in protocol version 2025-03-26 and addresses all of SSE’s limitations. Here’s what makes it better:

Single Endpoint Architecture

Everything goes through one endpoint: /mcp

Connection Reuse

Instead of 1000 concurrent SSE connections, Streamable HTTP reuses TCP connections, keeping the count to just ~50 even under high load.

Flexible Response Format

The server chooses the response type based on the operation:

• Quick operations → Instant JSON response

• Long operations → SSE stream with progress updates

Stateless Mode

Perfect for cloud deployments—no session state to maintain, works beautifully with serverless and auto-scaling.

Migration from SSE to Streamable HTTP

The migration is surprisingly simple:

Python

# Old (SSE)
mcp.run(transport=”sse”)

# New (Streamable HTTP)
mcp.run(transport=”streamable-http”)

Client Code

# Old
from mcp.client.sse import sse_client
async with sse_client(url) as (read, write):
    # ...

# New
from mcp.client.streamable_http import streamablehttp_client
async with streamablehttp_client(url) as (read, write, _):
    # ...

That’s it. The tool definitions, resources, and prompts remain unchanged.

Key Takeaways

1. SSE is deprecated since protocol 2025-03-26 (March 26, 2025)

2. Streamable HTTP is the standard for production deployments

3. Migration is straightforward - mostly just changing transport configuration

4. Performance is significantly better - 4x faster with better scalability

5. Cloud-friendly - Works seamlessly with serverless and auto-scaling

Here’s the video of the week

If you manage a website (or several), you know the pain of alt tags.

They’re essential for accessibility and SEO, but writing hundreds of them manually?

Soul-crushing work.

And let’s be honest: when we DO write them, half the time they end up as generic descriptions like “image-123.jpg” that help exactly no one.

How It Actually Works

The workflow is surprisingly elegant. You feed it any URL, and it:

1. Scrapes the page and finds every image missing an alt tag

2. Extracts rich context – page titles, nearby text, headings, captions, everything around that image

3. Sends both the image URL and context to GPT-4o-mini – this is key: the AI actually LOOKS at the image while understanding where it appears on the page

4. Generates perfect alt tags following Google’s accessibility guidelines

5. Stores everything in a database ready for your CMS

The magic is in the context. Most alt tag generators just describe what they see. This workflow understands PURPOSE. A photo of a laptop gets described differently on a tech news site versus an e-commerce product page versus a workspace inspiration blog.

Who This Is For

This is perfect if you’re:

• A developer managing multiple client sites

• An SEO specialist optimizing for image search

• A content manager drowning in accessibility backlog

• An agency that needs to scale accessibility services

• Anyone who cares about making the web more accessible

The Technical Bits

Don’t worry if you’re not an n8n expert – I walk through every single node in detail. You’ll learn:

• How to scrape websites properly

• JavaScript for HTML parsing (regex-based, no external libraries)

• How to structure prompts for vision AI

• Loop automation techniques

• Database integration basics

Even if you’ve never used n8n before, you’ll have a working automation by the end.

Watch It Here

Today, I decided to take it for a spin.

Here’s my experience.

n8n is everything the “influencers” claim it to be.

It’s intuitive, powerful, and packed with over 400 integrations, a drag-and-drop interface, and custom code options that make complex automations feel effortless.

From the ease of setting it up on my 12-year-old Mac Mini to developing a solution in just 30 minutes (thanks to its impressive documentation), I must say, I’m a fan

As someone who spent a decade building enterprise automation, I can see how n8n solves so many process-related challenges, like streamlining data flows and reducing manual errors.

Is it RPA?

Tools like Power Automate, Automation Anywhere, UiPath, and others do similar things—but deploying and scaling them at an enterprise level requires dedicated teams, hefty infrastructure, and ongoing vendor support.

In contrast, n8n stands out as open-source and self-hostable, with no vendor lock-in or per-bot licensing fees.

It’s API-focused for seamless app integrations rather than UI-based bot mimicry, making it lighter, more flexible, and cost-effective for modern workflows without sacrificing power.

So what did I build with this?

A production-ready n8n workflow that automatically analyzes thousands of customer reviews using AI and generates actionable business insights, such as sentiment trends, key pain points, and improvement recommendations.

My verdict

n8n is a game-changer for efficient, scalable automation. It’s developer-friendly yet accessible to non-coders, and its community-driven updates keep it evolving. If you’re tired of bloated tools, give n8n a try—you won’t regret it.

Why should you learn it?

In today’s fast-paced digital world, automation skills are essential for boosting productivity and staying competitive.

n8n empowers you to connect disparate tools—like APIs, databases, and AI services—without deep coding expertise, saving hours on repetitive tasks.

It’s future-proof: as no-code/low-code platforms rise, mastering n8n opens doors to freelance gigs, startup roles, or internal efficiencies at big companies.

Plus, its active open-source community means constant improvements, free resources, and real-world applications in marketing, data analysis, e-commerce, and more.

Whether you’re a solo entrepreneur automating lead gen or a team lead optimizing operations, learning n8n builds versatile problem-solving skills that pay off immediately and scale with your career.

Your websites, landing pages, and digital content are critical revenue drivers.

But when mismanaged, they leak profits.

As content scales, manual audits fall short, inviting brand inconsistency and compliance risks.

Discover how AI Agents can streamline content audits across thousands of pages.

The Agent-Driven Content Audit System

Let me walk you through the high-level design.

The first step is content ingestion—gathering all URLs and asset metadata from various sources like crawler lists, CSVs, or CMS integrations. This ensures complete, real-time coverage across your content footprint.

Next, the orchestrator prioritizes assets using AI and historical data, focusing audits on high-impact pages first. This guarantees critical content gets the right attention every time.

Multiple audit engines then run in parallel: checking readability, SEO, accessibility, compliance, and post-launch monitoring. They use both third-party tools and custom code for thorough reviews.

All results feed into secure databases that connect content to revenue and risk metrics. Finally, the prioritization engine turns data into business impact scores, triggering automated tickets and alerts so stakeholders can make fast, informed decisions.

I’ve done full walk-through of the code in this video.

The Four Pillars of Intelligent Routing

After analyzing hundreds of production agent systems, four distinct routing approaches have emerged as the foundation of modern agentic architectures. Each represents a different trade-off between accuracy, speed, cost, and implementation complexity.

1. LLM-Based Routing: The Universal Translator

LLM-based routing leverages the same language understanding capabilities that make modern AI so impressive. Instead of trying to predict every possible user intent, you simply ask the language model to analyze the input and make the routing decision.

The core mechanism is elegantly simple: present the LLM with the user's input and a carefully crafted prompt that defines your routing categories. The LLM analyzes the semantic meaning, context, and intent, then outputs a structured decision about where to route the request.

Where it shines:

• Handling ambiguous inputs that don't fit neat patterns

• Understanding complex, multi-part requests that span multiple categories

• Adapting to new types of queries without retraining or rule updates

• Processing context-dependent routing that considers conversation history

The architectural trade-off: Maximum flexibility comes at the cost of latency and API expenses. Each routing decision requires a full LLM inference, which can add 1-3 seconds and $0.001-0.01 per request. For high-throughput systems, these costs compound quickly.

Production pattern: Many sophisticated systems use LLM routing as a fallback for edge cases or as the primary router for high-value, low-volume interactions where accuracy matters more than speed.

2. Embedding-Based Routing: The Semantic Compass

Embedding-based routing transforms the routing problem into a mathematical similarity search. By converting both user inputs and routing destinations into high-dimensional vectors, the system can make routing decisions based on semantic similarity rather than surface-level pattern matching.

The mechanism involves pre-computing embeddings for each possible route (or representative examples of each route), then computing the embedding for each incoming request and finding the closest match using cosine similarity or other distance metrics.

Where it excels:

• Semantic understanding that goes beyond keyword matching

• Multi-language support since embeddings capture meaning across languages

• Consistent performance with sub-second routing decisions

• Handling synonyms and paraphrasing naturally

The sweet spot: Embedding routing offers the best balance of semantic understanding and computational efficiency for most production systems. Once the embeddings are computed, routing decisions happen in milliseconds with no API calls.

Implementation insight: The quality of your route embeddings determines everything. Spend time crafting comprehensive descriptions of each route's purpose and scope—these become the foundation for accurate similarity matching.

3. Rule-Based Routing: The Deterministic Workhorse

Rule-based routing might seem primitive compared to AI-powered alternatives, but it remains the backbone of many production systems for good reason. Using predefined patterns, keyword matching, and logical conditions, rule-based routing provides predictable, lightning-fast decisions.

The approach relies on explicit logic: if the input contains certain keywords, matches specific patterns, or triggers particular conditions, route to the designated handler. Complex decision trees can be built by combining multiple rules and conditions.

Where it dominates:

• High-throughput systems where microsecond response times matter

• Compliance-sensitive applications requiring auditable, deterministic routing

• Well-defined use cases with predictable input patterns

• Resource-constrained environments with minimal computational overhead

The reliability factor: Rule-based routing never has an "off day." It makes identical decisions for identical inputs, making it perfect for systems that require absolute consistency and predictability.

Modern evolution: Today's rule-based systems often incorporate regular expressions, fuzzy matching, and hierarchical decision trees, making them far more sophisticated than simple keyword matching.

4. ML Model-Based Routing: The Learning Specialist

Machine learning model-based routing represents a middle ground between the flexibility of LLM routing and the efficiency of rule-based systems. A specialized classification model is trained on labeled examples of correct routing decisions, creating a dedicated routing function optimized for your specific use case.

The core difference from LLM routing is crucial: instead of using a general-purpose language model prompted to make routing decisions, you train a discriminative model specifically for routing. The routing logic becomes encoded in the model's learned weights rather than expressed through prompts.

Where it excels:

• Domain-specific accuracy that improves with more training data

• Cost-effective operation with no ongoing API expenses

• Fast inference comparable to rule-based systems

• Continuous improvement through retraining on new examples

The training advantage: Unlike embeddings, which rely on general-purpose representations, ML routing models learn patterns specific to your application. They can discover subtle correlations between input features and routing decisions that human-designed rules might miss.

Implementation strategy: The most effective ML routing implementations combine traditional ML features (TF-IDF, n-grams) with modern embedding representations, creating hybrid models that capture both statistical and semantic patterns.

code: https://github.com/zahere-dev/agentexpert-labs

Authentication Flow

Before looking at the code, let’s see how the authentication flow works:

Key points from the flow:

• Clients log in via Auth0 and receive a JWT access token.

• The server uses Auth0’s JWKS (JSON Web Key Set) to validate token signatures.

• Requests without a valid token are rejected with 401 Unauthorized.

Create Auth0 Service (Or any other OAuth provider)

• **We are using Auth0 as it is free**

• Use your github/google account to signup to Auth0 service

• Create a Machine-to-Machine app and generate your domain, client id and secret.

Imports and Setup

import datetime
import os
from zoneinfo import ZoneInfo
from fastapi import Depends, FastAPI, HTTPException, status, Request
from fastapi.responses import JSONResponse
from fastapi.security import HTTPBearer, HTTPAuthorizationCredentials
import jwt
import requests
from jwt.algorithms import RSAAlgorithm
from starlette.applications import Starlette
from starlette.routing import Route, Mount
import logging

from mcp.server.fastmcp import FastMCP
from mcp.server.sse import SseServerTransport
from dotenv import load_dotenv

load_dotenv()

• FastAPI / Starlette: Provide the ASGI framework and request/response tools.

• jwt & RSAAlgorithm: For decoding and verifying JWTs signed with RS256.

• HTTPBearer: A security utility to parse Authorization: Bearer <token> headers.

• dotenv: Loads environment variables (e.g., API keys).

• logging: For server-side logging.

• MCP modules: FastMCP and SseServerTransport enable MCP over SSE.

Auth0 Configuration

AUTH0_DOMAIN = "zahere-dev.us.auth0.com"
API_AUDIENCE = "https://zahere-dev.us.auth0.com/api/v2/"
ALGORITHMS = ["RS256"]

# Set up logging
logging.basicConfig(level=logging.INFO)
logger = logging.getLogger("mcp-server")

# Fetch JWKS keys once at startup
jwks_url = f"https://{AUTH0_DOMAIN}/.well-known/jwks.json"
jwks = requests.get(jwks_url, verify=False).json()

• AUTH0_DOMAIN: Your Auth0 tenant domain.

• API_AUDIENCE: The intended audience claim of the JWT (ensures tokens are meant for your API).

• ALGORITHMS: We only accept RS256 (RSA signature with SHA-256).

• JWKS Fetch: At startup, the server downloads Auth0’s public signing keys. These are later used to validate incoming tokens.

JWT Verification Logic

# Auth setup
security = HTTPBearer()

def verify_jwt(token: str):
    try:
        header = jwt.get_unverified_header(token)
        kid = header["kid"]

        # Find matching JWK
        key = next((k for k in jwks["keys"] if k["kid"] == kid), None)
        if not key:
            raise HTTPException(status_code=401, detail="Invalid auth key")

        public_key = RSAAlgorithm.from_jwk(key)

        payload = jwt.decode(
            token,
            public_key,
            algorithms=ALGORITHMS,
            audience=API_AUDIENCE,
            issuer=f"https://{AUTH0_DOMAIN}/"
        )
        return payload
    except Exception as e:
        logger.error(f"JWT validation error: {str(e)}")
        raise HTTPException(status_code=401, detail="Invalid or expired token")

• Extract header & KID: Each JWT contains a kid (key ID). This tells us which public key was used to sign it.

• Find JWK: Match the kid against Auth0’s JWKS set.

• RSAAlgorithm.from_jwk: Convert the JWK to a usable RSA public key.

• jwt.decode: Validate the token signature, audience, issuer, and expiry.

• If anything fails, raise a 401 Unauthorized error.

MCP Server & Tools (Minimal)

# ======================
# MCP Server Setup
# ======================
mcp = FastMCP(name="Weather and Time SSE Server")

@mcp.tool()
def TimeTool(input_timezone: str = None):
    current_time = datetime.datetime.now()
    if input_timezone:
        current_time = current_time.astimezone(ZoneInfo(input_timezone))
    return f"The current time is {current_time}."

transport = SseServerTransport("/messages/")

@mcp.tool()
def weather_tool(location: str):
    api_key = os.getenv("OPENWEATHERMAP_API_KEY")
    url = f"http://api.openweathermap.org/data/2.5/weather?q={location}&appid={api_key}&units=metric"
    response = requests.get(url)
    data = response.json()
    if data.get("cod") == 200:
        temp = data["main"]["temp"]
        description = data["weather"][0]["description"]
        return f"The weather in {location} is {description} with {temp}°C."
    return f"Couldn't fetch weather for {location}."

• A simple implementation of the MCP server tools

FastAPI App & Endpoints

app = FastAPI()

@app.get("/sse")
async def handle_sse(request: Request):
    auth_hdr = request.headers.get("authorization")
    token = None
    if auth_hdr and auth_hdr.lower().startswith("bearer "):
        token = auth_hdr.split(" ", 1)[1]
    else:
        token = request.query_params.get("access_token")

    if not token:
        raise HTTPException(status_code=401, detail="Missing token")

    verify_jwt(token)

    async with transport.connect_sse(request.scope, request.receive, request._send) as (in_stream, out_stream):
        await mcp._mcp_server.run(in_stream, out_stream, mcp._mcp_server.create_initialization_options())

• Supports two auth methods:

  1. Standard Authorization: Bearer <token> header.

  2. Query parameter ?access_token=... (useful for browser EventSource).

• Token is verified, then SSE connection is established.

Protecting the ASGI Transport

def auth_asgi_wrapper(asgi_app):
    async def app(scope, receive, send):
        if scope["type"] == "http":
            headers = {k.decode().lower(): v.decode() for k, v in scope.get("headers", [])}
            auth_hdr = headers.get("authorization")
            if not auth_hdr or not auth_hdr.lower().startswith("bearer "):
                resp = JSONResponse({"detail": "Not authenticated"}, status_code=401)
                await resp(scope, receive, send)
                return
            token = auth_hdr.split(" ", 1)[1]
            try:
                verify_jwt(token)
            except HTTPException as he:
                resp = JSONResponse({"detail": he.detail}, status_code=he.status_code)
                await resp(scope, receive, send)
                return
            except Exception:
                resp = JSONResponse({"detail": "Invalid or expired token"}, status_code=401)
                await resp(scope, receive, send)
                return
        await asgi_app(scope, receive, send)
    return app

• This wrapper protects the /messages/ endpoint. It intercepts requests, checks for a Bearer token, and validates it before passing control to the MCP transport.

Mount Messages Route

app.mount("/messages/", auth_asgi_wrapper(transport.handle_post_message))

• This makes sure POST requests to /messages/ are also protected by our wrapper

Run the Server

if __name__ == "__main__":
    import uvicorn
    uvicorn.run(app, host="0.0.0.0", port=8100)

The Client

**Below is only part of the client code**. Full code is available in repo.

def get_token():
    import http.client

    conn = http.client.HTTPSConnection(os.getenv("AUTH0_DOMAIN"))
    
    payload = {"client_id":os.getenv("CLIENT_ID"), "client_secret":os.getenv("CLIENT_SECRET"),"audience":os.getenv("AUTH_AUDIENCE"),"grant_type":"client_credentials"}

    headers = { 'content-type': "application/json" }

    conn.request("POST", "/oauth/token", json.dumps(payload), headers)

    res = conn.getresponse()
    data = json.loads(res.read())
    return data["access_token"]


async def main(queries: list[str]):
    sse_url = "http://localhost:8100/sse"
    logger.info(f"Generating Bearer token for authentication")
    auth_token = get_token()
    #auth_token = "12124234"
    logger.info(f"Token generated {auth_token[:20]} ")
    headers = {"Authorization": f"Bearer {auth_token}"}    
    try:
        logger.info("Connecting to MCP Server with token")
        # 1) Open SSE → yields (in_stream, out_stream)
        async with sse_client(url=sse_url, headers=headers) as (in_stream, out_stream):
            # 2) Create an MCP session over those streams
            logger.info("Connected to MCP Server")
            async with ClientSession(in_stream, out_stream) as session:
                
                # 3) Initialize
                info = await session.initialize()
                logger.info(f"Connected to {info.serverInfo.name} v{info.serverInfo.version}")

                # 4) List tools
                tools = (await session.list_tools())
                logger.info(tools)            
                
                ### Run the queries
                
                for query in queries:                
                
                    prompt = get_prompt_to_identify_tool_and_arguements(query,tools)
                    logger.info(f"Printing Prompt \n {prompt}")
                    
                    response = llm_client(prompt)
                    print(response)
                    
                    tool_call = json.loads(response)
                                
                    result = await session.call_tool(tool_call["tool"], arguments=tool_call["arguments"])
                    logger.success(f"User query: {query}, Tool Response: {result.content[0].text}")
    except httpx.HTTPStatusError as http_e:
        logger.exception(f"HTTP Error: {http_e}")
    except Exception as e:
        logger.exception(f"Error: {e}")
            

if __name__ == "__main__":
    queries = ["What is the time in Bengaluru?", "What is the weather like right now in Dubai?"]    
    asyncio.run(main(queries))

• Use the client_id and secret to connect with Auth0 and request for access token

• Send the token to the MCP Server as a header with “Authorization” key.

• If connection is established, you will see the message below, else 401 Unauthorized error