Quickstart

See it first — 2 minutes, no waiting for your own data

The impact report and the skills leaderboard are most convincing on real data — so both ship with a one-command sandbox that seeds a realistic agent and trace corpus into your workspace. See the payoff before you instrument anything.

pip install decimalai   # requires Python 3.10+
export DECIMAL_API_KEY="dai_sk_..."   # grab one at app.decimal.ai/settings

DecimalAI requires Python 3.10 or newer. On Python 3.9 and older, pip silently installs an outdated release that lacks the demo command.

Pick the door that matches your job — or run both:

For engineers

Catch regressions before they ship.

decimalai demo regression

Seeds a v1→v2 agent change and links you straight to the impact report — which production traces the change would break, which may behave differently, and which are unaffected.

For prompt engineers

Find skills that actually work.

decimalai demo skills

Seeds three skills with real, varied effectiveness and links you to the ranked registry — per-model pass rates and cross-org activation, not download counts.

No account yet? Browse the public skill registry right now — no signup — to see skills ranked by production effectiveness.

Once a demo makes the value land, wire DecimalAI to your own agent below.

You’ll do five things in this guide:

Install the SDK

1 minute.

Get your API key and verify your setup

1 minute.

Instrument your agent

3 minutes.

View your first trace in the dashboard

1 minute.

Add the GitHub Action so every PR gets a manifest impact report

5 minutes.

By the end, your team’s next agent change will get an automatic structural impact analysis on the PR — without you writing any eval cases. Here’s the kind of report that lands on the PR:

Run this in Colab

Run the SDK portion interactively — no local setup required.

1. Install the SDK

pip install decimalai   # requires Python 3.10+

The base package covers no-framework tracing, the CLI, and the Skill Router. Framework integrations install as extras — e.g. pip install "decimalai[langchain]" — shown per-framework in step 3.

Checkpoint: decimalai --version prints a version number. If the demo command is missing, you’re on Python < 3.10 and pip silently installed an outdated release.

2. Get Your API Key

Sign in to the DecimalAI Dashboard and navigate to Settings → API Key. Your first key has to come from the dashboard — the POST /api-keys endpoint itself requires authentication, so it’s only useful for minting additional keys once you have one.

Verify your setup instantly: Run decimalai init to check your API key, test connectivity, and send a test trace — all in one command.

Checkpoint: decimalai init prints all three green checks:

✓ API key: dai_sk_8f3...3a2c
✓ Connected to workspace: ws_7Hq2Kp (scope: workspace)
✓ Test trace sent successfully

→ Open dashboard: https://app.decimal.ai/traces
→ Docs: https://docs.decimal.ai/quickstart
→ Quickstart notebook: https://colab.research.google.com/github/decimal-labs/decimalai-python/blob/main/examples/quickstart/quickstart.ipynb

Reading a ✗: on the first line it means no API key was found at all (nothing in DECIMAL_API_KEY or --api-key). On the second line you get ✗ Connection failed: followed by the underlying error, and that error is what tells you which problem you have: Client error '401 Unauthorized' means the key is wrong or truncated and '403 Forbidden' means it’s expired or revoked — either way, regenerate it at app.decimal.ai/settings. Only a timeout or DNS error is an actual network or --base-url problem, despite the “Check your API key and base URL” hint printed under both.

3. Instrument Your Agent

Calling openai / anthropic / google.genai directly, no agent framework in between? This is the shortest path — and it gets full skill routing:

pip install decimalai

import decimalai
from decimalai.skill_router import SkillRouter
from openai import OpenAI

decimalai.init(api_key="dai_sk_...")
client = OpenAI()
# inject_body=True delivers the routed skill's full instructions,
# not just a one-line menu row
router = SkillRouter(api_key="dai_sk_...", strategy="auto", inject_body=True)

@decimalai.trace(agent_name="support-agent")
def answer(question: str) -> str:
    skills, _ = router.build_prompt_fragment(query=question)
    messages = [
        {"role": "system", "content": "You are a support agent.\n\n" + skills},
        {"role": "user", "content": question},
    ]
    resp = client.chat.completions.create(model="gpt-4o", messages=messages)
    decimalai.log_llm_call(
        model="gpt-4o",
        input=messages,
        output={"content": resp.choices[0].message.content},
    )
    return resp.choices[0].message.content

