Observability and debugging for LangChain agents

Who this is for and what you will be able to do

This guide is for developers who have built a first LangChain agent and want to see what it actually does at each step. After reading it, you should be able to turn on tracing, run an agent, and find in LangSmith which tools it called and how it interacted with the model.

What tracing and LangSmith are

Agents built with create_agent in Python, or createAgent in TypeScript, automatically support tracing through LangSmith^[1]. LangSmith is a platform for capturing, debugging, evaluating, and monitoring agent behavior^[1].

A trace records every step of an agent's execution, from the initial user input to the final response. That includes all tool calls, model interactions, and decision points^[1]. You can use this data to debug issues, compare performance across different inputs, and monitor usage patterns in production^[1].

Prerequisites

Before you start, you need two things^[1]:

1. A LangSmith account. You can sign up for free or log in at smith.langchain.com.
2. A LangSmith API key, created by following the "Create an API key" guide^[1].

Enable tracing with environment variables

To enable tracing, set four environment variables: LANGSMITH_AGENT_ID, LANGSMITH_AGENT_ENVIRONMENT, LANGSMITH_TRACING, and LANGSMITH_API_KEY. The example sets LANGSMITH_AGENT_ENVIRONMENT to local and LANGSMITH_TRACING to true^[1]. In a shell, the commands look like this:

export LANGSMITH_AGENT_ID="<your-agent-id>"
export LANGSMITH_AGENT_ENVIRONMENT="local"
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>

Replace <your-agent-id> and <your-api-key> with your own values. After that, no extra logging code is needed in your agent^[1].

Your first trace

The Python example below defines two tools, send_email and search_web, creates an agent with create_agent, and runs it on one task^[1]:

from langchain.agents import create_agent


def send_email(to: str, subject: str, body: str):
    """Send an email to a recipient."""
    # ... email sending logic
    return f"Email sent to {to}"

def search_web(query: str):
    """Search the web for information."""
    # ... web search logic
    return f"Search results for: {query}"

agent = create_agent(
    model="gpt-6.1-sol",
    tools=[send_email, search_web],
    system_prompt="You are a helpful assistant that can send emails and search the web."
)

# Run the agent - all steps will be traced automatically
response = agent.invoke({
    "messages": [{"role": "user", "content": "Search for the latest AI news and email a summary to john@example.com"}]
})

The two tool functions contain placeholder comments, email sending logic and web search logic, so you need to supply the real implementations. Once agent.invoke runs, every step of that task is traced automatically, and the traces appear in the destination you configured during setup^[1].

The TypeScript version follows the same pattern. It imports createAgent from langchain, defines two functions as tools, and calls agent.invoke^[1].

What you can see in a trace

A trace shows the full run in order: the user's request, the model's decision to call a tool, the tool's result, and the final reply to the user^[1]. When something goes wrong, you can check each step and tell whether the model chose the wrong tool or a tool returned an unexpected result.

The page gives Python and JavaScript sections side by side. The concepts are the same, and only the syntax differs^[1].

For debugging, the advantage is that you do not need to scatter print statements through your code or guess why the agent chose a particular tool. Open the trace for a run and follow it step by step through each tool call and model interaction. When a result is not what you expected, find the step where things went wrong first. Then decide whether the fix belongs in the prompt, in the tool description, or in the tool implementation^[1].

Limits and common questions

• The examples show only how to enable tracing. The page does not cover filtering traces or setting up evaluations and alerts, so those topics belong in LangSmith's own documentation^[1].
• Tracing depends on your API key. If no traces appear, first check that LANGSMITH_TRACING is true, and that the key is exported in the same shell that runs your agent^[1].
• The destination for traces is determined by the configuration you chose during setup^[1].

Next steps

To learn more about LangSmith concepts and how to analyze traces, follow the links from this page to the LangSmith observability documentation^[1].

Adapted from LangChain's documentation page *LangSmith Observability*^[1], released under the MIT License.