Anthropic Messages API

​

Install

pip install "decimalai[anthropic]"

​

Use

import anthropic
from anthropic import beta_tool
from decimalai.anthropic import agent_config

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


@beta_tool
def lookup_order(order_id: str) -> str:
    """Look up the status of an order.

    Args:
        order_id: The order id, for example A1001.
    """
    return f"Order {order_id} shipped yesterday."


question = "Where is order A1001?"
with support.run(question) as run:      # one user message = one run = one trace
    answer = client.beta.messages.tool_runner(
        model="claude-haiku-5-5",
        max_tokens=4096,
        system=run.system,               # the saved prompt, then the skill list
        tools=[lookup_order, *run.tools],  # your tools, then load_skill
        messages=[{"role": "user", "content": question}],
    ).until_done()
print("".join(block.text for block in answer.content if block.type == "text"))

• 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 prompt. With no key at all, the agent runs without a DecimalAI key: the project’s skills and public registry matches, no traces.
• support.run(question) routes the agent’s skill list on question and opens the run’s trace. It calls no model: make the model calls inside the with block. A Tool Runner sends nothing until it is consumed, so consume it there too (until_done(), or a for loop over it).
• run.system is a list of text blocks: the saved prompt, then the agent’s skill list with one sentence telling the model to load a skill before using it. The last block carries a prompt-caching breakpoint, so a run’s later requests read the first one’s cache. See Prompt caching.
• run.tools holds the load_skill tool for the beta Tool Runner, 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. A refusal (an unknown name, an outage) comes back as text the model can read, marked is_error.
• support.name is the agent’s name in DecimalAI, and the name every run is routed and traced for.
• No decimalai.init(). With a key, agent_config() initializes the SDK from DECIMAL_API_KEY and turns its tracing on itself. init() refuses to start without a key, so a file that calls it cannot run keyless.

​

Your own messages.create() loop

with support.run(question) as run:
    messages = [{"role": "user", "content": question}]
    while True:
        response = client.messages.create(
            model="claude-haiku-5-5", max_tokens=4096,
            system=run.system, tools=[*my_tool_params, *run.tool_params], messages=messages,
        )
        messages.append({"role": "assistant", "content": response.content})
        if response.stop_reason != "tool_use":
            break
        results = []
        for block in response.content:
            if block.type == "tool_use":
                results.append(run.tool_result(block) or call_my_tool(block))
        messages.append({"role": "user", "content": results})

​

Chats

chat = support.conversation(variables={"customer": {"name": "Sam"}})   # one per chat
history = []                                                     # the chat's messages, kept with it

with chat.run(question) as run:
    history.append(run.message)                 # the question (+ skills new to this chat)
    runner = client.beta.messages.tool_runner(
        model="claude-haiku-5-5", max_tokens=4096,
        system=run.system, tools=[lookup_order, *run.tools], messages=list(history),
    )
    for message in runner:                      # until_done() returns only the last message
        history.append({"role": "assistant", "content": message.content})
        if reply := runner.generate_tool_call_response():
            history.append(reply)
saved = chat.state                              # JSON: support.conversation(state=saved) resumes it

• run.message is the user turn to send: the question, plus, for an agent whose skill list is cut to fit, the skills routed for this message that the chat has not shown yet, as a second text block. Send it instead of your own user dict, or the model is not shown what this message’s routing picked.
• chat.state is the conversation as JSON-ready data. A server that keeps no chat in memory stores it beside the chat’s history, and support.conversation(state=saved) resumes it in another process, with the same system blocks and tool. A state for another agent, or state= together with variables=, raises ValueError.
• Variables are the conversation’s: they are filled once, at its first message. Put facts that change per message in the user message.

​

Change the prompt without redeploying

with support.run(question, variables={"customer": {"name": "Sam"}}) as run:
    ...

​

Prompt caching

​

How each run’s skills are picked

• The first run is routed before it opens.
• 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. Closing the run does not wait either: the trace is sent once the decision lands.
• An agent with more skills than the list holds is routed before every run, so the list is picked for the message.
• A later message of a conversation shows the conversation’s list. When the list was cut to fit, the message is still routed on its own text, and the skills it picks that the chat has not shown go into run.message. Each load names the decision that showed its skill.

​

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 run.system instead (inject_skill_body, which defaults to on once the tool is off), and run.tools is empty. 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, and an open conversation keeps its system blocks. 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.
• on_unavailable="fail". By default ("continue") a run whose skill list never came back answers without skills, and its trace says so. With agent_config(..., on_unavailable="fail") opening the run raises instead.

• Loading a skill costs a model request. The model asks for the skill in one request and uses it in the next.
• An outage during a run is not an error. If DecimalAI cannot be reached mid-run, load_skill answers with a sentence the model can read.
• Skills come from DecimalAI, not from disk. Anthropic’s own Agent Skills (container={"skills": [...]}) are another way to give an agent skills; an agent given both shows the model two lists.

​

Tracing

• Each run is one trace, filed under support.name, with its model calls, the prompt version, the variable names it filled, and the skills offered, loaded and delivered. A conversation’s runs share its id as the trace’s session_id, so a chat’s messages group together. A run opened inside your own span (a web server’s request span) is a trace of its own, linked to that span.
• Nothing outside a run is sent. A Claude call made outside one, in any client of the process, is held back, even under the app’s own request span, and so are the app’s own spans. decimalai.init(anthropic=True) sends every Claude call; decimalai.init(otel=True), the app’s spans.
• Set up tracing first. Your own OpenTelemetry tracer provider, and decimalai.init(otel=True) or init(crewai=True), go before the first agent_config(), as they do before init(anthropic=True): OpenTelemetry sets the global provider once.
• Another tool’s tracing. When the instrumentor was turned on outside DecimalAI (Phoenix, Langfuse, your own setup), DecimalAI does not turn it on again; its runs are traced as long as that tracing sends its spans to the global tracer provider, and a run that got none of its calls says so in a warning.
• Reading each trace. agent_config(..., on_trace=fn) calls fn once per run with a copy of the finished trace before it is sent. A run made inside decimalai.start_trace() is linked to it.

​

What gets captured

• One trace per run: each model request with its input and output, and each load_skill result as a tool message in the next request’s input
• 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
• An auto-detected manifest: the model and each tool, by name. Not the system text: a run’s prompt is the saved one, whose version each trace names.
• Cache reads and writes, from each response’s usage

​

Moving from SDK 0.22

# 0.22
from decimalai.anthropic import instrument
instrument(enable_skill_loader=True, agent_name="support-agent")
response = client.messages.create(model=MODEL, max_tokens=1024, system=BASE, messages=messages)

# 0.23
from decimalai.anthropic import agent_config
support = agent_config("support-agent", fallback=BASE)
with support.run(question) as run:
    response = client.beta.messages.tool_runner(
        model=MODEL, max_tokens=1024, system=run.system, tools=[*my_tools, *run.tools],
        messages=[{"role": "user", "content": question}],
    ).until_done()

​

What’s next