answer("How do I reset my password?")

build_prompt_fragment stamps the routing decision and the offered skill names onto the active trace automatically — no extra logging calls. On a network failure it returns ("", None) so prompt assembly never blocks.

Prefer zero manual logging? decimalai.init(openai=True) auto-traces every raw OpenAI SDK call — it drives an OpenInference instrumentor, so install both: pip install "decimalai[openai]" openinference-instrumentation-openai. anthropic=True / google=True work the same way via openinference-instrumentation-anthropic / openinference-instrumentation-google-genai (no extra for those — install the instrumentor package directly). Don’t combine a provider flag with a framework flag that already traces the same provider.

pip install "decimalai[langchain]"

import decimalai

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

# Run your agent as usual — traces are captured automatically
agent.invoke({"input": "Hello!"})

Run this in Colab

Live notebook, no setup — just paste your API key.

pip install "decimalai[openai-agents]"

import decimalai

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

result = await Runner.run(agent, "Hello!")

Run this in Colab

Live notebook, no setup — just paste your API key.

pip install "decimalai[claude-agent-sdk]"

import decimalai

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

# Every query() stream is traced automatically — model turns,
# tool calls, token usage, cost
from claude_agent_sdk import query, ClaudeAgentOptions
async for message in query(prompt="Hello!", options=ClaudeAgentOptions()):
    ...

Skills reach Claude Code via disk, not the live router: install registry skills into .claude/skills/ with SkillRouter(api_key="dai_sk_...").install("pdf", agents=["claude-code"]) and Claude Code loads them itself. There is no hosted-routing path on this integration — skill selection happens inside Claude Code, so router-side effectiveness data isn’t collected here.

pip install "decimalai[llamaindex]"

import decimalai

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

# Query engines, retrievers, and LLM calls are traced automatically
from llama_index.core import VectorStoreIndex
index = VectorStoreIndex.from_documents(documents)
response = index.as_query_engine().query("What is the revenue?")

pip install decimalai   # CrewAI routes through the built-in OTel rail

import decimalai

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

# CrewAI agent tasks, tool calls, and LLM interactions are traced
from crewai import Crew
crew = Crew(agents=[...], tasks=[...])
result = crew.kickoff()

# Zero code changes — just set env vars
export DECIMAL_API_KEY="dai_sk_..."

# Frameworks: langchain, openai-agents, adk, llamaindex, otel,
#             autogen, crewai   (autogen/crewai alias the otel rail)
# Raw provider SDKs (no framework): openai, anthropic, google
export DECIMAL_AUTO_TRACE=langchain

python my_agent.py

If the framework package isn’t importable, auto-init logs a warning and continues untraced — see the silent no-ops list below.

Auto-detection depth varies by framework. LangChain and OpenAI Agents (with explicit install(agent=...)) extract full tool schemas; LlamaIndex / CrewAI extract tool names only. See the capability matrix before deciding which integration to commit to. AutoGen / AG2 is supported as a community/legacy OTel integration — see AutoGen.

Checkpoint: run your agent once. Startup logs show DecimalAI SDK initialized: base_url=https://api.decimal.ai ... with no auto-init failed or not installed warnings. Traces flush in the background and at process exit.

4. View Your Traces

Open the Traces page in the dashboard. Your first trace should appear within seconds. Each trace is auto-tagged with the of the agent that produced it — this is what powers the regression check in the next step.

Checkpoint: the Traces page shows a row for your run, tagged with a manifest hash, and the input/output you sent. Nothing after 30 seconds? Work through the silent no-ops below — the most common cause is an integration flag whose package isn’t installed.

Skills (SKILL.md files) in your project’s directories (.claude/skills/, .agents/skills/, …) are auto-discovered and tracked — no extra configuration. Personal directories like ~/.claude/skills/ are deliberately opt-in (include_global=True) so private skills don’t leak into your org’s registry. See Skills.

5. Add the Regression Check to your PRs (recommended)

Now wire DecimalAI into your CI so every PR gets a manifest impact report. This is the most-used capability for engineering teams.

What this step assumes, honestly:

