The agent demo that runs perfectly in a Jupyter notebook will embarrass you in production. We learned this on our third or fourth agentic deployment, and we've been fixing it ever since.
This isn't a beginner's guide to what an AI agent is. If you're reading this, you probably already have something working in dev. This is about the gap between "it works in testing" and "it runs reliably at scale, with real users, real data, and real consequences if it gets something wrong."
That gap is wide. Here's what's in it.
What Makes Agents Different From Regular AI Systems
Most enterprise AI systems are request-response: a user sends a query, the system retrieves context, the LLM generates a response. The interaction is bounded, predictable, and observable.
Agents are different. They take an objective and reason through it autonomously — calling tools, observing results, adjusting their approach, and deciding when they're done. This autonomy is what makes them powerful. It's also what makes them dangerous in production.
A regular AI system can hallucinate a wrong answer. An agent can hallucinate a wrong action — and execute it. It can call an API that sends an email, updates a database, or charges a credit card, based on reasoning that was subtly wrong.
This changes the engineering requirements significantly. You're not just validating output quality — you're validating the safety of autonomous decision-making in your specific environment.
Why Agents Fail in Production: The Real Root Causes
We've done post-mortems on a lot of agentic system failures — ours and clients'. The causes cluster into five buckets:
1. Infinite reasoning loops. The agent keeps replanning without acting. This happens when it gets confused about its state, receives unexpected tool output, or encounters an edge case outside its training distribution. Without a hard step limit, it runs until it hits a context limit or timeout — meaning an incomplete job and a confused user, at the cost of the full token usage.
2. Tool call hallucination. The agent invents parameters that don't exist, calls functions with wrong argument types, or makes up tool names. This is particularly dangerous when tools have real-world side effects. We've seen agents email the wrong person, update the wrong record, and make duplicate API calls that incurred real costs — all because parameter validation wasn't tight enough.
3. Cascading errors. One tool fails or returns unexpected output. The agent proceeds with partial information, making wrong assumptions. Step 6 of a 10-step workflow is now built on a corrupted foundation. By the end, you're so far from the original intent that the output is worse than useless — and potentially harmful.
4. Context window overflow. Multi-step agents accumulate history — tool calls, results, intermediate reasoning. Long-running agents hit context limits and start silently dropping earlier context. The agent "forgets" decisions it made in step 2 by step 8, leading to contradictions, loops, and inconsistent output.
5. Latency unpredictability. In testing, your agent takes 30 seconds. In production with diverse real queries, some run in 15 seconds, some in 8 minutes. The P99 latency is 10-20x the median. Users abandon, retry, and create duplicate runs. The system gets into a state you never tested.
The Architecture Patterns That Work
We've converged on three patterns across different use case types. The right one depends on your task complexity, reliability requirements, and how much user interaction is acceptable.
Pattern 1: Single Agent + Tool Set
The simplest production pattern. One LLM, one conversation context, a defined set of tools.
Works well for: research tasks, document analysis, data retrieval and synthesis, content generation with external context, customer-facing assistants.
The key discipline here is keeping the tool set small and well-defined. Every tool you add increases the surface area for hallucination. We typically start with 3-5 tools and add only when there's a specific, documented failure case that requires it.
Tool design matters more than most teams expect. A well-designed tool has:
- A clear, unambiguous function name
- A description that explains not just what it does but when to use it
- Strict input validation with helpful error messages
- Predictable output format (consistent JSON schema)
- A defined behavior for every failure mode
We spend as much time on tool design as on prompt design. Usually more.
Pattern 2: Supervisor + Specialized Workers
For tasks that genuinely require different specializations.
A supervisor agent receives the goal, breaks it into subtasks, and delegates to specialized worker agents. Workers are simpler — narrower context, smaller tool set, defined output schema. Results flow back to the supervisor for synthesis.
Works well for: research and analysis pipelines, parallel processing tasks, tasks spanning multiple knowledge domains, complex report generation.
The risk: coordination complexity. When it works, it's powerful. When it fails, the failure is harder to debug — you need to understand which worker produced bad output and why, and how the supervisor misinterpreted or misrouted.
We've found that explicit output schemas for each worker, defined up front and validated on receipt, dramatically reduce coordination problems. The supervisor doesn't have to interpret ambiguous output — it validates against a contract and fails cleanly if the contract is violated.
Pattern 3: Graph-Based Stateful Workflows (LangGraph)
For enterprise workflows with branching logic, checkpoints, and human-in-the-loop gates.
LangGraph lets you model your workflow as a directed graph: each node is a step, edges are conditional transitions, and state is explicitly managed and persistent. This is the right tool when you need:
- Pause and resume (human review required before certain steps)
- Error recovery with fallback paths
- Restart from checkpoint on failure rather than from scratch
- Formal audit trail of every decision point
This is where most enterprise agentic systems should eventually live. The additional complexity pays back in reliability, debuggability, and the ability to add compliance controls without rewriting everything.
When an agent running on LangGraph fails in production, you know exactly which node it failed at, what state it was in, what input triggered the failure, and how to resume from a clean state. This isn't just nice to have — in regulated environments, it's required.
The Non-Negotiable Production Requirements
These are not best practices or recommendations. If you don't have them, you don't have a production-ready agent.
Hard step limits. Maximum 25 steps for most tasks. When the limit hits, the agent returns whatever it has, logs the incomplete state, and alerts. We've never seen a legitimate enterprise task that required more than 25 steps. If something needs more, it's a scope problem, not an agent problem. The step limit is your circuit breaker.
Tool call validation. Before any tool executes: validate every parameter against a strict schema. Type, range, format, referential integrity if applicable. Fail immediately and loudly on invalid input with a clear error message the agent can understand and act on. Do not let the agent proceed with a "best guess" interpretation.
Immutable audit trail. Every tool call, every intermediate reasoning step, every input and output — written to an append-only log with timestamps, trace IDs, user identifiers, and sequence numbers. Not optional. In any regulated environment, this is a compliance requirement. In any environment, it's how you debug the failure that happens at 2am on a Tuesday.
Human-in-the-loop gates. For any action with irreversible real-world consequences — external communications, production database writes, financial transactions, account changes — build a human approval step. Start with it required on every action. Remove it only after you've validated reliability across 1,000+ real-world instances. The gate costs seconds. The recovery from a bad autonomous action costs hours or days.
Timeout handling per tool. Never let a slow external API hang your entire agent. Every tool call gets an independent timeout with a clearly defined fallback behavior. If the timeout triggers: log it, return a structured error the agent can handle, and let the agent decide whether to retry, skip, or escalate.
Semantic caching. Agents generate a lot of similar sub-queries — especially in multi-step research tasks. Caching semantically similar queries reduces API costs by 30-50% and improves response time significantly for repeated patterns. Worth implementing even for internal-only agents.
What We Use and Why
Frameworks: LangGraph for stateful, complex workflows. LangChain for simpler RAG pipelines. Direct API calls with our own orchestration for high-performance cases where framework overhead matters.
LangGraph has a steeper learning curve than alternatives, but the state management and checkpoint capabilities are worth it for production. The ability to pause at any node, inspect state, and resume is indispensable during debugging. Alternatives have improved significantly, but the checkpoint and human-in-the-loop integration is still LangGraph's biggest advantage.
Models: GPT-4o as the default for agentic reasoning — tool call reliability and structured output consistency are better in our production testing. Claude 3.5 Sonnet for analysis-heavy tasks that require following complex long-form instructions without drift. Gemini 2.0 Flash for multimodal agent tasks or cost-sensitive high-volume routing.
Observability: LangSmith for tracing (especially useful for debugging complex multi-agent flows), Prometheus + Grafana for production metrics (token cost per task, step count distribution, error rates), PagerDuty for agent failure alerts. You need visibility at every level — individual LLM calls, individual tool executions, and the overall task completion rate.
The Three-Phase Reliability Methodology
When we take on a new agentic system, we use a consistent three-phase approach:
Phase 1: Define the failure taxonomy. Before writing a line of code, we enumerate every failure mode: what happens if this API is down, if this document doesn't exist, if the model misunderstands the objective, if the context window fills. Write the failure handling before the success path.
Phase 2: Build to the minimum. Implement the agent with the smallest tool set that accomplishes the task. No scaffolding, no features we think we'll need later. Run it against 200 real representative examples and measure failure rate, step count distribution, and output quality.
Phase 3: Harden iteratively. Add each reliability feature one at a time, measuring impact: step limits, tool validation, caching, re-ranking, timeouts. Each one should improve a specific metric. If it doesn't, you don't actually need it.
Teams that try to build the full production system in one pass almost always end up with something over-engineered, hard to debug, and no clearer on whether it actually works.
Results From Real Deployments
Insurance claims routing — An agent system reads incoming claims, classifies by type and complexity, extracts key data points, and routes to the correct adjuster team. Handles 2,000+ claims per day, 24/7. Adjusters now spend zero time on routing and data extraction — which was previously 45 minutes per claim. The system handles 12 tools including document parsing, database lookup, ML classification, and task queue management.
Market intelligence pipeline (Xenith Intelligence Suite) — An agent runs weekly, pulling hiring signals from Adzuna and RemoteOK, tracking GitHub activity across relevant repositories, monitoring TechCrunch and DeFi news, and synthesizing a scored market report. What used to take a team member 4 hours every Monday runs unattended in 20 minutes. This is the core of our Xenith Radar product.
Legal contract review — Agents process NDAs and service agreements: extracting key clauses, flagging non-standard terms, generating risk summaries. Legal partners review the summary first rather than the full document. Review time cut by 60%. Error rate on flagging non-standard clauses: lower than the previous manual process. The system escalates to human review for any clause it rates above a risk threshold.
Customer onboarding automation — An agent orchestrates 11 steps in a SaaS onboarding workflow: verification, provisioning, configuration, integration checks, and welcome communication. Each step has human gates at specific risk points. Time to active account: from 3 days to 4 hours. Error rate: lower than the manual process because validation happens at every step.
The Mistakes We'd Warn You About
Building an agent when you need a simpler system. Agents are impressive. They're not always the right tool. Before you build an agent, make sure you understand what the human is currently doing in that workflow. Often, a simpler RAG query or a structured ETL pipeline is faster, cheaper, and more reliable. We've steered multiple clients away from agents when a simpler approach would give 90% of the value at 10% of the complexity.
No observability from day one. If you can't see what your agent is doing step by step, you cannot debug it, and you cannot improve it. Build observability before you build anything else. The cost of adding it later is much higher than the cost of building it in from the start.
Removing human-in-the-loop gates too early. We've seen teams remove approval gates in week 2 because the demo looked so good. Three months later, they're dealing with hundreds of incorrectly processed records or external communications sent without review. Leave the gate until the system has earned trust through sustained, measurable reliability.
Treating agents as black boxes. Every autonomous decision should be explainable. If you can't reconstruct exactly what the agent did and why, you don't have a production system — you have an expensive mystery. Audit trails aren't optional.
Where to Start
If you're building your first production agent:
Week 1: Single agent, 3 tools, simple task, extensive logging. Don't try to build the final system — build something you can learn from. Run 50 real examples and measure everything.
Weeks 2-3: Add the real failure cases. What happens when a tool fails? When input is ambiguous? When the step limit hits? Handle these explicitly before you polish the happy path.
Month 2: Move to LangGraph if you need state management or human gates. Instrument with a proper observability stack. Run in parallel with the manual process for at least 3 weeks before any displacement.
Month 3+: Scale and optimize. Now you know where latency comes from, which queries are hardest, where the model struggles. That's when caching, model routing, and specialized fine-tuning pay off.
We've built agentic systems for insurance, finance, legal, healthcare, and manufacturing. If you're evaluating whether an agent is the right approach for your workflow — or if you have an agent in production that's not behaving the way you expect — we'll give you a straight technical assessment in 30 minutes.