Init & Setup

Installation

pip install decimalai

Each framework integration ships as an extra, such as pip install "decimalai[langchain]". Each extra floors its framework at the framework’s latest release. Two extras ask more of the environment:

[adk], [pydantic-ai] and [all] need Python 3.11+.
[evals] is not part of [all]. litellm pins openai<3, while [openai], [openai-agents] and [pydantic-ai] need openai>=3, so install [evals] in an environment of its own.

pip reports neither conflict: it quietly installs an older decimalai, the newest release whose requirements still resolve. Check with pip show decimalai, or put a floor on the SDK so pip fails with an error instead:

pip install "decimalai[adk]>=0.27"

Quick Start

An agent gets its prompt and skills from its framework’s agent_config(), which you pass into your own agent:

from agents import Agent
from decimalai.openai_agents import agent_config

support = agent_config("support-agent", fallback="You are a support agent.")
agent = Agent(name=support.name, instructions=support.instructions, tools=[*support.tools])

agent_config() reads DECIMAL_API_KEY and traces its own runs, so a file that uses one needs no init() call. Eight frameworks have one: LangChain, OpenAI Agents, the Claude Agent SDK, the OpenAI SDK, Anthropic, the Gemini API, Pydantic AI and Google ADK. See Frameworks. decimalai.init() is for tracing with a framework flag, and for settings such as base_url, enabled or a default agent name:

import decimalai

decimalai.init(api_key="dai_sk_...", langchain=True)   # traces LangChain runs

Your own model calls

Code that calls a model itself, through a provider SDK or a tool loop of your own, gets an agent’s prompt and skills from decimalai.agent_config(), as plain values. On the OpenAI SDK, the Gemini API and the Anthropic Messages API, use that module’s own agent_config() instead: it hands the tool over in the provider’s shape and traces each run. Start a run for each user message:

import decimalai

support = decimalai.agent_config("support-agent", fallback="You are a support agent.")

run = support.run(question, variables=customer)   # one user message
system = run.system                              # the saved prompt, filled, then this run's skill list
tools = [*my_tools, run.tool_spec]               # load_skill as {name, description, parameters}
# Call your model with them. When it calls load_skill:
text = run.load_skill(tool_input["name"])        # the skill's full text, for the tool result

support.run(message, variables=...) routes message and fills the saved prompt’s {{name}} variables from variables (attributes or dict keys). A variable with no value raises decimalai.MissingPromptVariable before any model call.
run.tool_spec is the load_skill tool in no provider’s format, so translate it.
run.load_skill(name) returns a listed skill’s full text, from any thread or task. A skill already loaded in this run, an unknown name or an outage comes back as a sentence the model can act on.
support.prompt is the saved prompt with its variables unfilled, or the fallback= text, for code that only wants the text.
prompt_version, prompt_hash and prompt_source say which prompt is in use. prompt_source is "decimalai", "decimalai (cached copy)" when DecimalAI could not be reached, "fallback (unreachable)" when nothing was cached either, "fallback (none saved)" when the agent has no saved prompt, or "fallback (no key)" with no key. variables lists the prompt’s variables, and skill_names the agent’s skills.

agent_config() re-reads the prompt in the background at most once a minute. A name your workspace has no agent by is created, so a misspelled name makes a new agent rather than an error. With no key it runs from your project alone. on_unavailable="fail" makes support.run() raise when DecimalAI never returned the agent’s skills; by default the run goes on without them. A run’s record (prompt version, variable names, skills offered and loaded) goes on a trace only inside an OpenTelemetry run, such as agent_run(support.name) with a provider flag.

A chat on Claude

Claude rejects a changed system prompt or tool definition partway through a chat (why), so a chat keeps one conversation:

chat = support.conversation(variables=customer)   # or support.conversation(state=saved)
run = chat.run(question)                          # run.system: the first run's text, every message
tools = [*my_tools, run.tool_spec]                # the first run's definition, every message
saved = chat.state                                # JSON: store it with the chat's history

`decimalai.init()`

Call it once, before the calls it configures.

str

default:"DECIMAL_API_KEY env"

Your DecimalAI API key. Falls back to DECIMAL_API_KEY, then to its alias DECIMALAI_API_KEY.

str

default:"https://api.decimal.ai"

Backend URL.

bool

default:"True"

Set False to disable all tracing (useful in tests): no adapter is installed and no call is made to the DecimalAI API. It also stops a skill loader an earlier init() installed, until a later init(enabled=True).

str

default:"DECIMAL_AGENT_NAME env"

The agent this process traces and routes skills for, wherever a call names no agent. See The default agent name.

bool

default:"True unless DECIMALAI_SKILLS=0"

Whether crewai=True also turns on CrewAI’s skill loader, the one flag with a skill loader. False installs tracing only. With langchain, False silences the warning a run without agent_config()’s middleware logs. Unset, it falls back to DECIMALAI_SKILLS, then to True.

str

default:"DECIMALAI_SKILL_AUTHORITY env, else auto"

