agex
Agents that work in a versioned world.
agex is an agent loop over nontainer workspaces: a filesystem, a shell and sandboxed Python, with history. It has two front doors:
- A session drives a workspace turn by turn. Its conversation is stored in the workspace's branch, so checking out a commit rewinds the agent's memory with its files, and a fork carries both.
- A task is a typed function an agent runs on a world of its own and answers with a value of the declared type.
pip install "agex[anthropic]" # or [openai], [openrouter], [google], [all]
A session
from agex import Agent
from nontainer import Store
agent = Agent("anthropic:claude-sonnet-5-5")
store = Store(memory=True)
ws = store.open("demo")
chat = agent.session(ws)
out = chat.say("Write fib.py printing the first ten Fibonacci numbers, and run it.")
print(out.status, out.text) # completed, and the model's reply
print(ws.files.read("fib.py").decode()) # the file it wrote
out = chat.say("Make it print twenty.") # it remembers the last turn
Tool calls that change the workspace commit as they land, and a turn's
end lands one more commit, stamped with how the run ended: completed,
cancelled, failed or interrupted. None of them raise.
A task
from dataclasses import dataclass
@dataclass
class Recipe:
name: str
steps: list[str]
minutes: int
@agent.task
def plan_dinner(ingredients: list[str]) -> Recipe:
"""A dinner recipe using only these ingredients, plus salt and oil."""
...
recipe = plan_dinner(["eggs", "spinach", "feta"]) # a Recipe
The docstring is the job, and the body holds no code (... is for a
type checker). The agent works in a scratch world (or a fork of
world=), and its code hands back the value with task.success(...).
The value is checked against the return type, so the caller gets a
Recipe or a TaskFailed.
Agent-defined tasks
A session's agent can define tasks of its own, for the judgment work in
a script: classify, extract, summarize. Grant agex to its workspace:
from agex import agent_tasks
from nontainer import Profile, PythonConfig
profile = Profile(python=PythonConfig(host_objects={"agex": agent_tasks(agent)}))
ws = store.open("reviews", profile=profile)
and the agent's code can write
@agex.task
def sentiment(review: str) -> str:
"""positive, negative or mixed"""
labels = sentiment.map(reviews) # helpers run them at once
More
- Quick start: install, the first session and task, reading an outcome
- Examples: runnable scripts for each of the above
- Design notes: the shape, and why
- Plan: what is done and what is next
agex 0.13 is a new API. The 0.12 line, agents working directly with an
existing Python codebase, is at the
v0.12.4 tag and on
PyPI as agex==0.12.4.
Development
uv sync
uv run pre-commit install --hook-type pre-commit --hook-type pre-push
uv run pytest
See CONTRIBUTING.md.
1 maintainer
Metadata
1 maintainer
Release files for agex 0.13.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| agex-0.13.0.tar.gz | 217.5 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| agex-0.13.0-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 343.4 kB
Release files / agex-0.13.0.tar.gz
| Download URL | agex-0.13.0.tar.gz |
|---|---|
| Size | 217.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
224ac795b197115d41d3eda520fa566e05ed55e5f8918aa769eddf7b6408b3c2
|
|
BLAKE2b-256 checksum How to use checksums |
2623aca0b78c749377f6c5b579d7f6de0bbcf74207039c7b6ad00c8d0d20c20e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
Release files / agex-0.13.0-py3-none-any.whl
| Download URL | agex-0.13.0-py3-none-any.whl |
|---|---|
| Size | 125.9 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0fd51a14b0a9d8235c316dcf4fa2d72c08173d3e1e6b7c50bb1ef214815d1c58
|
|
BLAKE2b-256 checksum How to use checksums |
ab0b8392e5629b5debaf5d8b7aef8162f3092f43ff7ca5ccd8be763926feb6d7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.12.15
|
