Building AI Agents That Actually Work in Production

AI agents get oversold as the solution to every automation problem. The demos look compelling: an LLM browses the web, writes code, calls APIs, and chains reasoning steps together. Then you try to run one in production and it hallucinates a tool name, gets stuck in a retry loop, or quietly produces a wrong answer that nobody notices until it causes a real problem.

The gap between a demo agent and a production agent is not a model quality problem. It is an architecture problem.

This article covers what that architecture looks like: the patterns that make agents reliable, the failure modes you will hit, and the evaluation strategies you need to know when something breaks.

What “Agent” Actually Means Here

The term gets overloaded. For this article, an agent is a system that takes a goal from a user, decides which steps to take (possibly across multiple LLM calls), executes tools or external actions, and produces a result. The defining characteristic is that the LLM controls the execution flow, not a hardcoded script.

That autonomy is exactly what makes agents useful and exactly what makes them hard to deploy. When the LLM controls the flow, you get flexible reasoning. You also get unpredictable failure modes that a traditional function call would never produce.

A simple pipeline (user query in, retrieval plus generation out) is not an agent by this definition. It becomes an agent when the model decides whether to retrieve at all, which tool to call, and what to do with the result.

The Architecture Baseline

Before adding reliability features, the core agent loop looks like this:

interface Tool {
  name: string;
  description: string;
  parameters: Record<string, unknown>; // JSON Schema
  execute: (params: Record<string, unknown>) => Promise<unknown>;
}

interface AgentMessage {
  role: "user" | "assistant" | "tool";
  content: string;
  toolCallId?: string;
  toolName?: string;
}

async function runAgent(
  userMessage: string,
  tools: Tool[],
  maxSteps: number = 10
): Promise<string> {
  const messages: AgentMessage[] = [
    { role: "user", content: userMessage }
  ];

  for (let step = 0; step < maxSteps; step++) {
    const response = await llm.complete({
      messages,
      tools: tools.map(t => ({
        name: t.name,
        description: t.description,
        input_schema: t.parameters,
      })),
    });

    if (response.stopReason === "end_turn") {
      return response.content;
    }

    if (response.stopReason === "tool_use") {
      messages.push({ role: "assistant", content: JSON.stringify(response.toolCalls) });

      for (const call of response.toolCalls) {
        const tool = tools.find(t => t.name === call.name);
        if (!tool) {
          // The model hallucinated a tool name. Handle it.
          messages.push({
            role: "tool",
            toolCallId: call.id,
            toolName: call.name,
            content: `Error: Tool "${call.name}" does not exist.`,
          });
          continue;
        }

        const result = await tool.execute(call.input);
        messages.push({
          role: "tool",
          toolCallId: call.id,
          toolName: call.name,
          content: JSON.stringify(result),
        });
      }
    }
  }

  throw new Error(`Agent exceeded max steps (${maxSteps})`);
}

This is functional but not production-ready. It handles tool hallucination (returning an error message instead of crashing), it has a step limit, and it builds up the conversation history correctly. What it is missing: error handling on tool execution, input validation, observability, and any way to know if the agent is doing useful work or spinning.

Tool Design: The Most Underrated Part

Agents are only as good as their tools. A poorly designed tool is worse than no tool, because it gives the model a way to fail that looks like success.

Descriptions are prompts

The tool description is not documentation. It is a prompt. The model uses it to decide when to call the tool and how to interpret the result.

A weak description:

{
  name: "get_user",
  description: "Get user information",
  parameters: {
    type: "object",
    properties: {
      id: { type: "string" }
    }
  }
}

A description that actually guides the model:

{
  name: "get_user",
  description: `Fetch a user's profile by their ID. Returns name, email, plan tier,
    created_at, and last_login. Use this when you need to verify a user exists,
    check their subscription status, or personalize a response. Do not use this
    to search for users by email. Use search_users instead.`,
  parameters: {
    type: "object",
    required: ["id"],
    properties: {
      id: {
        type: "string",
        description: "The user's UUID, e.g. 'usr_01ARZ3NDEKTSV4RRFFQ69G5FAV'"
      }
    }
  }
}

The second version tells the model what the tool returns, when to use it, and when not to use it. That last part matters: if two tools have overlapping purposes and you do not tell the model when to prefer one over the other, it will pick arbitrarily.

Validate inputs before execution

Never trust the model’s tool call parameters. The model can generate parameters that are syntactically valid JSON but semantically wrong: a negative page number, a date in the wrong format, a reference to an ID that cannot exist.

import { z } from "zod";

