Skip to main content

What you get

agent_config() gives a Google ADK agent its prompt and skills as two pieces, which you pass into your own LlmAgent(...): an instruction provider and a load_skill tool. It runs before you have a DecimalAI account, using skills in your project. With a key, you can change the agent’s prompt and skills in the dashboard without redeploying, and DecimalAIPlugin() in your App traces every invocation. Nothing in ADK is patched. Only an agent you give these pieces gets DecimalAI’s prompt and skills, and only the runners built from that App are traced. This page is for agents built on ADK. Calling the google-genai SDK yourself? See Gemini API.

Install

The extra brings google-adk, which depends on google-genai, the source of the program’s types. It needs Python 3.11 or later. On Python 3.10, pip quietly installs a much older decimalai with no agent_config(), and pip show decimalai tells you which one you got.

Run with no account

Save this as main.py:
Run it. With no DECIMAL_API_KEY, it says so once on stderr and sends nothing to DecimalAI. The project has no skills yet, so the model guesses the command.
  • agent_config("my-agent", fallback=...) names the agent. fallback= is the prompt until a saved one exists.
  • instruction=support.instruction is an ADK instruction provider, which ADK calls before each model request. It returns the prompt, then the agent’s skill list and one sentence telling the model to load a skill before using it.
  • *support.tools adds one tool, load_skill. The model calls it with a skill’s name and gets the skill’s full text back.
  • name="my_agent" is ADK’s own name, which has to be a Python identifier. A DecimalAI name with a hyphen isn’t one, so the two can differ. Each invocation is routed and traced under support.name either way.
  • runner.run_async(...) is one invocation. runner.run(...) is its synchronous form.
To see where the list comes from, read Without a DecimalAI key.

Your own tools

List your tools before *support.tools:

Other models

For a model that isn’t Gemini, ADK goes through LiteLLM. Run pip install "google-adk[extensions]", then from google.adk.models.lite_llm import LiteLlm and pass model=LiteLlm(model="openai/gpt-5.4-mini"). Gemini 2.x model ids are retired upstream, so use gemini-3.5-flash or newer.

Add a registry skill

Run main.py again. The model loads the skill and gives the real command, playwright-cli attach --cdp=http://localhost:9222. The command wrote the skill’s files to .agents/skills/, listed it in .decimal/skills.toml, and recorded its exact bytes in .decimal/skills.lock. To find others, see Browse the registry. A skill you wrote goes in the same folder.

Add a key

Get one from Settings → API keys. ADK needs one change to main.py before its runs are traced: build the runner from an App holding DecimalAIPlugin().
DecimalAIPlugin() is the one line ADK adds to agent_config(): the plugin is what makes an invocation a trace, and agent_config() doesn’t install it. With no key it does nothing, so the same file still runs keyless. Don’t add decimalai.init(): agent_config() reads the key itself, and init() refuses to start without a key, so a file that calls it can’t run keyless.
  • The first run connects the project. The agent is created in your workspace, and your project’s skill list is copied onto it once. In a git repository, .decimal/link.toml records this: commit it.
  • From now on its skills live on DecimalAI. Each invocation’s list is picked from them.
  • Every invocation is one trace, filed under support.name. See Tracing.
  • Your fallback= keeps running until you save a prompt.
A name your workspace has no agent by is created, so a misspelled name makes a new agent rather than an error. The detail is in Without a DecimalAI key.

Change the prompt without redeploying

Write a prompt on the agent’s Prompt & skills page and save it. agent_config() keeps a local copy and re-reads it in the background at most once a minute, so the next invocation gets the saved prompt within a minute, in place of fallback=. A version pinned through the API works the same way. With a key, fallback= is what runs when the agent has no saved prompt or DecimalAI can’t be reached at startup. A saved prompt can hold variables, written {{name}}. There’s no variables= argument on this framework: they’re filled from the session’s state, as dict keys or attributes. A dotted name walks down, so {{customer.name}} reads state["customer"]["name"].
A {{name}} in your fallback= is filled the same way. A variable with no value stops the invocation before the model request, with a decimalai.MissingPromptVariable error that names it. DecimalAI fills only the prompt, never a skill’s text, and the trace keeps the variables’ names, not their values. ADK fills no {var} of its own in an instruction provider’s text, so {{name}} is the only template syntax in play.

Conversations

