Skip to main content

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

The extra installs 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 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.
  • support.run(question) opens one run for one user message. It calls no model, so make the model calls inside the with block.
  • run.system is the system instruction: your fallback= (later, the saved prompt), then the skill list and one sentence telling the model to load a skill before using it.
  • run.message is the user turn, as text. Send it instead of the bare question: in a conversation it can carry more.
  • run.tools holds load_skill as 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.
Keep automatic function calling in a chat, as here: google-genai says its next major version removes it from direct 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 raises KeyError 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:
A refusal (an unknown name, an outage) comes back under the part’s error key, as text the model can read.

Async

Open the run with async 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

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, and decimalai skills add <folder> lists it.

Add a key

Get one from Settings → API keys, and run 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.toml records 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:
A {{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.message is 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.state is the conversation as JSON-ready data, and None before 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, so agent_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

  • KeyError from send_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. A MissingPromptVariable is a KeyError too, 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 the with block, or through a library other than google-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) to tools=.
  • load_skill was called after its run closed. The skill is served, but the run’s record won’t show it. Usually a client.chats object outlived its run: make one inside each with block.
  • 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.toml lists nothing. With a key, check that the agent gets the skill.
  • run.tools is empty though the agent has skills. With a key, DECIMALAI_LOAD_SKILL_TOOL=0 or decimalai.init(load_skill_tool=False) empties run.tools and run.tool_params, and the text of the skills picked for each run goes into run.system instead. The other switches are in Turn it off.