• TRACE
  • ERROR
  • INPUT
  • HUMAN

How to debug failed agent runs with your AI

Connect LangSmith to your agent to inspect execution traces. Once connected, your AI can pull specific run data to find where your logic broke.

Ask AI about this page

Short answer

How can I use my AI to find out why an agent run failed?

Your AI uses LangSmith to fetch specific error traces and execution details. It identifies the exact step where the workflow failed, providing you with the context needed to fix it.

Debugging outcomes.

Where your investigation leads.

The AI categorizes the data it finds into clear outcomes.

TRACE

Full execution paths

The AI pulls the sequence of events for a run. You see exactly which tools were called and what they returned.

ERROR

Root cause identification

The AI isolates the specific error message. You get the exact reason the execution stopped.

INPUT

Data validation

The AI checks the inputs sent to each step. You find where malformed data caused a failure.

HUMAN

Manual fixes needed

The AI flags runs that require you to change your prompts or tool logic. These stay in your hands to resolve.

The workflow

What your AI does when a run fails.

The AI acts as a forensic tool for your LangSmith data.

  1. Locate the failure

    The AI scans your recent history to find the specific failed execution you're asking about.

    langsmith_list_runs

  2. Retrieve the trace

    The AI pulls the granular details and metadata for that specific failed run.

    langsmith_get_run

  3. Analyze the error

    The AI compares the expected output against the actual error returned by the system.

    langsmith_get_run

  4. Summarize the fix

    The AI explains why the run failed and suggests how to adjust your agent's logic.

    langsmith_get_run

Try it

Copy these to start.

Use these prompts to begin your investigation.

Starting points

Swap the bracketed text with your actual run IDs or error descriptions.

LangSmith Connector

You're all set. Choose your MCP client and follow the setup instructions.

Connector linkhttps://edge.vinkius.com/vk_preview_JBueIzhraYvzf2S9aR0UP9Q6bjldfIBgmwxTvRHt/mcp

Claude Desktop

Follow the steps below to connect in seconds.

  1. 1In Claude Desktop, open Settings → Connectors.
  2. 2Click “Add custom connector” and paste the connector link above as the remote MCP server URL.
  3. 3Click Add and start a new chat — LangSmith capabilities are ready to use.
Configuration · claude_desktop_config.jsonCopy
{
  "mcpServers": {
    "langsmith-mcp": {
      "url": "https://edge.vinkius.com/vk_preview_JBueIzhraYvzf2S9aR0UP9Q6bjldfIBgmwxTvRHt/mcp"
    }
  }
}
Copy into chat04

  • Find the last failed run in LangSmith and tell me why it crashed.

  • Get the details for run ID 'run_123abc' and explain the error in the tool call.

  • List all failed runs from the last hour so I can see the pattern.

  • Look at the trace for run 'run_456def' and tell me what the input was for the final step.

  • Claude
  • ChatGPT
  • Cursor
  • VS Code
  • Windsurf
  • Claude Code
  • JetBrains
  • Cline

Start here

Connect LangSmith once, then ask.

Provide your LangSmith API key to get started. Your credentials stay encrypted, and the full walkthrough lives on the Connector page.

Connect LangSmith to your AI

FAQ

How this task behaves.

  • 01

    Can the AI fix my code automatically?

    No. The AI identifies the error and suggests a fix, but you must manually update your code.

  • 02

    Can the AI delete runs from LangSmith?

    No. This MCP only has permissions to read and list run data.

  • 03

    How does the AI find the right run to debug?

    It uses the list tool to scan your history and then pulls the specific trace you've identified.

  • 04

    Can the AI create new traces in LangSmith?

    No. The AI is strictly for inspecting and analyzing existing execution data.

  • 05

    Does the AI see my entire LangSmith project?

    The AI can access any run it has permission to list and retrieve based on your API key.

  • More questions about LangSmith? The Connector page answers them. See everything the LangSmith Connector can do

Connect LangSmith to Claude, Cursor, ChatGPT & more