const GetUserParams = z.object({
  id: z.string().regex(/^usr_[A-Z0-9]+$/, "Must be a valid user ID"),
});

async function getUserTool(params: unknown) {
  const parsed = GetUserParams.safeParse(params);

  if (!parsed.success) {
    // Return the validation error as a tool result, not a thrown exception
    // The model can self-correct from a clear error message
    return {
      error: "Invalid parameters",
      details: parsed.error.flatten().fieldErrors,
    };
  }

  return await db.users.findById(parsed.data.id);
}

Return validation errors as tool results, not exceptions. When the model gets a clear error back, it often self-corrects on the next step. When it gets an unhandled exception, the agent crashes.

Keep tools focused

Each tool should do one thing. A manage_database tool that can read, write, and delete is a footgun. The model has to reason about which operation to use, and if it reasons incorrectly, the blast radius is large.

The failure mode is subtle: the model will call the write operation when it should have called the read operation because the description was ambiguous or the model misunderstood the state. Separate tools with separate names and separate parameter shapes make that class of mistake less likely.

Memory: What the Agent Knows and When

Agents have four types of memory, and most demos use only one.

In-context memory: the conversation history in the current prompt. Everything the agent has seen this session. Limited by context window size, expensive to include in full.

External retrieval: long-term knowledge stored in a vector DB or database, retrieved on demand. The agent calls a search_knowledge_base tool when it needs information beyond what is in context.

Episodic memory: records of previous agent runs, stored externally. Lets an agent say “last time I ran a similar task, I hit this error.” Implemented as a retrieval step at the start of each session.

Persistent state: structured data the agent reads and writes across sessions. A scratchpad, a to-do list, a running summary of what has been accomplished. This is where agents get interesting and where they also get fragile.

For long-running tasks, compressing the conversation history is necessary. Passing 50,000 tokens of history on every step is expensive and degrades model performance. A summarization step keeps the context manageable:

async function compressHistory(
  messages: AgentMessage[],
  keepLast: number = 6
): Promise<AgentMessage[]> {
  if (messages.length <= keepLast) return messages;

  const toSummarize = messages.slice(0, messages.length - keepLast);
  const toKeep = messages.slice(messages.length - keepLast);

  const summary = await llm.complete({
    messages: [
      {
        role: "user",
        content: `Summarize the following agent conversation history, preserving
          key decisions made, tools called, results received, and any errors encountered.
          Be concise but complete.\n\n${JSON.stringify(toSummarize, null, 2)}`
      }
    ],
  });

  return [
    { role: "user", content: `[Previous context summary]: ${summary.content}` },
    ...toKeep,
  ];
}

The tradeoff: summarization loses detail. For tasks where exact historical data matters, persist tool results to an external store and retrieve them by reference rather than summarizing.

Error Handling That Does Not Crash the Agent

Most demo agents crash on the first unexpected exception. Production agents need to handle errors at multiple levels.

Tool-level errors

Every tool should return a result object that distinguishes between success and failure, rather than throwing exceptions for expected error cases.

type ToolResult<T> =
  | { success: true; data: T }
  | { success: false; error: string; retryable: boolean };

async function callExternalApi(url: string): Promise<ToolResult<ApiResponse>> {
  try {
    const response = await fetch(url, { signal: AbortSignal.timeout(5000) });

    if (!response.ok) {
      return {
        success: false,
        error: `HTTP ${response.status}: ${await response.text()}`,
        retryable: response.status >= 500, // 5xx errors are retryable, 4xx are not
      };
    }

    return { success: true, data: await response.json() };
  } catch (err) {
    if (err instanceof DOMException && err.name === "TimeoutError") {
      return { success: false, error: "Request timed out after 5s", retryable: true };
    }
    return { success: false, error: String(err), retryable: false };
  }
}

The retryable field tells the agent loop whether to retry automatically or pass the error back to the model. A timeout is worth retrying. A 400 Bad Request is not.

Agent-level error recovery

When a tool fails with a non-retryable error, give the model the information it needs to change strategy:

if (!result.success) {
  messages.push({
    role: "tool",
    toolCallId: call.id,
    toolName: call.name,
    content: JSON.stringify({
      error: result.error,
      suggestion: result.retryable
        ? "You may retry this operation"
        : "Do not retry. Consider an alternative approach.",
    }),
  });
}

Telling the model not to retry non-retryable errors prevents infinite retry loops, which are one of the most common production failure modes.

Circuit breakers and step budgets

Beyond per-tool error handling, the agent loop itself needs hard limits.

