Trace your first agent run

Atlan Trident shows what an agent did through traces: one trace per run, made of spans for each step. Without tracing, a run leaves no evidence that the Registry can attribute to your agent. In this lesson, you initialize the tracing client, record a sample run, flush the trace, and find the run under your agent in Atlan Trident. The example records supplied model, usage, and cost values; it does not call a model. The SDK writes a session record for the run, and that record links the trace to your agent.

At the end of this lesson: one trace named handle-ticket, with a chat child span carrying model, tokens, and cost, is stored in your workspace. Its session appears under your agent in Atlan Trident.

Before you begin

Before you start, make sure you have:

SDK with tracing: Installed for your language, including the tracing extra in Python. See Install atlanai SDK.
API key: An Atlan API key. Load it from your environment or secret store, and never commit it. To get one, see Send bearer token.
Workspace ID: The workspace the traces belong to. In the web app or Atlan Trident Desktop, open the workspace and select Copy workspace ID from the More actions (⋯) menu at the top of the page. Exporting to an Atlan endpoint without a workspace raises at init(), because those traces would be unattributable.
Agent ID: The ID of a registered agent, starting with agent_. Without it the trace still exports, but the SDK writes no session record, so the run does not appear under an agent. To register one, see Register your first Agent.

Prepare your shell

This lesson reads three settings from the environment. Export them in the shell that runs your code:

export ATLAN_API_KEY="<your-api-key>"
export ATLAN_WORKSPACE_ID="<your-workspace-id>"
export ATLAN_AGENT_ID="<your-agent-id>"  # the agent_... ID from the Register your first Agent lesson

Trace one run

The work is three actions: initialize the client once, trace the run, and flush before the process exits. The trace is not visible in Atlan Trident until the flush completes.

Initialize client

Call init() once, as early as your process allows. Calls with the same credential, destination, workspace, service name, and subject reuse the client. init() reads ATLAN_API_KEY, ATLAN_WORKSPACE_ID, ATLAN_AGENT_ID, and the optional ATLAN_BASE_URL from the environment.The service name is required. It labels your process in traces. It does not choose the Registry agent: a trace belongs to the identity whose API key sent it, so use the agent’s own key from Settings > Identity on its profile. ATLAN_AGENT_ID names the agent so the SDK writes a session record for each run, which scoring needs. See How trace attribution works.

Python
TypeScript

import atlanai.tracing as atlan

client = atlan.init(service_name="support-rover")

import * as atlan from "@atlanai/sdk/tracing";

const client = atlan.init({ serviceName: "support-rover" });

Once a client exists, everything instrumented with OpenTelemetry in the process exports through the same pipeline. If init() logs “tracing disabled” or raises AtlanConfigError, see init() disables tracing and AtlanConfigError.

Trace run

Wrap the work in a span. Inside propagate_attributes, every span started in scope carries the same session ID, including spans from third-party instrumentation you do not control. The session ID groups the spans of one run, and the SDK writes one session record per session ID, named trace- followed by the ID.Record usage and cost on the span that spent them. Here, the chat span stands for a model call.

Python
TypeScript

with atlan.propagate_attributes(session_id="ticket-4821"):
    with client.start_as_current_span("handle-ticket", as_type="task"):
        with client.start_as_current_span("chat", as_type="llm") as generation:
            generation.update(
                model="claude-sonnet-5",
                provider="anthropic",
                usage={"input_tokens": 1200, "output_tokens": 340},
                cost={"input": 0.0036, "output": 0.0051},
            )

await atlan.propagateAttributes({ sessionId: "ticket-4821" }, async () => {
  await client.startAsCurrentSpan("handle-ticket", { asType: "task" }, async () => {
    await client.startAsCurrentSpan("chat", { asType: "llm" }, async (generation) => {
      generation.update({
        model: "claude-sonnet-5",
        provider: "anthropic",
        usage: { input_tokens: 1200, output_tokens: 340 },
        cost: { input: 0.0036, output: 0.0051 },
      });
    });
  });
});

The root span is handle-ticket. Its child chat span holds the model, provider, token usage, and cost.

Flush before exit

Long-lived services batch and export automatically. A short-lived process, such as a script, a job, or a serverless invocation, must flush, or the last batch is lost. flush() raises an error if the export failed, so a clean return means the export request was accepted.

Python
TypeScript

client.flush()

await client.flush();

Confirm trace in Atlan Trident

A clean flush proves that Atlan accepted the export request. It does not prove that the trace is visible in the workspace and under the agent you expect. Check both in Atlan Trident:

Select the workspace that matches ATLAN_WORKSPACE_ID, not another workspace your key can also reach.
Press ⌘K and search for your agent, then select it to open its profile.
Open Sessions and find the session for ticket-4821. Its record name is trace-ticket-4821.
Open Usage and select the matching run in Recent runs. Confirm the handle-ticket trace with its chat child span, and the recorded model, tokens, and cost.

If nothing appears, set ATLAN_DEBUG=true and run again. Debug mode logs the export decision and switches to per-span export, which surfaces a rejected batch immediately instead of at the next flush interval. For attribution problems, see Trace errors.

What you have accomplished

A trace for one run is stored in your workspace. The SDK wrote a session record for it, so the run appears under your agent in Atlan Trident, with model, tokens, and cost recorded on the chat span. If the export or the session record does not appear, see Install and setup errors.

What’s next

Create spans for agent run: Add observation types, wrap functions with observe, and derive deterministic trace IDs.

Get started

References

Troubleshoot

Trace your first agent run

Before you begin

Prepare your shell

Trace one run

What you have accomplished

What’s next