A session is a conversation. Run each message with the same session_id, and ADK keeps the history. There’s no support.conversation() on this framework: the session is the state.
  • On a Claude model, a session keeps its first invocation’s instruction and load_skill. A chat on Claude explains why. This applies to AnthropicLlm, Claude, and LiteLlm with a Claude model. A newer saved prompt or skill list reaches the next session, and variables keep the values of the session’s first invocation.
  • The plugin carries that copy between processes. DecimalAIPlugin keeps it in the session’s state, under _decimalai_conversation, so it reaches any process that serves the session from a persistent session service. Without the plugin, only the process that served the first invocation has it.
  • On Gemini and other models, every invocation gets the newest prompt.

Its own skill loader

ADK can read skill folders itself, with its SkillToolset. decimalai.adk.skills() gives the toolset your installed skills, and the plugin records each load:
The model finds the skills through ADK’s list_skills tool and reads one with load_skill. decimalai.init() needs a key, so with no key, leave that line out: the toolset still loads skills, with nothing recorded.
  • Each load counts as Loaded, with the version of the text ADK handed the model, and the names list_skills returns count as Offered. A skill loaded twice in one invocation counts once.
  • It reads the whole folder. Every skill folder in .agents/skills is offered, whether or not .decimal/skills.toml lists it.
  • ADK keeps serving the version it read. It 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 record names the version it actually served.
  • Don’t also give this agent agent_config()’s pieces. The toolset is already its catalog, so DecimalAI adds neither its skill list nor load_skill, and one warning says so.
  • 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. decimalai skills verify reports what a loader would reject.
  • On-demand skills are offered anyway. ADK ignores disable-model-invocation.
Native skill loaders covers how the version is decided and how the other frameworks compare.

Tracing

App(name=..., root_agent=agent, plugins=[DecimalAIPlugin()]) makes each invocation (one run_async or run) one DecimalAI trace. A runner built without the plugin is not traced, and an agent_config() agent it runs logs one warning per agent saying so, with the line to add. With no key, nothing is traced.
  • What’s in the trace: model calls, tool calls with their inputs and results, sub-agent activity, and errors.
  • What agent_config() adds: the prompt version, the variable names it filled, any skill outage, and the skills offered, delivered and loaded, each with the exact version the model received.
  • Which agent it’s filed under. An invocation of an agent given support.instruction is filed under support.name. Any other 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. For a runner that runs as a sub-agent of another orchestrator, pass the parent’s trace id as DecimalAIPlugin(parent_trace_id=...).
  • DecimalAIPlugin(on_trace=fn) calls fn once per invocation, failed ones included, with a copy of the finished trace before it’s sent. An fn that raises is logged and changes nothing else.
  • The manifest (the agent’s setup, which DecimalAI versions) comes from the root agent: model, instruction, sub-agents, and tools by name and description. For regression checks on tool schemas, register it yourself.
To trace with no skills, there’s no init() flag. Call decimalai.init(), leave out agent_config()’s pieces, and put DecimalAIPlugin() in the App. adk web and adk run load a module-level app before a root_agent, so define app as above in your agent.py and the plugin comes with it.

Troubleshooting

  • this run is not traced, so its prompt version and skills are recorded nowhere. No DecimalAIPlugin is in the App that ran it. Add one as in Add a key.
  • DecimalAI skills are off for this agent: it carries ADK's own SkillToolset. The agent has both routes. Its prompt still runs. Keep one: see Don’t deliver a skill two ways.
  • DecimalAI skills are off for this agent: it has another tool named load_skill. Rename your tool to give the agent its skills. Its prompt still runs.
  • from decimalai.adk import agent_config fails. You’re on Python 3.10, so pip settled for an older decimalai without saying so. Upgrade Python.
  • ADK rejects name="my-agent" as not a valid identifier. Use my_agent for ADK’s name=, and keep my-agent in agent_config().
  • The model never loads a skill. After a run, print(support) names the prompt version and the skills on its list, for example ADKAgentConfig(name='my-agent', prompt_version=3, skills=['playwright-cli']). With no key, an empty list means .decimal/skills.toml lists nothing. With a key, check that the agent gets the skill.
  • agent_config() raises at startup while DecimalAI is down. With a key and no fallback=, it raises instead of starting an agent with no instruction. Pass a fallback=.
  • DecimalAI goes down during an invocation. That isn’t an error. It keeps the last skill list DecimalAI returned, and load_skill answers with a sentence the model can read.
Loading a skill costs a model request: the model asks for it in one request and uses it in the next. The switches every framework shares are in Turn it off.