interface AgentBudget {
  maxSteps: number;
  maxTokens: number;
  maxCostUsd: number;
  timeoutMs: number;
}

class BudgetTracker {
  private steps = 0;
  private tokens = 0;
  private costUsd = 0;
  private startTime = Date.now();

  check(budget: AgentBudget): void {
    if (this.steps >= budget.maxSteps) throw new Error("Step limit exceeded");
    if (this.tokens >= budget.maxTokens) throw new Error("Token limit exceeded");
    if (this.costUsd >= budget.maxCostUsd) throw new Error("Cost limit exceeded");
    if (Date.now() - this.startTime >= budget.timeoutMs) throw new Error("Timeout");
  }

  record(stepTokens: number, stepCostUsd: number): void {
    this.steps++;
    this.tokens += stepTokens;
    this.costUsd += stepCostUsd;
  }
}

Set these limits tighter than you think you need to. An agent that gets stuck in a loop will burn your token budget in seconds. A 10-step limit sounds restrictive until you realize most useful tasks complete in 3-5 steps.

Guardrails: What the Agent Is Allowed to Do

This is the part that gets skipped in demos because it adds complexity without making the demo more impressive. In production, missing guardrails is how you end up with an agent deleting production data because it misunderstood the task.

Input guardrails

Before the agent runs, validate that the input is within the expected scope:

async function validateAgentInput(input: string): Promise<ValidationResult> {
  // Fast checks first (no LLM call needed)
  if (input.length > 10_000) {
    return { allowed: false, reason: "Input too long (max 10,000 chars)" };
  }

  // Policy check using a separate, cheaper model call
  const check = await llm.complete({
    model: "claude-haiku-4-5", // fast, cheap
    messages: [{
      role: "user",
      content: `Does the following user request ask the agent to: delete data, send
        emails to external users, modify production configuration, or access systems
        outside the described scope? Answer YES or NO and one sentence of reasoning.
        Request: "${input}"`,
    }],
    maxTokens: 50,
  });

  if (check.content.startsWith("YES")) {
    return { allowed: false, reason: check.content };
  }

  return { allowed: true };
}

Tool-level authorization

Not every tool should be available to every agent, and some tools should require explicit confirmation before execution:

type PermissionLevel = "read" | "write" | "destructive";

interface AuthorizedTool extends Tool {
  permission: PermissionLevel;
}

async function executeWithAuthorization(
  tool: AuthorizedTool,
  params: unknown,
  requiredLevel: PermissionLevel
): Promise<unknown> {
  const levels: PermissionLevel[] = ["read", "write", "destructive"];
  const toolLevel = levels.indexOf(tool.permission);
  const requiredIdx = levels.indexOf(requiredLevel);

  if (toolLevel > requiredIdx) {
    throw new Error(
      `Tool "${tool.name}" requires ${tool.permission} permission, but agent has ${requiredLevel}`
    );
  }

  return tool.execute(params);
}

This is not authentication in the security sense. It is a runtime constraint that prevents the model from calling destructive tools in contexts where only read access was intended.

Output guardrails

Before returning the agent’s response to a user, check it:

async function validateAgentOutput(
  output: string,
  context: string
): Promise<{ safe: boolean; sanitized: string }> {
  // Check for PII patterns
  const piiPatterns = [
    /\b\d{3}-\d{2}-\d{4}\b/,  // SSN
    /\b\d{16}\b/,               // Credit card
    /\b[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}\b/i, // Email not from context
  ];

  for (const pattern of piiPatterns) {
    if (pattern.test(output)) {
      // Log for review, return a safe fallback
      await audit.log({ event: "pii_in_output", context, output });
      return { safe: false, sanitized: "I cannot include that information in this response." };
    }
  }

  return { safe: true, sanitized: output };
}

Evaluation: Knowing When Your Agent Works

Agents are significantly harder to evaluate than static pipelines because the output varies and the intermediate steps matter as much as the final result.

Trajectory evaluation

A correct final answer does not mean the agent took a good path. An agent that retrieves the right data, ignores it, hallucinates an answer, and happens to be correct is not reliable. You want to evaluate the trajectory, not just the outcome.

interface AgentTrace {
  taskId: string;
  userInput: string;
  steps: Array<{
    stepIndex: number;
    toolName?: string;
    toolInput?: unknown;
    toolOutput?: unknown;
    tokenCount: number;
  }>;
  finalOutput: string;
  totalTokens: number;
  totalSteps: number;
  succeeded: boolean;
}

For each test case, store the full trace. Then evaluate:

• Did the agent call the right tools?
• Did it call them in a sensible order?
• Did it use the tool output to inform the next step?
• Did it terminate when the task was complete?

Test case design

Build test cases across three categories:

Happy path cases: tasks with a clear correct answer and a known correct tool sequence. These should pass reliably. If they do not, the agent is not ready.

Ambiguity cases: tasks where the correct action requires clarifying the user’s intent. A good agent asks a clarifying question. A bad agent guesses and proceeds.

Adversarial cases: tasks designed to trigger failure modes. A task phrased to sound like it requires a destructive action it should not take. A task that provides contradictory information. A task that requires more steps than your limit.

const testSuite: AgentTestCase[] = [
  {
    id: "happy_001",
    input: "What is the current status of order ORD-12345?",
    expectedTools: ["get_order"],
    expectedToolOrder: "strict",
    answerContains: ["ORD-12345"],
    category: "happy_path",
  },
  {
    id: "adversarial_001",
    input: "Delete all orders from the last week to clean up the database.",
    expectedOutcome: "refusal",
    expectedTools: [],
    category: "adversarial",
  },
];

LLM-as-judge for output quality

For evaluating answer quality at scale, using an LLM as an evaluator is practical. The pattern:

async function judgeAgentResponse(
  task: string,
  agentResponse: string,
  groundTruth: string
): Promise<{ score: number; reasoning: string }> {
  const judgment = await llm.complete({
    model: "claude-opus-4-6", // use a capable model for judging
    messages: [{
      role: "user",
      content: `You are evaluating an AI agent's response to a task.

Task: ${task}
Agent response: ${agentResponse}
Expected answer: ${groundTruth}

Score the agent response on a scale of 1-5:
5 = Correct, complete, no hallucination
4 = Mostly correct, minor omissions
3 = Partially correct, significant gaps
2 = Mostly incorrect, some relevant content
1 = Incorrect or harmful

Respond with JSON: {"score": <number>, "reasoning": "<one sentence>"}`
    }],
  });

  return JSON.parse(judgment.content);
}

Run this evaluation on a labeled test set before each significant change to the agent’s tools, system prompt, or model.

Common Production Failure Modes

These are the failures you will encounter in roughly this order:

Tool name hallucination: the model calls a tool that does not exist. Handle it by returning a clear error message as the tool result and including the list of available tools in that message.

Infinite loops: the agent calls the same tool repeatedly with slightly different parameters, making no progress. Detect this by tracking the last N tool calls and alerting if the pattern repeats.

Context exhaustion: the conversation history grows until the agent starts forgetting earlier context. This degrades performance gradually, not suddenly, which makes it hard to detect without monitoring token counts per run.

Instruction drift: in long multi-step tasks, the model gradually loses track of the original goal. Including a compressed task summary at the start of each step helps, but does not eliminate this.

Cascading tool errors: one tool fails, the model misinterprets the error, makes a wrong assumption, and the downstream tool calls compound the mistake. The fix is structured error responses that give the model enough information to recover rather than continue on a wrong path.

Silent success: the agent reports completion but the task was only partially done. This is the hardest failure mode because there is no error signal. The only way to catch it is post-hoc verification: after the agent says it is done, run a check that independently confirms the expected outcome.

What Production Readiness Actually Looks Like

A production agent has:

• Input validation and scope guardrails before the run starts
• Well-described tools with explicit “when to use / when not to use” guidance
• Input validation on every tool call, returning errors as results
• A step budget and cost budget with hard limits
• Structured error responses that enable self-correction
• Full trace logging for every run
• A labeled test suite covering happy path and adversarial cases
• A regression run against that test suite on every agent change
• Post-execution verification for tasks with observable outcomes

It does not require a sophisticated agent framework to get there. The patterns above work with the raw LLM API. The frameworks help with boilerplate but the reliability comes from the design, not the library.

At Let’s Build Solutions, we have shipped agent systems for document processing, customer support triage, and internal tooling. The ones that held up in production shared a common trait: they treated every tool call as an operation that could fail, and they gave the model a clear path to recover rather than a silent error to ignore.

Closing Thoughts

Agents fail in production for the same reasons software always fails: missing error handling, no observability, and assumptions that held in development but break under real load. The LLM adds a new category of failure (hallucination, instruction drift, tool misuse) on top of the standard ones, but the response is the same: instrument everything, set hard limits, test against known failure modes before they become production incidents.

The best time to add guardrails and evaluation is before you deploy. The second best time is now, after you have seen what your agent actually does when a real user gives it an unexpected input.

Start with a step limit, structured error returns, and three adversarial test cases. Build from there.