Tracing

Manual tracing, for code with no framework adapter. If your framework has an agent_config(), it traces for you: see All frameworks. Call decimalai.init() first. Until then your code runs as normal and nothing is sent.

`@decimalai.trace()`

Traces a function as one run. A string first argument is recorded as the run’s input and a string return value as its output, the first 200 characters of each.

import decimalai

@decimalai.trace(agent_name="my-agent", session_id="chat-42")
def run_agent(query: str) -> str:
    return "Paris"   # your model call goes here

result = run_agent("What is the capital of France?")   # one trace per call

Parameter	Description
`agent_name`	The agent the trace is filed under. Left out, the agent `init()` named, else the function’s name. Looked up on each call, so an `init()` after the import still counts
`session_id`	Runs that share one are a conversation
`parent_trace_id`	The run that called this one (multi-agent). Fixed when the decorator is applied, so for a parent known at run time use `start_trace`
`subagents`	The agents this one can call, such as `[{"name": "flight_agent"}]`, recorded in its manifest
`auto_send`	`True` by default. With `False`, the trace is never sent

It wraps a regular function. An async def returns its coroutine at once, so the trace ends before your code runs: open the run with start_trace inside the coroutine.

`decimalai.start_trace()`

A context manager that opens a run. It takes @trace’s parameters, plus skills and skill_dirs for the manifest’s skill list (left out, the SDK reads your project’s skill folders). An exception in the block marks the trace as an error and is re-raised.

with decimalai.start_trace(agent_name="my-agent") as ctx:
    ctx.set_input("Hello")
    decimalai.log_llm_call(
        model="gpt-4o",
        input=[{"role": "user", "content": "Hello"}],
        output={"content": "Hi there!"},
    )
    ctx.set_output("Hi there!")

ctx also has log_llm_call, log_tool_call, set_input(text), set_output(text) (200 characters kept) and get_trace_id(), the id to pass as a child run’s parent_trace_id.

`decimalai.log_llm_call()`

Records one model call on the current trace. Outside a trace it raises DecimalConfigError.

Parameter	Description
`model`	Required, such as `"gpt-4o"`
`input`, `output`	The messages sent (`list[dict]`) and the response (`dict`)
`provider`, `temperature`, `input_tokens`, `output_tokens`, `latency_ms`, `cost_usd`	As named
`cache_read_tokens`, `cache_creation_tokens`	Cache counts as the provider reported them. Leave out what it didn’t: `0` means a cold cache
`finish_reason`	`"stop"`, `"tool_calls"`, `"length"` or `"error"`
`call_role`	`"planner"`, `"responder"`, `"subagent"`, `"judge"`, `"router"` or `"other"` (default)
`response_format`, `content_type`	The structured-output schema; `"text"` (default), `"image"`, `"audio"` or `"multimodal"`

`decimalai.log_tool_call()`

Records one tool call on the current trace. Outside a trace it raises DecimalConfigError.

# inside a traced function or a start_trace block
decimalai.log_tool_call(
    name="search_flights",
    input={"from": "SFO", "to": "NRT"},
    output={"results": []},
    latency_ms=150,
)

name is required. status is "success" (default), "error", "partial" or "running".

`@decimalai.tool`

Registers a function’s name, docstring and parameter types in the agent’s manifest, so the regression check sees when a tool’s schema changes. The function runs unchanged and calling it records nothing: log calls with log_tool_call.

@decimalai.tool
def search_flights(origin: str, destination: str) -> list:
    """Search for available flights."""
    return []

@decimalai.tool(name="flights") registers it under another name.

Mark where a run begins and ends

With a direct provider flag (anthropic=True, openai=True, google=True), say where a run begins yourself. A provider instrumentor sees one SDK call at a time, so a tool-use loop of two messages.create() calls arrives as two unrelated traces.

import decimalai
from decimalai.providers import agent_run

decimalai.init(api_key="dai_sk_...", anthropic=True)

with agent_run("support-bot"):
    first = client.messages.create(model=MODEL, max_tokens=1024, messages=messages)   # tool_use comes back
    add_tool_result(messages, first)                                                  # you feed the tool_result in
    final = client.messages.create(model=MODEL, max_tokens=1024, messages=messages)

That is one trace with both calls nested under it, filed under support-bot. The name belongs to the block, so concurrent runs stay separate, and an inner agent_run is a child span, not a second trace. The other parameters are span_name, attributes and tracer_provider, for an exporter on a provider other than the global one. A run’s skills reach its trace through this span. Without it, a raw-provider run carries no routing_id and no offered skill names: the SDK won’t guess which run a decision belonged to. Framework adapters wrap their own runs, and on Pydantic AI agent_config()’s capability opens the run span. A Pydantic AI agent traced by a provider flag alone needs agent_run. For several LlamaIndex agents in one process, see OpenTelemetry.

Python SDK

Skills in your repo

CLI

REST

`@decimalai.trace()`

`decimalai.start_trace()`

`decimalai.log_llm_call()`

`decimalai.log_tool_call()`

`@decimalai.tool`

Mark where a run begins and ends

​@decimalai.trace()

​decimalai.start_trace()

​decimalai.log_llm_call()

​decimalai.log_tool_call()

​@decimalai.tool

​Mark where a run begins and ends

`@decimalai.trace()`

`decimalai.start_trace()`

`decimalai.log_llm_call()`

`decimalai.log_tool_call()`

`@decimalai.tool`

Mark where a run begins and ends