Tracing

Every run of your agent is saved as a trace: what it was asked, what it answered, which skills it used, which prompt it ran on, and each model and tool call. Open one from the Traces page or an agent’s Traces tab.

What a run shows about skills

A run’s Overview tab has a Recorded skills section with three rows: Offered, Delivered and Loaded. How skills reach the model defines them. On one run, read them like this:

What the run shows	What happened
Offered lists a skill and Loaded doesn’t	The model saw its line and didn’t ask. That’s normal when the question doesn’t call for it
Offered, Delivered and Loaded all list it	The model asked for the skill and got its text
Delivered lists it and Loaded doesn’t	Its text reached the model without the model asking. It may be always included, or pasted into the prompt
A row says None	The run reported that step, and no skill reached it
A row says Not reported	The run didn’t report that step, which doesn’t mean no skill was used

Two more rows can appear. Routing decision is the id of the ranking this run used. Experiment says which group the run was in. Under those rows, each recorded skill has its own line:

Explicit load recorded means the skill is on the run’s Loaded list. Activation record means it was recorded another way, such as your code declaring it.
Skill version v3 is the version this run received, which may not be today’s. Version not recorded means the run didn’t say.
Details shows the recorded version ID and content hash, and Copy evidence copies them.

Across many runs, see Which skills get used.

What the API returns, and how each step is detected

GET /api/v1/traces/{trace_id} returns the same three steps:

{
  "id": "trc_abc123",
  "skills_offered_in_prompt": ["code-review", "sql-optimizer"],
  "skills_delivered": ["code-review"],
  "skills_loaded_by_agent": ["code-review"],
  "active_skills": [
    {
      "skill_name": "code-review",
      "skill_hash": "sha256:9b1c42aa",
      "skill_version_id": "5d2e8f10-6f3a-4a1b-9c7d-2e1f0a9b8c7d",
      "version_number": 3
    }
  ]
}

active_skills holds the loaded skills with the version of each, plus any skill your code declared. null means the step wasn’t reported, and [] means it was reported and empty.Loaded comes only from a direct event: the model calls load_skill, a framework’s own skill loader hands it a skill, or your code declares it.Offered and Delivered come from DecimalAI’s own list when DecimalAI built the prompt. Otherwise, on the generic tracer, LangChain, OpenAI Agents and OpenTelemetry, the SDK matches system and developer messages against the skills it knows. A name alone, such as ## Skill: code-review, means Offered. At least 60% of the skill’s body lines means Delivered.

Which prompt a run used

An agent built with agent_config() records, on each run, the prompt that run was given: its source ("decimalai", or a fallback value when no saved prompt was used), the saved version number, the template’s content hash, and the names of the variables it filled. Variable values are never recorded. When DecimalAI could not serve the agent’s skills, the reason is recorded too. The API returns these as prompt on each trace, or null when the run recorded none. GET /api/v1/traces?prompt_version=3 lists the runs whose agent ran saved version 3; a handoff target’s prompt doesn’t count as the run’s own. In the dashboard:

A run’s page shows the version in its header, and a Prompt section with the source, hash and variable names, linked to Other traces on this version.
The agent’s Traces tab has a Prompt column and a filter by prompt version. Its Version column is the agent’s code version, which a prompt edit doesn’t change.
Prompt & skills links each saved version to Traces on this version.

The rest of a run

A run has this shape:

Session        one conversation
└── Trace      one run, from input to output
    ├── Span       a timed step, such as a tool call
    └── LLM call   one model call, in full

Traces are what the rest of DecimalAI works on: evaluators score them, compatibility gives them verdicts, and datasets are built from them. A trace belongs to one agent, and normally one manifest. Some compatibility screens and routes say episode, which means the same thing.
Spans nest through parent_span_id, and each has a span_type: agent, llm, tool, retrieval, router, judge, handoff, guardrail, memory, planning or other.
LLM calls hold the messages sent, the output and the tokens. Training rows are made of them.
Sessions group the runs of one conversation. Runs that share a session_id belong together. @decimalai.trace() takes it.

On a run’s page, the strip at the top shows Duration, Tokens, Est. cost, LLM calls, Spans and LLM latency. Cost is an estimate from model pricing tables. Below it, Execution shows the run as a Timeline or a Tree, beside Overview, which shows the input and output. Select a step to see what went in and came out. A model call has an Open in Playground button, which re-runs that call. The other tabs are Evaluations (scores and verdicts), Compatibility, Contract, Skill Rater and Annotations.

Find a run

