What you get
agent_config() gives your own calls to the google-genai SDK their prompt and skills, one user message at a time. You open a run and pass run.system, run.message and run.tools into a chat. It runs before you have a DecimalAI account. DecimalAI changes nothing about how the SDK behaves, so only the requests you give these pieces get them.
Building on Google ADK (LlmAgent) instead? See Google ADK.
Install
google-genai and openinference-instrumentation-google-genai, which agent_config() uses to trace its runs. genai.Client() reads GOOGLE_API_KEY (or GEMINI_API_KEY).
Run with no account
Save this asmain.py:
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.
support.run(question)opens one run for one user message. It calls no model, so make the model calls inside thewithblock.run.systemis the system instruction: yourfallback=(later, the saved prompt), then the skill list and one sentence telling the model to load a skill before using it.run.messageis the user turn, as text. Send it instead of the bare question: in a conversation it can carry more.run.toolsholdsload_skillas a Python function, which automatic function calling declares and calls like your own. The model calls it with a skill’s name and gets the skill’s full text back. A name not on the list gets a sentence back and loads nothing. The list is empty when the run has no skills to offer.
generate_content calls.
To see where the list comes from, read Without a DecimalAI key.
Your own tools
List your functions before*run.tools:
Your own loop
Automatic function calling raisesKeyError when the model asks for a function you did not pass, for example one your saved prompt names. A loop of your own can answer that call instead, and decimalai init <agent> --framework google-genai writes one. It takes run.tool_params, the same load_skill as a function declaration, and answers each call with run.tool_result(call), which returns the function_response part for load_skill and None for any other function:
error key, as text the model can read.
Async
Open the run withasync with support.run(question) as run: for client.aio. run.tools then holds an async function, and await run.atool_result(call) keeps a load off the event loop.
Add a registry skill
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, and decimalai skills add <folder> lists it.
Add a key
main.py again.
- 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.tomlrecords this: commit it. Without a DecimalAI key has the detail. - From now on its skills live on DecimalAI. Each run’s list is picked from them.
- Every run is one trace, filed under
support.name.
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 run gets the saved prompt within a minute, in place of fallback=.
A saved prompt can hold variables, written {{name}}. Pass their values as variables= to support.run(), as dict keys or attributes, so {{customer.name}} reads variables["customer"]["name"] or variables.customer.name:
{{name}} in your fallback= is filled the same way. A variable with no value raises decimalai.MissingPromptVariable, naming it, as the with block opens, so no model call is made.
Conversations
A chat keeps one conversation.support.conversation() holds the system instruction and load_skill its first message got, so a newer saved prompt or skill list reaches the next conversation, not an open one. A chat on Claude explains why: Claude requires it, and other models’ conversations work the same way.
The function in run.tools belongs to its run, so keep the chat’s history in your own contents, not in one client.chats object:
run.messageis the user turn to send: the question, plus, for an agent whose skill list is cut to fit, the skills ranked for this message that the chat has not shown yet.conversation.stateis the conversation as JSON-ready data, andNonebefore its first run.support.conversation(state=saved)resumes it in another process.- Variables are filled once, at the conversation’s first message: pass them to
support.conversation().
Its own skill loader
None. This framework has no skill loader of its own, soagent_config() is the only route.
Tracing
agent_config() turns on Gemini tracing with OpenInference’s instrumentor, which wraps the SDK’s classes for the process, and sends only its runs. 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, delivered and loaded. A conversation’s runs share its id as the trace’s session_id.
A Gemini call made outside a run is held back, and so are the app’s own spans. Set up your own OpenTelemetry tracer provider, and decimalai.init(otel=True), before the first agent_config(). agent_config(..., on_trace=fn) calls fn once per run with a copy of the finished trace.
To trace with no skills, call decimalai.init(google=True). It sends every Gemini call in the process and gives none of them a prompt or skills.
Troubleshooting
KeyErrorfromsend_message(). The model asked for a function you did not pass. Answer it in your own loop, or take its name out of the prompt. AMissingPromptVariableis aKeyErrortoo, but it comes from opening the run and names a prompt variable.no Gemini request was traced inside this run. The model calls ran outside thewithblock, or through a library other thangoogle-genai.run.system names the load_skill tool, but this run's tools never included it. Add*run.tools(automatic function calling) or*run.tool_params(your own loop) totools=.load_skill was called after its run closed. The skill is served, but the run’s record won’t show it. Usually aclient.chatsobject outlived its run: make one inside eachwithblock.- The model never loads a skill. After a run,
print(support)names the prompt version and the skills on its list. With no key, an empty list means.decimal/skills.tomllists nothing. With a key, check that the agent gets the skill. run.toolsis empty though the agent has skills. With a key,DECIMALAI_LOAD_SKILL_TOOL=0ordecimalai.init(load_skill_tool=False)emptiesrun.toolsandrun.tool_params, and the text of the skills picked for each run goes intorun.systeminstead. The other switches are in Turn it off.