avo

Provider-agnostic reliability runtime for bounded, observable, resumable, replayable AI agent loops.

Bounded. Resumable. Provider-agnostic. Honest about why it stopped.

⚠️ 0.1 is an alpha foundation. Suitable for evaluation, deterministic tests, and local prototypes; not production-ready.

Install

Requires Python 3.11+. Core runtime depends only on Pydantic.

git clone https://github.com/Fqih/avo.git
cd avo
python -m pip install -e ".[dev,providers,sandbox]"

Optional extras

Verify the install:

avo doctor

Prints resolved provider / model / endpoint without an HTTP call — cheapest smoke test.

Quickstart

One typed tool call, then a final reply. No API key:

import asyncio
from pydantic import BaseModel

from avo import (
    AgentRuntime, FunctionTool, ModelResponse, TokenUsage, ToolCall,
)
from avo.providers import FakeProvider


class AddArguments(BaseModel):
    left: int
    right: int


async def add(arguments: AddArguments) -> object:
    return {"sum": arguments.left + arguments.right}


async def main() -> None:
    provider = FakeProvider(
        [
            ModelResponse(
                tool_call=ToolCall(
                    tool_call_id="addition-1", name="add",
                    arguments={"left": 2, "right": 3},
                ),
                usage=TokenUsage(input_tokens=12, output_tokens=5),
            ),
            ModelResponse(
                content="The sum is 5.",
                usage=TokenUsage(input_tokens=18, output_tokens=6),
            ),
        ]
    )

    runtime = AgentRuntime(
        provider=provider,
        tools=[
            FunctionTool(
                name="add",
                description="Add two integers.",
                arguments_model=AddArguments,
                function=add,
            )
        ],
    )
    result = await runtime.run("What is 2 + 3?")
    print(result.status.value, result.stop_reason.value, result.output)


asyncio.run(main())

examples/basic_agent.py ships this runnable end-to-end.

Configuration

All knobs live in AVO_* env vars. The chat REPL's first-run wizard can persist them to ~/.zshrc / ~/.bashrc.

Provider selection

Runtime + policy

See .env.example for a copy-paste template.

Providers

All six implement the same ModelProvider Protocol. Swapping providers is one line.

Application tools

avo.app_tools is the optional-but-default toolkit. Tools plug into the existing
FunctionTool / ToolRegistry contract — no changes to the runtime, state machine, or
event log.

Workspace safety

Workspace(root).validate_path(...) rejects ../, symlink escapes, absolute-path
escapes, and null bytes before any I/O. validate_for_write refuses to follow
symlinks at the leaf or any parent. write_file / edit_file open with O_NOFOLLOW on
POSIX. No path the model can ask for exits the workspace root.

Shell sandbox

SandboxExecutor wraps docker-py. Each run_shell call creates a fresh container
(remove=True), runs with network_mode="none" by default, applies a mem_limit and
cpu_quota, times out via the runtime's LoopPolicy.tool_timeout_seconds, and removes
the container before returning. run_shell never calls subprocess on the host — the
sandbox is the only path to the shell.

Suit the network policy to your task:

from avo.app_tools.sandbox import SandboxExecutor

sandbox = SandboxExecutor(
    network_mode="bridge",  # default "none" — switch when network is required
    mem_limit="512m",
    cpu_quota=100000,
)

Approval policy

AVO_TOOLS_REQUIRE_APPROVAL lists tool names that must wait for explicit operator
approval. Tools not in the list auto-approve. Wire a custom callback:

from avo.app_tools.approval import build_approval_callback

callback = build_approval_callback(
    on_require=lambda call: input(f"approve {call.name}? [y/N] ").lower() == "y",
)
runtime = AgentRuntime(provider=provider, tools=[...], approval_callback=callback)

Observability (OpenTelemetry)

Set AVO_OTEL_ENABLED=1 and the runtime wraps every _drive invocation in a span
tagged with the gen_ai.* semantic conventions:

python -m pip install -e ".[otel]"
export AVO_OTEL_ENABLED=1
export OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4317
avo chat

Spans carry avo.run_id, gen_ai.system (provider name), and gen_ai.request.model.
avo.observability.record_usage(...) writes input / output token counts into the
active span, so cost rollups line up with trace data. The module is a noop when the
extra is not installed — no exceptions at import time, no runtime overhead.

Cost tracking

avo cost aggregates every persisted ledger entry (the same avo.db the event store
uses) and prints total tokens + USD spend, with per-run and per-model breakdowns.
Output is human-readable by default and machine-readable with --json:

avo cost --database avo.db --json

{
  "run_count": 2,
  "total": {"input_tokens": 700, "output_tokens": 370, "total_tokens": 1070},
  "cost_usd": "0.0142",
  "runs": [...],
  "models": [...]
}

Set AVO_USAGE_RATES_INPUT_PER_1K / AVO_USAGE_RATES_OUTPUT_PER_1K to seed the ledger
with USD costs as each provider call returns.

Scaffolding plugins

avo plugin init writes a working plugin to disk so you can iterate on a new tool
without touching project structure by hand:

mkdir ~/projects/my-tool && cd ~/projects/my-tool
avo plugin init my-tool
cd my-tool
avo plugin install .    # registers the sample echo tool

The scaffold ships a pyproject.toml declaring an avo.tools entry point, a
register() stub returning a sample FunctionTool, a README.md, and a .gitignore.
Replace the sample tool with your own and the runtime picks it up on the next
avo plugin install ..

CLI

avo [-d DATABASE] <command> [args]

Chat REPL slash commands

Examples

examples/ ships runnable Python files, all offline (no API key):

python examples/basic_agent.py
python examples/repeated_action.py
python examples/resume_after_interrupt.py
python examples/app_tools_demo.py

Development

python -m pip install -e ".[dev,providers,sandbox]"
ruff check .
ruff format --check .
mypy src/avo
pytest

Quality gates:

• ruff lint + format — line-length 100, per-file ignores for examples/, benchmark/.
• mypy strict on src/avo (Pydantic plugin).
• pytest --strict-config --strict-markers, asyncio mode auto.
• coverage branch coverage, fail-under 90%.

The suite needs no Docker — SandboxExecutor accepts an injectable client so tests
inject a fake and assert the container config that would be sent. Live Docker integration
is opt-in, same pattern as benchmark/live/tests/.

License

MIT — see LICENSE.