Your AI Is Doing the Wrong Job. That Is On You.

The Bug Was Never the AI

A developer spent two weeks debugging a Python-based deployment pipeline for professional certification courses on Moodle. Every single failure traced back to malformed XML — not a single one was caused by the AI agents authoring the content. The lesson is deceptively simple but widely ignored: when your AI system fails, the problem is almost always how you scoped the role, not the model itself.

This is a story about right-sizing AI roles in production. And it is a lesson most teams are learning the hard way.

The Setup: AI Agents in a Real Workflow

The workflow in question is a multi-stage content pipeline. Team 1 (T1) is a group of AI agents working alongside a subject matter expert who serves as a human-in-the-loop reviewer. Together, they author course content for professional certification programs. A separate developer then takes that content and compiles it into deployable Moodle course packages — a process that involves generating Moodle-compliant XML, packaging assets, and importing everything into the LMS.

This is not a toy demo. It is a production system where real learners access real certification content. When the imports started failing, the instinct — as it so often is — was to blame the AI.

Two Weeks of Wrong Assumptions

For fourteen days, the developer chased what appeared to be content-generation bugs. The AI agents were producing course modules, assessment items, and structured metadata. The Moodle imports kept breaking. The natural conclusion? The AI must be generating bad output.

But every failure, once properly traced, came back to XML serialization issues in the deployment layer — the part of the pipeline that had nothing to do with AI. Namespace mismatches. Encoding errors. Schema validation failures against Moodle's backup format. Classic integration bugs that have plagued LMS deployments since long before large language models existed.

The AI agents were doing their job correctly. The problem was that the pipeline architecture had blurred the boundary between 'content generation' and 'deployment packaging.' Nobody had clearly defined where the AI's responsibility ended and the infrastructure code began.

The Real Problem: Role Confusion at Scale

This pattern is everywhere in 2025's AI-integrated workflows. Teams adopt AI agents — whether through frameworks like LangChain, CrewAI, AutoGen, or custom implementations — and then fail to draw clean lines around what each agent is actually responsible for.

The result is what some practitioners now call 'role bleed': an AI agent gets implicitly tasked with responsibilities that should belong to deterministic code, validation layers, or entirely separate systems. When things break, teams waste days or weeks investigating the AI's output when the failure lives in the scaffolding around it.

Consider the common patterns:

• An AI coding assistant generates API endpoints, but deployment fails because of Docker configuration issues. The team retrains prompts instead of fixing the Dockerfile.
• An AI content agent produces marketing copy, but the CMS rejects it due to field-length constraints. The team blames the model's verbosity instead of adding a validation step.
• An AI data pipeline agent extracts and transforms records, but downstream analytics break because of schema drift in the warehouse. The team adjusts the agent's output format instead of enforcing schemas at the boundary.

In each case, the AI is doing its job. The architecture around it is not.

Right-Sizing Means Drawing Hard Boundaries

The fix is not more sophisticated models or better prompts. It is better architecture. Right-sizing an AI role means defining three things explicitly:

1. Input contract. What exactly does the agent receive, and in what format? If the agent is generating course content, it should receive a structured brief — not a vague instruction to 'make a course.'

2. Output contract. What exactly does the agent produce? If it outputs structured content, that output should conform to a schema that is validated before it ever touches the next pipeline stage. The AI should not be responsible for Moodle-compliant XML. It should produce structured data that a deterministic serializer converts to XML.

3. Failure boundary. When something breaks, where do you look first? If the contracts are clean, you can immediately determine whether the failure is in generation (the AI) or integration (the infrastructure). Without these boundaries, you get two weeks of chasing ghosts.

The Industry Is Slowly Getting This Right

Platforms like Microsoft's AutoGen and emerging agent orchestration tools are starting to enforce clearer role definitions. The 'agent card' pattern — where each agent in a multi-agent system publishes a formal description of its capabilities, inputs, and outputs — is gaining traction precisely because it forces teams to think about boundaries before they start building.

Anthropic's recent guidance on building effective agents emphasizes keeping agent scopes narrow and composing simple agents rather than building complex monolithic ones. OpenAI's function-calling patterns push in the same direction: define what the model can do, validate what it returns, and keep the deterministic logic deterministic.

But tooling alone will not solve this. It requires a mindset shift. Engineers building AI-integrated systems need to treat role definition as a first-class architectural concern — not an afterthought.

The Takeaway

The Moodle story is small. The lesson is not. Across the industry, teams are losing weeks of productivity because they have not clearly defined what their AI agents are — and are not — responsible for. They blame the model when the model is fine. They retune prompts when the bug is in a config file. They add complexity to the AI layer when what they need is a validation step in the infrastructure layer.

If your AI system is failing, ask yourself one question before you touch a single prompt: is the AI actually doing the wrong job, or did you just give it the wrong one?

Most of the time, the answer is uncomfortably clear.