An importable agent factory. The CI script imports and calls one function that constructs your agent. If construction is spread across a script, extract a build_agent() first.
A baseline builds on the first run. The Action’s first run finds no baseline manifest, records your current manifest as the baseline, and exits green — real diffs start on your second PR.
Impact counts come from your ingested traces. A workspace that just finished step 4 has a handful of traces, so early reports will honestly say few or zero traces are affected. The report earns its weight over days as production tracing accumulates volume.

Three things, all copy-pasteable below: a tiny scripts/init_for_decimal.py that calls your agent factory, a .github/workflows/decimal.yml that runs it under DECIMALAI_MODE=manifest_only, and your DECIMAL_API_KEY in GitHub Secrets. Here’s what runs on every PR: 1. Add scripts/init_for_decimal.py — five lines that import and call your existing agent factory. In manifest_only mode the SDK reads tools, prompts, and models from the runtime objects, then exits without any LLM calls:

scripts/init_for_decimal.py

from myapp.agent import build_agent  # adjust to your agent factory

if __name__ == "__main__":
    build_agent()  # DECIMALAI_MODE=manifest_only captures the manifest, no LLM calls

2. Add .github/workflows/decimal.yml:

.github/workflows/decimal.yml

name: Decimal Manifest Impact
on: [pull_request]

permissions:
  contents: read
  pull-requests: write  # required for the Action to post/update its PR comment

jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.12'
      - name: Install dependencies
        run: pip install -e .
      - name: Manifest extraction
        env:
          DECIMALAI_MODE: manifest_only
          DECIMAL_API_KEY: ${{ secrets.DECIMAL_API_KEY }}
          OPENAI_API_KEY: dummy_for_init  # placeholder; NOT called in manifest_only mode
        run: python scripts/init_for_decimal.py
      - name: Impact check
        uses: decimal-labs/regression-check@v1
        with:
          api-key: ${{ secrets.DECIMAL_API_KEY }}
          agent-name: support-agent  # the same name you use in decimalai.init()

3. Add the DECIMAL_API_KEY secret in Settings → Secrets and variables → Actions → New repository secret, with the value from app.decimal.ai/settings. That’s the whole setup. Once a baseline exists and traces have accumulated, each PR gets a comment like this within ~30 seconds:

🔍 Decimal Manifest Impact — support-agent

🔴 HIGH IMPACT — 247 traces will break (called the removed `compare_competitors` tool)
🟡 MEDIUM IMPACT — 501 traces may behave differently
🟢 LOW IMPACT — 1,254 traces unaffected

Checkpoint: open a trivial PR. The Decimal Manifest Impact check runs green, and the PR gets a comment. On the very first run the comment says “First run for this agent. Recorded the current manifest as the baseline.” — that’s the expected day-one state, not a failure. Impact counts like the example above appear from the second PR onward, sized by how many traces you’ve ingested.

Full setup, troubleshooting, severity thresholds, override behavior, and alerting are in the Regression Check Guide.

If something looks wrong: the six silent no-ops

The SDK is deliberately fail-open: a misconfiguration degrades quietly instead of crashing your agent. These are the six places that bites, in the order people hit them.

1. A registry skill is never offered to your agent

Browsing or previewing a skill on the public registry doesn’t make it routable — you have to adopt it into your org first. Either way works — Use (router.use("name") or the Use button) creates a linked pointer that tracks the author’s updates, and Fork (router.fork("name"), or router.install("name") to also write it to disk, or the Fork button) creates an editable copy you own. The Skill Router offers both. If you use per-agent assignments, also assign it to the requesting agent. Until you Use or Fork it, the skill never appears in your agent’s menu, with no warning anywhere.

2. Only menu rows reach the model — never the skill body

By default build_prompt_fragment injects one-line menu rows (name + description). The skill’s actual instructions reach the model only if you pass inject_body=True to the SkillRouter (smart-routed queries), or enable the load_skill tool so the model can pull bodies on demand. Menu rows count as offered — usage panels show rung-labeled counts for them, and activation isn’t measurable for bare prompt-injection usage. If a skill “isn’t working,” check whether its body ever actually reached the model.

3. The load_skill tool never appears