Whether the LangChain and OpenAI Agents adapters upload the local SKILL.md files you wrote. "harness" always does, for a runtime that loads skills from disk itself (Claude Code, Cursor). "auto" and "router" do only when instrument() is asked to, with disk_sync=True or skill_dirs=. Nothing is ever written to disk.

bool

default:"True"

Probes the backend once to validate the key and base_url. Raises DecimalConfigError on a 401/403 or a connection failure. Pass False in CI or cold-start-sensitive paths.

float

default:"3.0"

Seconds before the probe gives up. On timeout, init() logs a warning and continues.

Instrumentation flags

Each flag is a bool, default False, and traces that surface. Google ADK and Pydantic AI have no flag: an ADK agent is traced by DecimalAIPlugin() in its App, and a Pydantic AI agent by agent_config()’s capability.

Flag	Instruments
`openai_agents`	OpenAI Agents SDK, tracing only
`langchain`	LangChain / LangGraph, tracing only
`llamaindex`	LlamaIndex (`llama-index-core>=0.14.25`)
`crewai`	CrewAI: tracing, and the skill loader
`autogen`	Retired. An alias for `otel=True` that warns
`claude_agent_sdk`	Claude Agent SDK, tracing only
`otel`	Generic OpenTelemetry span exporter for any framework
`openai`, `anthropic`, `google`	Direct provider SDK calls. Don’t combine one with a framework flag that already traces the same provider, or the call is captured twice

crewai=True is shorthand for init() plus decimalai.crewai.instrument(agent_name=..., enable_skill_loader=True). Use the explicit instrument() form when you need other arguments, and don’t combine the two forms for one framework: on LangChain the second call ignores its agent_name.

The default agent name

You name the agent once, in init() or in the DECIMAL_AGENT_NAME environment variable, and every call that is not given a name of its own uses it:

decimalai.init(agent_name="support-agent")   # or: export DECIMAL_AGENT_NAME=support-agent

The SDK takes the first of these that is set: a name passed to the call itself (instrument(), start_trace(), @decimalai.trace, SkillRouter()), init(agent_name=...), DECIMAL_AGENT_NAME, then the call’s own fallback (the decorated function’s name for @decimalai.trace, the framework’s own name for an adapter). agent_name matters for skills too: skills assigned to one agent are only offered when the router is told which agent is asking. An agent built from agent_config("<name>") is routed and traced as that name on all eight frameworks that have one, whatever the framework calls it, a Pydantic AI Agent’s own name= included. For the flag and instrument() forms, every adapter’s instrument() uses the name init() was given (or DECIMAL_AGENT_NAME) when it is not passed one, so naming the agent in init() is enough; an agent_name= passed to instrument() wins over it. SkillRouter(agent_name=None), passed explicitly, means no agent: the router offers the organization-wide skill set. register_manifest(), flush_manifest_for_ci() and decimalai.agent_config() take the name as a required argument. With verify=True, init() also logs a WARNING when the name is not an existing agent but is within two characters of one (refund_bot beside refund-bot). Such a typo files traces under a second agent, which is offered none of the first one’s skills, and nothing errors.

Environment Variables

Variable	Description
`DECIMAL_API_KEY`	API key. `DECIMALAI_API_KEY` is accepted too
`DECIMAL_BASE_URL`	Backend URL override
`DECIMAL_AGENT_NAME`	The default of `init(agent_name=...)`. A name passed in code wins over it
`DECIMAL_AUTO_TRACE`	Trace on import, with no code changes: `langchain`, `openai-agents`, `llamaindex`, `crewai`, `otel`, `openai`, `anthropic` or `google` (`autogen` maps to `otel`). Calls the matching `init()` flag, so `crewai` also turns the skill loader on. `adk` traces nothing and logs a warning: put `DecimalAIPlugin()` in your ADK `App`
`DECIMALAI_SKILLS`	The default of `init(skills=...)`, and the opt-out for `DECIMAL_AUTO_TRACE`. `0`, `false`, `no` or `off` keeps `crewai` to tracing only, and silences `langchain`’s warning. Unset, empty, `1`, `true`, `yes` or `on` delivers skills on `crewai`. Any other value is treated as off and logs a warning
`DECIMALAI_SKILL_AUTHORITY`	The default of `init(skill_authority=...)`: `auto` (unset), `router` or `harness`

What’s next

Tracing

Decorators and helpers to capture LLM and tool calls.

Frameworks

Each framework’s agent_config(), and tracing for CrewAI and OTel.

Python SDK

Skills in your repo

CLI

REST

Installation

Quick Start

Your own model calls

A chat on Claude

`decimalai.init()`

Instrumentation flags

The default agent name

Environment Variables

What’s next

Tracing

Frameworks

​Installation

​Quick Start

​Your own model calls

​A chat on Claude

​decimalai.init()

​Instrumentation flags

​The default agent name

​Environment Variables

​What’s next

Tracing

Frameworks

Installation

Quick Start

Your own model calls

A chat on Claude

`decimalai.init()`

Instrumentation flags

The default agent name

Environment Variables

What’s next