Pydantic AI

​

Install

pip install "decimalai[pydantic-ai]"

# Only for the harness's own skill loader (below):
pip install pydantic-ai-harness

​

Use

from pydantic_ai import Agent
from decimalai.pydantic_ai import agent_config

def lookup_order(order_id: str) -> str:
    """Look up the status of an order."""
    return f"Order {order_id} shipped yesterday."

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

agent = Agent(
    "openai:gpt-4o-mini",
    name=support.name,
    tools=[lookup_order],     # your tools; the capability adds load_skill
    capabilities=[support],   # the saved prompt, the skill list and load_skill
)
result = agent.run_sync("Where is order 1001?")
print(result.output)

• agent_config("support-agent") reads the agent’s saved prompt when it is called. It initializes the SDK from DECIMAL_API_KEY when decimalai.init() has not been called, and a name your workspace has no agent by is created (SDK 0.24+), so a misspelled name makes a new agent rather than an error. fallback= is what runs when the agent has no saved prompt yet, when no DecimalAI key is set, or when DecimalAI cannot be reached at startup; with a key and no fallback=, an unreachable DecimalAI raises instead of starting an agent with no instructions. With no key at all, the agent runs without a DecimalAI key: the skills your project lists in .decimal/skills.toml, with nothing sent.
• capabilities=[support] adds instructions: the saved prompt, then this agent’s skill list, chosen for the run’s prompt, and one sentence telling the model to load a skill before using it. Your own instructions= stay first and unchanged, so they remain a prefix a provider can cache.
• load_skill is the capability’s one tool, limited to the agent’s skills. The model calls it with a skill’s name and gets the skill’s full text back, which counts as delivered and activated on the usage ladder. Each load names the run’s routing decision, and the platform decides what it serves: a skill your org owns, has installed or has assigned to the agent loads whether or not this run’s list showed it, while one reachable only through the public registry loads only when this run was offered it.
• support.name is the agent’s name in DecimalAI. Every run is routed for it and traced under it, whatever the Agent is called. name=support.name makes the two agree.
• Each run is one trace, with Pydantic AI’s own spans for its model calls and tool calls, and no other line: no decimalai.init(otel=True), no Agent.instrument_all() (SDK 0.25+). Tracing says how, and what happens when your app traces Pydantic AI itself. decimalai init --framework pydantic-ai writes the same file.

​

Change the prompt without redeploying

from dataclasses import dataclass

@dataclass
class Customer:
    name: str
    tier: str

# A prompt saying "The customer is {{name}}, a {{tier}} member" reads deps.name and deps.tier
result = agent.run_sync("Where is my order?", deps=Customer("Sam", "gold"))

​

How each run’s skills are picked

• The first run is routed before its first model request.
• Later runs show the local copy of the list, and their own routing decision is recorded in the background, so no run waits on it.
• An agent with more skills than the list holds is routed before every run, so the list is picked for the prompt.
• A run that continues a Claude conversation shows that conversation’s list. Its own decision is recorded in the background, or, when the list was cut to fit, the run names the decision the list came from, so the skills it shows can be loaded.

​

When an agent’s skills are switched off

• The tool’s kill switch. With DECIMALAI_LOAD_SKILL_TOOL=0 or decimalai.init(load_skill_tool=False), every run is routed and the text of the skills picked for it goes into the instructions instead (inject_skill_body, which defaults to on once the tool is off). With inject_skill_body=False as well, the agent gets no skills, and one warning says so.
• decimalai.init(enabled=False) after agent_config() stops routing and skills for that config; the prompt it read keeps running. An agent_config() called while it is off asks DecimalAI nothing: the agent runs on its fallback= text, and without one agent_config() raises RuntimeError (SDK 0.22.1+).
• on_unavailable="fail". By default ("continue") an agent whose skill list never came back answers without skills, and its trace says so. With agent_config(..., on_unavailable="fail") the run raises before the model request instead.

