What Nobody Tells You About Building Production LLM Agents

Over the past few months, I have been focused on an exciting engineering challenge: building LLM-powered skills and workflows to optimize our internal engineering triaging.

When you read the marketing materials for modern AI agents, it sounds like you can just hand them a folder of documents and let them run. The reality of moving an agent from a cool demo to a reliable production tool is a completely different story.

Here is what I learned while building an automated Root Cause Analysis (RCA) agent—and where the common assumptions fail.

The Challenge: Scaling Domain Expertise

I work in a fast-moving engineering team of about 30 people, structured around deep Subject Matter Experts (SMEs), developers, and QA engineers.

Because our product handles complex features, our specialized SMEs are constantly in high demand. When a customer incident or a critical last-minute bug arises, developers frequently need to consult an SME for confirmation on the best path forward. If those experts are tied up solving other critical issues, engineers have to independently piece together context from multiple deep Confluence pages—some of which naturally struggle to keep pace with our rapid deployment cycles.

This creates immense pressure on the team and naturally introduces delays when we need to triage issues quickly.

The Proposed Solution
To help scale our team's domain expertise and make triaging more self-service, I built an automated triaging skill using an AI agent framework. The goal was straightforward:

1. Pull bug details from a JIRA ticket.
2. Feed the context into an LLM.
3. Allow the agent to utilize a customized knowledge base and system tools to triage the incident.
4. Output a comprehensive, foundational RCA document in minutes to give engineers a head start.

The heart of this solution was the Knowledge Base—a collection of documents detailing exactly which diagnostic tools to use, step-by-step triaging procedures, and specific error patterns to look for in system logs.

Where It Went Wrong: The Reality of Agent Behavior

My initial assumption was intuitive: If I give a premium LLM a highly detailed, step-by-step engineering procedure, it will execute it exactly like an expert engineer.

I was wrong.

As the complexity of the instructions grew, the agent's reliability collapsed. We ran into several critical issues:

• Hallucinations: The models invented log patterns that didn't exist in our actual systems.
• Step Skipping: The agent routinely bypassed critical diagnostic steps outlined in the documentation.
• Tool Amnesia: It completely forgot to utilize available diagnostic tools at its disposal.
• Model Divergence: Different underlying LLMs produced wildly inconsistent outputs, making the resulting RCA document too unreliable to trust blindly.

The Illusion of Domain Expertise

Another major trap I fell into was expecting the LLM to have a baseline, superficial knowledge of our specific enterprise product and domain out of the box.

During our initial trials, the model answered basic questions confidently, giving us the false impression that it truly understood how our systems operated. But in reality, when confronted with complex, production-level triaging issues, that superficial understanding dissolved. The model began hallucinating even basic domain realities.

The Lesson: Confident answers during a simple demo shouldn't be mistaken for actual architectural comprehension. Out-of-the-box LLMs do not inherently understand proprietary enterprise systems.

The Root Cause: "Context Window Pressure"

Through repeated testing and boundary analysis, I realized what was actually happening. We talk a lot about "large context windows," but we rarely talk about the cognitive load on the model within that window.

When you saturate an agent with too many details, structural instructions, and workflows simultaneously, the model experiences a form of algorithmic "pressure."

You have to budget your context window carefully. Every line of your agent configuration, every knowledge base file injected, and every historical step in the workflow eats away at the model's attentional capacity. If your system prompts are bloated, the model loses its ability to follow instructions precisely.

Iteration: Why Pure Scripting Failed

In my first attempt to fix this, I tried to enforce determinism by rewriting the entire skill around Python scripts. The idea was to force the agent to execute code and simply process the raw textual output.

This backfired. Combining complex system-level execution code with high-level textual instructions in the same prompt confused the model further. The agent began hallucinating the script outcomes or skipping the code execution entirely to protect its remaining context window.

The Engineering Fix: Designing for Consistency

To achieve consistent, production-grade behavior across multiple LLM models, I had to completely re-engineer the agent's architecture. I applied a five-part remediation strategy:

• Ruthless Prompt Pruning: I rewrote the core configuration (SKILL.md), cutting it down to under 400 lines. Every instruction was rewritten to be incredibly explicit, simple, and direct—devoid of ambiguity.
• Adhering to Vendor Standards: I refactored the prompt formatting to strictly align with Anthropic's system prompting standards (utilizing clear XML tagging and explicit "Do/Do Not" guardrails).
• Decoupling Workflows from the Core Skill: I removed heavy, multi-step workflows that were duplicating details the skill already inherently understood. Instead, I moved complex procedures into modular reference files that the agent is instructed to fetch only when a specific condition is met.
• The "Mid-Level Engineer" Domain Grounding: To fix the domain hallucinations, I introduced a lightweight .md file focused solely on core product concepts. I explicitly instructed the agent to read this file during the initial phase of triaging to ground itself. The key here was striking a balance: I didn't overload it with full system architecture diagrams or massive documentation dumps, but provided just enough context to elevate the model to a baseline understanding of our domain.
• Implementing Deterministic Validation Gates: I introduced lightweight JSON validation schemas. Before the agent can finalize and output the RCA document, it must validate its findings against these structured gates, forcing a baseline of consistency.

The Result

By treating prompt space as a highly constrained engineering resource, we stabilized the agent. The behavior is now consistent across different LLMs, and the generated RCAs are tracking reliably against what our human experts expect, serving as a powerful accelerator for our engineering team.

In a future post, I will dive deeper into the mechanics of Context Engineering and how to calculate your prompt's "cognitive budget."