Google ADK

​

Install

pip install "decimalai[adk]"

​

Use

import asyncio

from decimalai.adk import DecimalAIPlugin, agent_config
from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.runners import InMemoryRunner
from google.genai import types


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 = LlmAgent(
    name="support_agent",                  # ADK's own name: a Python identifier
    model="gemini-3.5-flash",
    instruction=support.instruction,       # the saved prompt, then the skill list
    tools=[lookup_order, *support.tools],  # your tools, then load_skill
)
app = App(name="support", root_agent=agent, plugins=[DecimalAIPlugin()])
runner = InMemoryRunner(app=app)


async def main():
    session = await runner.session_service.create_session(app_name="support", user_id="u1")
    async for event in runner.run_async(
        user_id="u1",
        session_id=session.id,
        new_message=types.Content(role="user", parts=[types.Part(text="Where is order 1001?")]),
    ):
        if event.is_final_response():
            print(event.content.parts[0].text)


asyncio.run(main())   # one invocation = one trace

• 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 instruction. With no key at all, the agent runs without a DecimalAI key: the skills your project lists in .decimal/skills.toml, with nothing sent.
• instruction=support.instruction is an ADK instruction provider, which ADK calls before each model request. It returns the saved prompt, then this agent’s skill list, chosen for the invocation’s message, and one sentence telling the model to load a skill before using it.
• load_skill is support.tools’ 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 invocation’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 invocation’s list showed it, while one reachable only through the public registry loads only when this invocation was offered it.
• support.name is the agent’s name in DecimalAI, and the name every invocation is routed and traced for. ADK’s own name= has to be a Python identifier, which a DecimalAI name with a hyphen is not, so the two can differ: the trace is filed under support.name either way.
• DecimalAIPlugin() goes in the App, ADK’s place for plugins (Runner(plugins=...) is deprecated). It is the one line ADK adds to agent_config(): the plugin is what makes an invocation a trace, and agent_config() does not install it. Tracing has what it records. With no key it does nothing, so the same file runs keyless.
• No decimalai.init(). With a key, agent_config() initializes the SDK from DECIMAL_API_KEY itself. init() refuses to start without a key, so a file that calls it cannot run keyless.

​

Change the prompt without redeploying

async def main():
    # A prompt saying "The customer is {{name}}, a {{tier}} member" reads these two keys
    session = await runner.session_service.create_session(
        app_name="support", user_id="u1", state={"name": "Sam", "tier": "gold"},
    )
    message = types.Content(role="user", parts=[types.Part(text="Where is my order?")])
    async for event in runner.run_async(user_id="u1", session_id=session.id, new_message=message):
        if event.is_final_response():
            print(event.content.parts[0].text)

​

How each invocation’s skills are picked

• The first invocation is routed before its first model request.
• Later invocations show the local copy of the list, and their own routing decision is recorded in the background, so no invocation waits on it.
• An agent with more skills than the list holds is routed before every invocation, so the list is picked for the message.
• A later invocation of a Claude session shows that session’s list. Its own decision is recorded in the background, or, when the list was cut to fit, the invocation 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 invocation is routed and the text of the skills picked for it goes into the instruction 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 invocation 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.
• An outage during an invocation is not an error. If DecimalAI cannot be reached mid-invocation, it 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 ADK’s SkillToolset below.

​

Tracing

• The trace’s agent. An invocation of an agent given agent_config()’s instruction is filed under support.name, with the prompt version, the variable names and the skills offered, loaded and delivered. Any other invocation is filed under DecimalAIPlugin(agent_name=...), else the agent decimalai.init(agent_name=...) named (or DECIMAL_AGENT_NAME), else the ADK root agent’s name.
• Linking runs. An invocation made inside decimalai.start_trace() is filed as that trace’s child, through runner.run(...) too. For a runner that runs as a sub-agent of another orchestrator, pass the parent’s trace id as DecimalAIPlugin(parent_trace_id=...).
• Reading each trace. DecimalAIPlugin(on_trace=fn) calls fn once per invocation, failed ones included, with a copy of the finished trace before it is exported. An fn that raises is logged and changes nothing else.

​

Load installed skills with ADK SkillToolset

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

import decimalai
import decimalai.adk
from decimalai.adk import DecimalAIPlugin
from google.adk.agents import LlmAgent
from google.adk.apps import App
from google.adk.code_executors.unsafe_local_code_executor import UnsafeLocalCodeExecutor
from google.adk.tools.skill_toolset import SkillToolset

decimalai.init(api_key="dai_sk_...", agent_name="support")

skilled_agent = LlmAgent(
    name="support",
    model="gemini-3.5-flash",
    instruction="Answer support questions concisely.",
    tools=[SkillToolset(
        skills=decimalai.adk.skills(),
        # Runs a skill's scripts on this machine, unsandboxed. Without an
        # executor, ADK offers no run_skill_script tool.
        code_executor=UnsafeLocalCodeExecutor(),
    )],
)
app = App(name="support", root_agent=skilled_agent, plugins=[DecimalAIPlugin()])

• Each load is an activation (SDK 0.16.0+). The plugin records every load_skill result as an activation carrying the version of the body ADK handed the model, and the names list_skills returns as offered. A skill loaded twice in one invocation is one activation.
• ADK keeps serving the version it loaded. ADK parses the folders when decimalai.adk.skills() runs, so an agent built before decimalai skills update serves the old version until you build it again. The activation names the version it actually served.
• Don’t also give this agent agent_config()’s pieces. The toolset is already its catalog, so DecimalAI would add neither its skill list nor load_skill, and one warning says so. If one invocation’s requests carried both catalogs anyway (the toolset on one agent, agent_config()’s instruction on another), a WARNING says so once: give the toolset to the agent that uses it.
• One bad folder costs only itself. decimalai.adk.skills() loads each folder on its own and skips one ADK refuses, with a WARNING that names it; ADK’s own load_skills_from_dir raises on one bad folder and loads nothing at all. decimalai skills verify reports what a loader would reject.
• On-demand skills are offered anyway. ADK ignores disable-model-invocation, so a skill the registry marks on-demand is listed to the model like any other.

​

What gets captured

• One trace per invocation: model calls, tool calls with their inputs and results (matched to each call by ADK’s function-call id, so parallel calls to one tool each get their own), and sub-agent activity
• On an agent given agent_config()’s instruction: 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. A load_skill result is in the next model call’s input on the trace.
• An auto-detected manifest from the root agent: model, instruction (system prompt), tools (names + descriptions), and sub-agents
• Errors: model and tool errors mark their span; the invocation’s end status is recorded on the trace

​

Moving from SDK 0.19

# 0.19
decimalai.init(adk=True, agent_name="support-agent")
agent = LlmAgent(name="support_agent", model="gemini-3.5-flash",
                 instruction="You are a support agent.", tools=[lookup_order])
runner = InMemoryRunner(agent=agent)

# 0.20
from decimalai.adk import DecimalAIPlugin, agent_config

support = agent_config("support-agent", fallback="You are a support agent.")
agent = LlmAgent(name="support_agent", model="gemini-3.5-flash",
                 instruction=support.instruction, tools=[lookup_order, *support.tools])
runner = InMemoryRunner(app=App(name="support", root_agent=agent, plugins=[DecimalAIPlugin()]))

​

What’s next