• Loading a skill costs a model request. The model asks for the skill in one request and uses it in the next, so leave room under UsageLimits(request_limit=...) if your agent already runs close to it.
• An outage during a run is not an error. If DecimalAI cannot be reached mid-run, the run keeps the last skill list DecimalAI returned, and load_skill answers with a sentence the model can read.
• Skills come from DecimalAI, not from disk. agent_config() reads no local SKILL.md files. To serve skill folders installed in your project, use the harness below.

​

Tracing

• Your own instrumentation (Agent.instrument_all(), Agent(instrument=...), an Instrumentation capability, or Logfire’s logfire.instrument_pydantic_ai()) keeps tracing the run with its settings, inside DecimalAI’s run span; the capability adds none of its own. Its spans reach DecimalAI when they go to the global tracer provider.
• A provider instrumentor that DecimalAI runs (decimalai.init(openai=True), anthropic=True or google=True, for the SDK the run’s model calls) records the model calls, so the capability does not instrument the run again. Such a run’s tool calls are not in its trace.

​

Load installed skills with the Pydantic AI harness

decimalai skills add acme/refund-policy    # writes .agents/skills/acme-refund-policy/

import decimalai
import decimalai.pydantic_ai_harness
from pydantic_ai import Agent
from pydantic_ai.capabilities import LocalWorkspace
from pydantic_ai_harness import FileSystem, Shell

decimalai.init(api_key="dai_sk_...", otel=True, agent_name="support-agent")
Agent.instrument_all()               # Pydantic AI's own spans: one trace per run

project = decimalai.skills_dir().parents[1]   # the directory that holds .agents/
harnessed = Agent(
    "openai:gpt-4o-mini",
    capabilities=[
        LocalWorkspace(project),
        decimalai.pydantic_ai_harness.skills(project),
        FileSystem(),
        Shell(),   # lets the model run commands, a skill's scripts included, on this machine
    ],
)
result = harnessed.run_sync("A customer wants a refund for $100 after 45 days.")

• Each load is an activation (SDK 0.16.0+). Each skill the model loads with the harness’s load_capability is recorded as an activation carrying the version of the body it received, and the run’s skills as offered. The harness drops metadata, so the version comes from the lock, by the hash of the delivered body. It reads the skills at the start of every run, so a run after decimalai skills update serves the new version.
• A load needs a trace to land on. The two OpenTelemetry lines above give every run one, filed under init()’s agent_name; no instrument() is needed (SDK 0.19+). Inside decimalai.start_trace(), the load goes on that trace instead. With neither, the load is dropped, and a warning says so once.
• Don’t also give this agent agent_config()’s capability. The harness’s Skills is already its catalog, so DecimalAI would add neither its skill list nor load_skill, and one warning says so. Build the Skills with decimalai.pydantic_ai_harness.skills(...): a plain Skills(...) serves the same skills, but its loads are not recorded.
• The path is relative to the workspace. A skills folder outside the workspace still lists, but the harness’s read_file refuses its files, which is why the workspace above is the project itself. skills(project) raises when the skills folder is not inside project.
• allowed-tools is not enforced. The harness says so with a UserWarning (Ignoring unsupported Agent Skill behavioral frontmatter fields) on every run; grant tools in the agent’s own configuration. From pydantic-ai-harness 0.57.0 it keeps a user-only skill (disable-model-invocation: true) out of the model’s catalog.

​

What gets captured

• Model calls and tool calls, from Pydantic AI’s own spans (or, beside init(openai=True) and the like, the provider instrumentor’s model calls)
• On an agent given agent_config()’s capability: the prompt version, the variable names it filled, any skill outage, and the skills offered, loaded and delivered, each delivery with the exact version the model received
• Skills the harness’s decimalai.pydantic_ai_harness.skills() capability loads, as activations

​

Moving from SDK 0.18

# 0.18
from decimalai.pydantic_ai import instrument
instrument(enable_skill_loader=True)
agent = Agent("openai:gpt-4o-mini", name="support-agent",
              system_prompt="You are a support agent.", tools=[lookup_order])

# 0.19
from decimalai.pydantic_ai import agent_config

support = agent_config("support-agent", fallback="You are a support agent.")
agent = Agent("openai:gpt-4o-mini", name=support.name, tools=[lookup_order],
              capabilities=[support])

​

What’s next