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 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.10.9 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. If no agent in the workspace uses the identifier you send, LangSmith creates that agent the first time you send a trace to it, so you do not have to create it in advance. Creating an agent this way requires the projects:create permission. Without it, LangSmith rejects the run with a 403. An archived agent still holds its identifier, so LangSmith rejects a run sent to it with a 409 instead of creating a new agent. Send that agent’s traces to a different identifier. The Overview of an agent created this way does not show deployment details.
• 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=production

​

Using code

import langsmith as ls
from langsmith import traceable


@traceable(address=ls.agent_address("checkout", "production"))
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", "production")):
    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", "production") },
);

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", "production"))
                .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", "production")
	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

​

Find an agent’s project

​

Send to an agent or a project, not both

• An agent and a project 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. If a run that names both an agent and a project reaches LangSmith, LangSmith rejects it.
• A project named 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 that project and ignores the agent variables, without an error. This is what lets an evaluation set its own project while the agent variables stay set for the rest of the process.

​

Troubleshooting

​

See also

• Agents
• Agent environments
• Log traces to a specific project
• Find an agent’s project
• Trace with OpenTelemetry
• Observability concepts