The DecimalAI Traces page: stat cards above a table of runs with ID, agent, status, eval verdict, tokens, cost, duration and input. — The Traces page, filterable by agent and by manifest version.

The Traces page covers every agent. It has Search traces (ID, agent or input), filters by Agent and Manifest (the agent version), views for All, Errors, Failed evals and Unevaluated, a Time range, and Group by Agent or Session. An agent’s Traces tab lists that agent’s runs, with a search over input and output, and filters by status, eval verdict and prompt version. Runs from decimalai.evaluate() show here too, and their own page says evaluation in its header.

Trace schema

Every run is a RunTrace:

Field	Type	Description
`id`	UUID	The run’s identifier
`agent_name`	string	The agent that made the run
`status`	string	Overall status: `success`, `error` or `degraded`
`user_input_preview`	string	The user’s input, cut short
`final_output_preview`	string	The final answer’s first 200 characters
`final_output`	string	The whole final answer, up to 20,000 characters, from the OpenAI Agents SDK integration. Other runs have only the preview
`llm_calls`	`LlmCallRecord[]`	Every model call
`spans`	`TraceSpan[]`	The run’s steps
`started_at`, `ended_at`	datetime
`source_type`	string	Where it came from: `production` by default, `evaluation` for evaluation runs, `synthetic` for generated prompts, `manual` for imported files, `sample` and `demo` for seeded data, and others such as `test`. Ingest rejects a value outside its list with a 422
`manifest_id`	UUID	The agent version active when the run was recorded
`parent_trace_id`	UUID	The parent run, for a child trace
`session_id`	string	The conversation it belongs to
`routing_id`	string	The ranking this run used
`skills_offered_in_prompt`, `skills_delivered`	`string[]`	Offered and Delivered
`skills_loaded_by_agent`, `active_skills`	`string[]`, `object[]`	Loaded
`prompt`	object	The prompt it used; see Which prompt a run used

LlmCallRecord

Field	Type	Description
`model_name`	string	The model, such as `gpt-5.4-mini` or `claude-sonnet-4-6`
`provider`	string	`openai`, `anthropic`, `google`
`input_tokens`, `output_tokens`	int	Prompt and completion tokens
`latency_ms`	int	Wall-clock time for this call
`rendered_input`, `output`	list, object	The exact request and response
`tool_calls`	list	Tool calls the model made
`finish_reason`	string	`stop`, `tool_calls`, `length`

Check your setup

With DECIMAL_API_KEY set, one command checks your key, tests the connection and sends a test run, with no agent code:

pip install decimalai
decimalai init

The run is filed under an agent named decimalai-init-test. If it doesn’t appear on the Traces page within seconds, see the silent no-ops.

Turn tracing on

An agent built with agent_config() is traced already. Frameworks shows the line for each framework. For tracing alone, with no prompt or skills from DecimalAI, use a flag:

import decimalai

decimalai.init(api_key="dai_sk_...", langchain=True)  # or openai_agents, llamaindex, crewai, otel

Every flag traces only, except on CrewAI, where it delivers skills too unless you pass skills=False or set DECIMALAI_SKILLS=0. Frameworks with no DecimalAI integration go through OpenTelemetry.

Zero-code setup (environment variables)

export DECIMAL_API_KEY="dai_sk_..."
export DECIMAL_AUTO_TRACE=langchain       # or openai-agents, llamaindex, crewai, otel
export DECIMAL_AGENT_NAME=support-agent   # the agent its runs are filed under

python my_agent.py

Google ADK has no value here: put DecimalAIPlugin() in your App.

Manual tracing

For a plain function, use the decorator. The SDK reference has the rest.

import decimalai

decimalai.init(api_key="dai_sk_...")

@decimalai.trace(agent_name="my-custom-agent")
def process_request(query: str):
    return call_llm(query)

process_request("What is the weather?")

Start here

Tutorial: a support agent

Use skills

Manage and measure

Publish a skill

More

What a run shows about skills

Which prompt a run used

The rest of a run

Find a run

Trace schema

LlmCallRecord

Check your setup

Turn tracing on

Zero-code setup (environment variables)

Manual tracing

Next Steps

Evaluations

Troubleshooting

​What a run shows about skills

​Which prompt a run used

​The rest of a run

​Find a run

​Trace schema

​LlmCallRecord

​Check your setup

​Turn tracing on

​Zero-code setup (environment variables)

​Manual tracing

​Next Steps

Evaluations

Troubleshooting

What a run shows about skills

Which prompt a run used

The rest of a run

Find a run

Trace schema

LlmCallRecord

Check your setup

Turn tracing on

Zero-code setup (environment variables)

Manual tracing

Next Steps