The on-demand body loader is opt-in: pass enable_skill_loader=True to install() on the openai_agents or pydantic_ai adapters. On the anthropic adapter there is no tool loop — enable_skill_loader=True there injects the skill menu into system (the offered rung only); add init(inject_skill_body=True) if you want full bodies delivered, and note enable_load_skill_tool is accepted but dormant. Kill-switch: init(load_skill_tool=False) or DECIMALAI_LOAD_SKILL_TOOL=0.

4. An integration flag whose package is missing

decimalai.init(langchain=True) (and every other framework flag) logs a warning and continues untraced when the framework package isn’t importable — your agent runs, nothing is recorded. The same applies to DECIMAL_AUTO_TRACE (auto-init warns and skips) and to the raw-provider flags (openai=True etc.), which soft-skip when the matching OpenInference instrumentor is absent. Fix: for a framework flag, install the matching extra, e.g. pip install "decimalai[langchain]"; for a raw-provider flag, install the instrumentor package the startup warning names, e.g. pip install openinference-instrumentation-openai (the [openai] extra covers only the provider SDK, not the instrumentor). Then re-check startup logs.

5. Skill injection skips callable instructions and prebuilt prompts

Adapters only inject skills into prompt shapes they can safely rewrite. On openai_agents, an agent whose instructions is a user-supplied callable is left untouched; on langchain, a prebuilt PromptValue (or any unrecognized prompt shape) passes through unchanged. The agent runs normally — with zero skills injected and no error raised.

6. The impact report says 0 traces (or 'first run')

The regression check needs two things before it can say anything real: a baseline manifest (recorded automatically on the Action’s first run, or by decimalai.init() running in production) and ingested traces to measure blast radius against. A fresh workspace legitimately reports “first run — no baseline” and then near-zero affected traces. That’s honesty, not breakage — reports gain weight over days as production trace volume accumulates.

Here for skills instead?

The steps above wire up the regression capability — what most teams start with. The skills workflow is a separate, shorter track (no GitHub Action needed):

Browse the registry

Find skills ranked by SkillScore in the public registry — no signup.

Try a skill with no account

skills pull is fully anonymous — no API key, no signup:

pip install decimalai
decimalai skills pull playwright-cli --out .claude/skills/

Writes playwright-cli’s SKILL.md (plus its eval.yaml test suite) to disk and prints its scorecard — the Install a Skill tutorial walks this exact skill end-to-end. Your runtime auto-discovers it from there; the whole keyless route is in Use skills without the SDK.

Prove one helps

A/B-benchmark a skill with skillevaluation (pip install "skillevaluation[runner]") to measure its lift on your own cases.

Install it

Fork it into your workspace and write it to disk with router.install(...) — see the Skills guide.

Next Steps

Regression Check Guide

Full configuration, troubleshooting, and severity tuning for the GitHub Action.

Manifests Guide

What manifests capture, how diffs work, and the compatibility policy model.

Concepts

How traces, manifests, evals, and datasets connect.

Training Pipeline

End-to-end: trace → evaluate → fine-tune.

Get Started

Foundation

Ship Safely

Improve with skills

Trust & Safety

Data & Training

Operate

Core Concepts

Platform

See it first — 2 minutes, no waiting for your own data

For engineers

For prompt engineers

Run this in Colab

1. Install the SDK

2. Get Your API Key

3. Instrument Your Agent

Run this in Colab

Run this in Colab

4. View Your Traces

5. Add the Regression Check to your PRs (recommended)

If something looks wrong: the six silent no-ops

Here for skills instead?

Next Steps

Regression Check Guide

Manifests Guide

Concepts

Training Pipeline

​See it first — 2 minutes, no waiting for your own data

For engineers

For prompt engineers

Run this in Colab

​1. Install the SDK

​2. Get Your API Key

​3. Instrument Your Agent

Run this in Colab

Run this in Colab

​4. View Your Traces

​5. Add the Regression Check to your PRs (recommended)

​If something looks wrong: the six silent no-ops

​Here for skills instead?

​Next Steps

Regression Check Guide

Manifests Guide

Concepts

Training Pipeline

See it first — 2 minutes, no waiting for your own data

1. Install the SDK

2. Get Your API Key

3. Instrument Your Agent

4. View Your Traces

5. Add the Regression Check to your PRs (recommended)

If something looks wrong: the six silent no-ops

Here for skills instead?

Next Steps