Create spans for agent run

SDK 0.6.0 atlanai SDK adds observation types to ordinary OpenTelemetry spans, so a step reads as a model call or a tool call instead of an untyped span. Use this guide to instrument an agent run by hand, with typed spans, model usage, cost, and failures. To trace a function without restructuring it, use Wrap functions with observe; for a framework, use Agent frameworks.

Before you begin

Before you start, make sure you have:

SDK: atlanai SDK installed with tracing, as in Install atlanai SDK.
Tracing: init configured and exporting, as in Trace your first agent run.

Create span

start_as_current_span (Python) or startAsCurrentSpan (TypeScript) opens a span, makes it the active parent for anything started inside, and closes it on exit.

Python
TypeScript

from atlanai.tracing import init

client = init(service_name="support-agent")

with client.start_as_current_span("summarize-thread", as_type="task") as span:
    span.update(input={"thread_id": "ticket-4821"})
    result = summarize(thread)
    span.update(output=result)

import { init } from "@atlanai/sdk/tracing";

const client = init({ serviceName: "support-agent" });

await client.startAsCurrentSpan("summarize-thread", { asType: "task" }, async (span) => {
  span.update({ input: { threadId: "ticket-4821" } });
  const result = await summarize(thread);
  span.update({ output: result });
});

For a detached span whose parent is not the active context, such as a framework tracking its own run tree or a child of a remote parent, use start_span or startSpan. End detached spans explicitly. A span that covers work begun earlier, such as a model call an integration sees only when its first message arrives, takes start_time (Python, epoch nanoseconds, as from time.time_ns()) or startTime (TypeScript, any OpenTelemetry TimeInput).

Set observation type

Pass as_type (Python) or asType (TypeScript) to classify the span. Atlan Trident uses the type to decide how to render the step and which metrics apply.

Type	Use for
`task`	A unit of work. The usual root span and the default.
`llm`	A model call. Carries model, provider, usage, and cost.
`tool`	A call to a tool or external system.
`function`	An internal function worth showing as its own step.
`session`	A conversation or long-running interaction.
`turn`	One exchange inside a session.
`score`	A span that records an evaluation.

Trace anatomy: a session identified by session_id groups traces. One trace is a task root span, summarize-thread, with llm, tool, function, and score child spans. propagate_attributes stamps session_id, user_id, and tags on every span in its scope, and a zoomed llm span shows model, provider, usage tokens, and cost.

Record model usage and cost

Call update on the llm span that spent the tokens. Record usage and cost there, not on the root.

Python
TypeScript

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},
        input=[{"role": "user", "parts": [{"type": "text", "content": "Summarize this thread"}]}],
        output="Three open questions remain.",
    )

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 },
    input: [{ role: "user", parts: [{ type: "text", content: "Summarize this thread" }] }],
    output: "Three open questions remain.",
  });
});

cost accepts input, output, and total. Provide total when your provider bills one figure you cannot split.

usage keys are agent-sdk.v1 attribute names, so they stay snake_case in both languages: input_tokens, not inputTokens. If a trace shows no token counts, check these key names first.

Record failure

record_failure (Python) or recordFailure (TypeScript) marks the span as errored and records the exception without re-raising it, so tracing never changes your control flow.

Python
TypeScript

span = client.start_span("call-provider", as_type="llm")
try:
    result = call_provider()
except ProviderError as error:
    span.record_failure(error)
    raise
finally:
    span.end()

const span = client.startSpan("call-provider", { asType: "llm" });

try {
  const result = await callProvider();
} catch (error) {
  span.recordFailure(error);
  throw error;
} finally {
  span.end();
}

start_as_current_span and startAsCurrentSpan already record a failure that escapes their block. Call record_failure yourself only on a span you started with start_span or startSpan.

Verify spans

Call client.flush() before the script exits. flush() fails when the asynchronous exporter reports a delivery error; inspect client.export_health in Python or client.exportHealth in TypeScript for a sticky status, failure count, and safe error category. The health object does not include an endpoint or token. Do not mark an evaluation complete after a failed flush.Then open the trace in Atlan Trident. Confirm the span tree matches your code, the chat span shows model, token counts, and cost, and a failed span shows the error.If no trace appears, see init() disables tracing and no traces are exported.

Troubleshooting

If traces do not appear, see Install and setup errors.

Next steps

Wrap functions with observe: trace functions without restructuring them.

Register and manage agents

Give agents business context

Observe agent runs

Evaluate and improve agents

Track agent cost

Create spans for agent run

Before you begin

Troubleshooting

Next steps

See also