Log traces to an agent

​

Prerequisites

• An agent-based workspace. Agent-based workspaces are available on LangSmith Cloud. They are not available on self-hosted LangSmith. In an agent-based workspace, sending traces to an agent is already on, and you have no setting to change. To check which kind of workspace you have, look at the control at the top left. In an agent-based workspace, it names your workspace. In a project-based workspace, it shows the LangSmith logo, and sending traces to an agent is off.
• An existing agent. Create the agent once in the target workspace before running the tracing examples. The examples use the identifier checkout. Replace it with your own.
• An API key from that workspace. See create an API key.
• The SDK. Sending traces to an agent needs langsmith>=0.14.9 in Python, langsmith@>=0.11.0 in TypeScript, v0.28.0 or later of github.com/langchain-ai/langsmith-go in Go, or 0.1.0-beta.26 or later of com.langchain.smith:langsmith-java in Java:
  uv

  pip

  npm

  go

  Java/Kotlin (Gradle)

  uv add "langsmith>=0.14.9"
  

​

Send traces to an agent

• Agent ID: The agent’s identifier, which the browser address bar carries and the ID field on the agent’s Overview copies. It is not the display name. A display name is a separate, editable value that does not have to match the identifier, so read the identifier from the agent rather than deriving it from what the agent is called. For the rules an identifier must follow, see Identifier rules. Create the agent before using its identifier. An archived agent still holds its identifier, and LangSmith rejects a run sent to it with a 409.
• Environment: The environment the run belongs to, and one of local, development, staging, or production. Environment names are not case-sensitive, and they map to the Local, Development, Staging, and Production labels in the UI. There is no default, because neither the agent nor the environment names a destination alone.

​

Using environment variables

export LANGSMITH_TRACING=true
export LANGSMITH_API_KEY=<your-api-key>
export LANGSMITH_AGENT_ID=checkout
export LANGSMITH_AGENT_ENVIRONMENT=local

​

Using code

import langsmith as ls
from langsmith import traceable


@traceable(address=ls.agent_address("checkout", "local"))
def handle_order(order_id: str) -> dict:
    return {"order_id": order_id, "status": "charged"}

import langsmith as ls
from langsmith import traceable, tracing_context


@traceable
def handle_order(order_id: str) -> dict:
    return {"order_id": order_id, "status": "charged"}


with tracing_context(address=ls.agent_address("checkout", "local")):
    handle_order("A-1")

import { AgentAddress } from "langsmith";
import { traceable } from "langsmith/traceable";

const handleOrder = traceable(
  async (orderId: string) => ({ orderId, status: "charged" }),
  { name: "handle_order", address: new AgentAddress("checkout", "local") },
);

import com.langchain.smith.address.AgentAddress;
import com.langchain.smith.tracing.TraceConfig;
import com.langchain.smith.tracing.Tracing;
import java.util.Map;
import java.util.function.Function;

public class TraceAgentExample {
  public static void main(String[] args) {
    Function<String, Map<String, String>> handleOrder =
        Tracing.traceFunction(
            orderId -> Map.of("order_id", orderId, "status", "charged"),
            TraceConfig.builder()
                .name("handle_order")
                .address(new AgentAddress("checkout", "local"))
                .build());

    handleOrder.apply("A-1");
  }
}

package main

import (
	"fmt"
	"time"

	"github.com/google/uuid"
	"github.com/langchain-ai/langsmith-go"
)

func main() {
	agent, err := langsmith.NewAgentAddress("checkout", "local")
	if err != nil {
		panic(err.Error())
	}
	client := langsmith.NewClient()

	id := uuid.New()
	start := time.Now().UTC()
	order := fmt.Sprintf("%s%06dZ%s", start.Format("20060102T150405"), start.Nanosecond()/1000, id)

	if err := client.CreateRun(&langsmith.RunCreate{
		ID:          id,
		TraceID:     id,
		Name:        "handle_order",
		RunType:     "chain",
		StartTime:   start,
		DottedOrder: order,
		Address:     agent,
		Inputs:      map[string]any{"order_id": "A-1"},
	}); err != nil {
		panic(err.Error())
	}
	if err := client.UpdateRun(&langsmith.RunUpdate{
		ID:          id,
		TraceID:     id,
		DottedOrder: order,
		EndTime:     time.Now().UTC(),
		Outputs:     map[string]any{"status": "charged"},
	}); err != nil {
		panic(err.Error())
	}
	client.Close()
}

​

Using OpenTelemetry

​

Send your first trace

​

Query an agent environment

​

Remove conflicting destination settings

• Agent variables and legacy variables together: Not allowed. If you set the agent variables and also LANGSMITH_PROJECT, LANGCHAIN_PROJECT, or LANGCHAIN_SESSION, the trace has two destinations, and the SDK does not pick one. It logs a warning when the client starts, and it does not trace a call unless code names the destination. If you pass both address and project_name in one call, the SDK raises an error and sends nothing: LangSmithUserError from @traceable or tracing_context() in Python, or an Error from traceable in TypeScript. LangSmith also rejects an ingestion request that supplies both address types.
• A project_name override in code: Overrides the agent variables. Passing project_name to @traceable or tracing_context() in Python, or in the traceable config in TypeScript, traces the run to the override destination and ignores the agent variables, without an error. This is what lets an evaluation use its own experiment destination while the agent variables stay set for the rest of the process.

​

Troubleshooting

​

See also

• Agent Registry
• Agent environments
• Configure legacy integrations
• Resolve an agent environment
• Trace with OpenTelemetry
• Observability concepts