Alpha Notice: These docs cover the v1-alpha release. Content is incomplete and subject to change.For the latest stable version, see the v0 LangChain Python or LangChain JavaScript docs.
Observability is crucial for understanding how your agents behave in production. With LangChain’s create_agent(), you get built-in observability through LangSmith - a powerful platform for tracing, debugging, evaluating, and monitoring your LLM applications. Traces capture every step your agent takes, from the initial user input to the final response, including all tool calls, model interactions, and decision points. This enables you to debug your agents, evaluate performance, and monitor usage.

Prerequisites

Before you begin, ensure you have the following:

Enable tracing

All LangChain agents automatically support LangSmith tracing. To enable it, set the following environment variables:
export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>
You can get your API key from your LangSmith settings.

Quick start

No extra code is needed to log a trace to LangSmith. Just run your agent code as you normally would:
import { createAgent } from "@langchain/agents";

function sendEmail(to: string, subject: string, body: string): string {
    // ... email sending logic
    return `Email sent to ${to}`;
}

function searchWeb(query: string): string {
    // ... web search logic
    return `Search results for: ${query}`;
}

const agent = createAgent({
    model: "openai:gpt-4o",
    tools: [sendEmail, searchWeb],
    prompt: "You are a helpful assistant that can send emails and search the web."
});

// Run the agent - all steps will be traced automatically
const response = await agent.invoke({
    messages: [{ role: "user", content: "Search for the latest AI news and email a summary to john@example.com" }]
});
By default, the trace will be logged to the project with the name default. To configure a custom project name, see Log to a project.

Trace selectively

You may opt to trace specific invocations or parts of your application using LangSmith’s tracing_context context manager:
import langsmith as ls

# This WILL be traced
with ls.tracing_context(enabled=True):
    agent.invoke({"messages": [{"role": "user", "content": "Send a test email to alice@example.com"}]})

# This will NOT be traced (if LANGSMITH_TRACING is not set)
agent.invoke({"messages": [{"role": "user", "content": "Send another email"}]})

Log to a project

You can set a custom project name for your entire application by setting the LANGSMITH_PROJECT environment variable:
export LANGSMITH_PROJECT=my-agent-project
You can set the project name programmatically for specific operations:
import langsmith as ls

with ls.tracing_context(project_name="email-agent-test", enabled=True):
    response = agent.invoke({
        "messages": [{"role": "user", "content": "Send a welcome email"}]
    })

Add metadata to traces

You can annotate your traces with custom metadata and tags:
response = agent.invoke(
    {"messages": [{"role": "user", "content": "Send a welcome email"}]},
    config={
        "tags": ["production", "email-assistant", "v1.0"],
        "metadata": {
            "user_id": "user_123",
            "session_id": "session_456",
            "environment": "production"
        }
    }
)
tracing_context also accepts tags and metadata for fine-grained control:
with ls.tracing_context(
    project_name="email-agent-test",
    enabled=True,
    tags=["production", "email-assistant", "v1.0"],
    metadata={"user_id": "user_123", "session_id": "session_456", "environment": "production"}):
    response = agent.invoke(
        {"messages": [{"role": "user", "content": "Send a welcome email"}]}
    )
This custom metadata and tags will be attached to the trace in LangSmith.
To learn more about how to use traces to debug, evaluate, and monitor your agents, see the LangSmith documentation.