Log traces to an agent

​

Addressing variables

• LANGSMITH_AGENT_ID: The agent to address. The value is the agent’s identifier, which the browser address bar carries and the ID field on the agent’s Overview copies. It is sent with every run.
• LANGSMITH_AGENT_ENVIRONMENT: The environment the run belongs to. Required alongside the agent, and one of local, development, staging, or production. Use the lowercase form, which maps 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. If only one of the two variables is set, the SDK logs a warning and leaves the call untraced instead of picking an environment for you, so nothing reaches LangSmith.

​

Addressing arguments

​

Examples

import langsmith as ls
from langsmith import traceable

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

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="lrn:agents/checkout/environments/production"):
    handle_order("A-1")

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

const handleOrder = traceable(
  async (orderId: string) => ({ orderId, status: "charged" }),
  { name: "handle_order", address: address.agent("checkout", "production") },
);

​

Send your first agent-addressed trace

uv add "langsmith>=0.14.4"

pip install -U "langsmith>=0.14.4"

npm install "langsmith@>=0.10.8"

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

​

Addressing modes are mutually exclusive

• An agent and a project together are 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 to @traceable or tracing_context() in one call, the SDK raises LangSmithUserError and sends nothing. If a run with both an address 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() 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.

​

Addressing an agent that does not exist

​

When runs stop being accepted

​

See also

• Agents
• Agent environments
• Log traces to a specific project
• Observability concepts