Agents in the database, not in the repo: a tour of apowerb
The usual way to define an agent is to write it: a Python file that declares a model, attaches tools, carries the instruction. You commit it, you deploy it. That is a good default — the definition is versioned, reviewable, testable — and it holds right up to the moment a non-engineer needs to change a prompt, or you are running forty agents for twelve teams and every wording fix has become a…
Traditionally, defining an agent involves writing a Python file that declares a model, attaches tools, and carries the instruction. This definition is versioned, reviewable, and testable, but becomes cumbersome when non-engineers need to make small changes like tweaking prompts or when multiple agents are required across various teams.
Apowerb takes a different approach: an agent is simply a row in a Postgres database. The Python code that the runtime imports is generated, disposable, and only seven lines long. Changing an agent is as simple as updating the corresponding row in the database, rather than deploying a new version. Apowerb is licensed under Apache-2.0, built on FastAPI and Google ADK (the Agent Development Kit), and can self-host with Docker Compose.
This article will explore the design aspects of Apowerb, highlighting some of the challenges and solutions encountered during its development.
Creating an agent through the user interface is a straightforward process. You provide a name, category, and provider, and the form writes a database row. The framework then generates a directory under agents_pool/ named after the agent's ID and places the generated module inside it. This module contains a stub that points to a loader.
Everything defining the agent, such as the instruction, model, tools, sub-agents, guardrails, and output schema, is read from the database at load time by the to_agent function. The model is stored as a string, and the agent type is also a database column. Notably, the API key is not required for the definition to exist; the agent can function without it until a credential is added later.
One advantage of this design is that the editing surface for an agent is an API and a user interface, rather than a repository. This approach simplifies the process of making small adjustments to an agent's definition. However, the downside is that the filesystem ends up storing derived state, which can drift over time. To address this, the boot sequence includes a repair function that ensures agent modules are regenerated or fixed if they become stale.
This repair occurs at startup, allowing the environment to heal itself on the next restart instead of requiring manual intervention each time an agent is saved.
Written by urgent.news from Dev.to's reporting — not their text. Machine-written — may contain errors; check the original before relying on it.
