agex 0.12.2

Library-friendly agents that work directly with your existing Python codebase.

agex: Library-Friendly Agents

agex (a portmanteau of agent execution) is a Python library for building AI agents that work directly with your code.

You define a typed Python function with @task and the agent fills it in. It writes sandboxed Python that calls into the modules you've whitelisted, returning real Python objects (DataFrames, Plotly figures, your Pydantic models) that flow back into your code unchanged. There's no JSON serialization at the boundary and no separate runtime to deploy: agex runs inside your application's Python process.

Because the sandbox is pure-Python AST rewriting, the same agent code runs in-process, in a subprocess, in a kernel-isolated worker, or (via Pyodide) entirely in a browser tab. agex-studio is the proof-of-concept: pandas, scikit-learn, plotly, and a chat agent all running client-side with no backend.

import pandas as pd
from agex import Agent

agent = Agent()
agent.module(pd)

@agent.task
def summarize(df: pd.DataFrame) -> dict[str, float]:
    """Return summary statistics for the numeric columns."""
    pass

stats = summarize(my_dataframe)  # real dict[str, float]

What you get

• Typed function tasks - @task declares the input/output contract; the agent fulfills it.
• Curated Python environment - whitelist exactly which modules and classes the agent can use, with per-member visibility.
• Versioned workspace - virtual filesystem, the agent's session memory, and event log are all kvgit-backed, with checkpoints and time-travel.
• Multi-agent orchestration - coordinate agents with regular Python control flow; sub-agents are just functions.
• Flexible execution - in-process by default; subprocess, kernel-isolated, browser (Pyodide), or remote (Modal, HTTP) when you need them.

For a deeper dive, see the agex101 tutorial or the geospatial routing example for multi-library integration. For a NiceGUI integration demo, see agex-ui.

Documentation

Complete documentation is hosted at ashenfad.github.io/agex.

Key sections:

• 📚 Quick Start Guide
• 🔭 The Big Picture
• 💡 Examples
• 📖 API Reference

Installation

Install agex with your preferred LLM provider:

pip install "agex[openai]"        # OpenAI models
pip install "agex[anthropic]"     # Anthropic Claude models
pip install "agex[gemini]"        # Google Gemini models

# Or with all providers
pip install "agex[all-providers]"

Project Status

This is a hobby project in active development. The core concepts are stabilizing but the API should be considered experimental.

If you're looking for a more battle-tested library built on the same "agents-that-think-in-code" idea, smolagents (Hugging Face) is the closest cousin and a good choice. agex explores a different shape: an embeddable library you import into your application, with typed function contracts and a pure-Python sandbox that runs anywhere Python runs (including the browser).

Built On

agex is composed of several focused libraries that can also be used independently:

Library	Purpose
sandtrap	In-process Python sandbox via AST rewriting
kvgit	Versioned key-value store with git-like semantics
monkeyfs	Filesystem interception via monkey-patching
termish	Virtual terminal with shell-like commands
reprobate	Budget-controlled repr for Python objects

Contributing

Bug reports, ideas, and pull requests welcome - see GitHub Issues or the Contributing Guide.