Step

Step types

• llm — a model call. Captures provider, model, messages, and token usage.
• retrieval — a search/embedding lookup. Captures inputs and document IDs.
• tool — a tool/function call. Captures name, arguments, and result.
• custom — anything else. Use it freely.

Auto-parenting

Steps that open inside another step automatically become children. The Python SDK uses a ContextVar stack; the Node SDK uses AsyncLocalStorage. You don't need to thread parent IDs manually.

with client.trace(name="agent") as t:
    with t.step(name="plan", type="llm") as s1:
        with t.step(name="kb.search", type="retrieval") as s2:
            ...   # s2 is a child of s1

Capturing messages

Use log_message / logMessage to record a single content event. Messages support typed content parts: text, image, audio, video, file, sensor, tool_call, tool_result.

Token usage and cost

Use set_token_usage(input=…, output=…) on every LLM step. Cost is computed from a per-model price table and rolled up at the trace level. Override it explicitly if needed via set_cost(usd=…).

Errors

If an exception escapes a step context, the SDK marks the step as failed and records the exception type, message, and stack frame. The parent trace bubbles the failure unless you handle it.