How do I track errors in an AI agent in production?

Why agent failures are hard to debug from logs

• The crash is often several steps after the cause: a tool returned bad data, the model acted on it, and a later tool threw.
• One session interleaves model calls, tool calls and retries, so its log lines are spread between other sessions.
• The same exception can come from different tools, and without the tool name every one of them looks alike.

What to record with each error

• Agent context: agent name and version, session id, the tool being called and the action (for example tool_call or plan).
• Breadcrumbs: one per model call and per tool call, with a short summary of the input and whether it succeeded. The SDK keeps the last 100.
• The release, so you can tell whether a new prompt or model version started the failures.
• The exception itself, with its stack trace. Uncaught exceptions are captured automatically once the SDK is initialized.

Node.js and TypeScript

import runheed from 'runheed';

runheed.init({ dsn: process.env.RUNHEED_DSN!, environment: 'production', release: 'support-agent@1.4.0' });

export async function callTool(sessionId: string, tool: string, input: unknown) {
  runheed.setAgent({ name: 'support-agent', version: '1.4.0', sessionId, toolName: tool, action: 'tool_call' });
  runheed.addBreadcrumb({ category: 'tool', message: `call ${tool}`, level: 'info' });
  try {
    const result = await tools[tool](input);
    runheed.addBreadcrumb({ category: 'tool', message: `${tool} ok`, level: 'info' });
    return result;
  } catch (err) {
    // Pass the session and tool as extra too: the agent context is per process,
    // so a server running many sessions at once should not rely on it alone.
    runheed.captureException(err as Error, { sessionId, tool });
    throw err;
  }
}

Python

import os, runheed

runheed.init(dsn=os.environ["RUNHEED_DSN"], environment="production", release="support-agent@1.4.0")

def call_tool(session_id: str, tool: str, args: dict):
    runheed.set_agent(name="support-agent", version="1.4.0", session_id=session_id, tool_name=tool, action="tool_call")
    runheed.add_breadcrumb(message=f"call {tool}", category="tool")
    try:
        result = TOOLS[tool](**args)
        runheed.add_breadcrumb(message=f"{tool} ok", category="tool")
        return result
    except Exception as e:
        runheed.capture_exception(e, extra={"session_id": session_id, "tool": tool})
        raise

Python's logging module is captured as breadcrumbs by default, so log lines your agent already writes show up in the trail before the error.

Keep prompts and user data out of the report

Runheed stores only what your code sends. Summarize tool inputs in breadcrumbs instead of attaching whole prompts, and use the beforeSend (before_send) hook to edit or drop any event before it leaves your app. Secret request headers are redacted on arrival. The details are on is it safe.

Read it back with your coding agent

Connect Claude Code or Cursor and ask "which tool fails most in the support agent this week?" or "show the breadcrumbs for the newest error in session 8f2c". runheed_get_error returns the agent context with the stack trace, and runheed_get_error_context returns the whole session trail. Setup for each client is under Connect your agent.