DB (Raw SQLite)

Agents can work directly with a live stateful objects like an sqlite3.Connection while still persisting their compute environment.

Create an agent and give it access to a live object:

import sqlite3
from typing import Any
from agex import Agent

# Create an architected DB agent with guidance (see primer idea below)
db = Agent(name="db_agent")

# In-memory database for the demo
conn = sqlite3.connect(":memory:")

# Register instance methods just like a module; name is required for instances
db.module(conn, name="db", include=["execute", "executemany", "commit"])

# Also register the Cursor class methods used to collect results
import sqlite3 as _sqlite

db.cls(_sqlite.Cursor, include=["fetchone", "fetchall", "fetchmany"])

Define task fns (agent implements at call time):

@db.task
def update_db(prompt: str):  # type: ignore[return-value]
    """Update the database based on a natural language description."""
    pass

@db.task
def query_db(prompt: str) -> Any:  # type: ignore[return-value]
    """Query the database and return structured results."""
    pass

Ask the agent to create a table and then follow up with questions about it:

from agex import Versioned

state = Versioned()

# Create schema and populate rows
update_db("Create a 'users' table with columns: id, name, email, age", state=state)
update_db("Add 10 users to the users table", state=state)

# Ask questions in natural language
oldest = query_db("Who is the oldest user?", state=state)
print(oldest)
# {'id': 10, 'name': 'User10', 'email': 'user10@example.com', 'age': 30}

# You can also inspect the real DB in host code
print(conn.execute("SELECT COUNT(*) FROM users").fetchone()[0])
# 10

Working with live objects like a database connection while also using Versioned state is one of agex's most compelling features. Unpicklable objects (like cursors) are automatically handled - they work naturally in single-turn use, and provide clear error messages if accidentally reused across turns.

—

Source: https://github.com/ashenfad/agex/blob/main/examples/db.py

Primer: https://github.com/ashenfad/agex/blob/main/examples/db_primer.py