Skip to content

AAA

Autonomous Agent Architecture

The architecture and runtime for autonomous agents.

Build · Orchestrate · Execute · Recover · Manage

An async, event-driven architecture for production agents: the algorithms, the durable runtime, tools, memory, evals and guardrails, over data of any shape, with any LLM gateway.

pip install autonomous-agent-architecture · import aaa · "AAA" is the short name.

AAA is for the part of an agent system that is not the model: the loops, plans, routing, retries, budgets, approvals, persistence and recovery that decide whether an agent is a demo or something you can put on call. It gives you ready-made algorithms (tool loops, ReAct, plan-and-execute, routers, supervisors, generate-test-repair, workflows, state machines, RAG, voting, Reflexion, debate, swarm handoffs, tree-of-thoughts) and the runtime that makes them durable, bounded and observable.

"""Quickstart: a tool-using agent in ~25 lines. Runs offline with a scripted model."""

import asyncio

from aaa.algos import ToolLoop
from aaa.llm import FakeLLMClient, LLMHandler
from aaa.llm.fake import text, tool_call
from aaa.runtime import Budget, Engine
from aaa.tools import ToolHandler, ToolRegistry, tool


@tool
def multiply(a: int, b: int) -> int:
    """Multiply two integers."""
    return a * b


def scripted_model(request):  # stands in for a real LLM (see "LLM gateways" to swap it)
    last = request.messages[-1]
    if last.role == "user":  # first turn: the model asks for the tool
        return tool_call("multiply", a=17, b=23)
    return text(f"17 x 23 = {last.content}")  # second turn: it answers using the tool result


async def main() -> None:
    registry = ToolRegistry([multiply])
    async with Engine() as engine:
        LLMHandler(FakeLLMClient(scripted_model)).attach(engine)  # who answers LLM requests
        ToolHandler(registry).attach(engine)  # who runs tool calls
        outcome = await engine.run(
            ToolLoop(registry),
            {"task": "What is 17 times 23?"},
            budget=Budget(max_steps=20, deadline_s=30),
        )
    print(outcome.kind.value, "-", outcome.value["text"])


asyncio.run(main())

success - 17 x 23 = 391

That example runs offline

A scripted model stands in for the LLM so every example in these docs is executable and tested. The LLM gateways guide shows how to point the same code at a real model.

Why AAA

  • The log is the truth

    Every run is an append-only stream of immutable events. State, plans, conversations and spend are folds of that log, so runs can be replayed, audited, resumed after a crash, and moved between processes. :octicons-arrow-right-24: Events and the log

  • Your data, not ours

    Algorithms see an Item envelope; you keep your own types (Pydantic, dataclasses, dicts, DataFrame rows, documents). A small codec teaches AAA to render, store and fingerprint them. :octicons-arrow-right-24: Data model

  • Bounded by construction

    Budgets (steps, tokens, cost), deadlines, cancellation, approval gates and tool timeouts are enforced by the engine, outside the model's control. Failures are facts on the log, not exceptions. :octicons-arrow-right-24: Runs and the engine

  • Any LLM gateway

    One OpenAI-compatible client with presets for LiteLLM, Portkey, Cloudflare, Vercel, Bifrost, Kong and MLflow, an in-process LiteLLM adapter, and a plug-in point for anything custom. :octicons-arrow-right-24: LLM gateways

  • Durable and distributed

    SQLite for one machine; Postgres or Redis plus a partitioned bus for many. Kill a worker mid-tool-call and another finishes the job. :octicons-arrow-right-24: Running a cluster

  • Safe side effects

    Exclusive execution leases, numbered attempts as fencing tokens, at-most-once / at-least-once delivery, and idempotency keys for tools that send email or move money. :octicons-arrow-right-24: Tool execution guard

What is in 0.3

Want an HTTP API?

The separate aaa-server package puts an engine behind a port: authentication, tenant isolation, rate limits and quotas, approvals over HTTP, resumable event streams, MCP and A2A endpoints. pip install aaa-server · overview and docs · PyPI

The algorithms

Algorithm Use it when
ToolLoop The model should call your functions until it can answer. The default choice.
ReAct The model/gateway has no native tool calling (text Thought/Action protocol).
PlanAndExecute A task decomposes into steps with dependencies that can run in parallel.
Router Pick exactly one specialist: rules first, an LLM only for what rules do not decide.
Supervisor An LLM coordinates several workers, possibly in parallel.
GenerateTestRepair You can verify output deterministically (schema, tests, rules).
GeneratorCritic You can only verify with another model.
WorkflowGraph The control flow is known; no LLM should decide it.
FSM Long-lived, event-driven processes with explicit states (approvals, onboarding).
SelfConsistency Answers are exactly comparable; majority vote beats one sample.
RAGAgent Answers must be grounded in your documents, with citations.
Reflexion Retry from scratch, informed by written lessons from the failed attempts.
Debate Several answers that read each other's, then a judge or a vote.
Swarm Specialist agents hand a conversation to each other, each with only its own tools.
TreeOfThoughts Search over reasoning steps, scored and pruned, within a hard call budget.

Choosing an algorithm walks through the decision, and Writing your own shows the 40-line recipe for a new one.

Status

Alpha software: read the limits

AAA is version 0.x. The test suite is substantial (unit, store/bus contract tests across four backends, real multi-process tests that SIGKILL workers) but you should know what has and has not been proven:

  • Verified live against a real model server (a local Ollama running gemma4), including tool calls, streaming, structured output, plan-and-execute and repair loops.
  • Not yet verified live against any hosted gateway (Portkey, Cloudflare, Vercel, Bifrost, Kong, MLflow, LiteLLM proxy). Their URLs and headers follow vendor documentation and are covered by mocked-transport tests. A smoke-test script is provided.
  • Lightly load tested. Correctness under failure is tested; throughput is measured for one laptop (workers sharing its cores), not for a real multi-machine deployment.

The full list is on Status and limitations.

Where to go next

  1. Install it and run the quickstart.
  2. Read the mental model (ten minutes; everything else follows from it).
  3. Pick an algorithm, or go straight to persistence and clusters if you are deploying.
  4. Need an API in front of it? See the aaa-server overview.
  5. Keep the event catalog and configuration reference open while you build.

AAA is MIT licensed. Source: github.com/innerkorehq/AutonomousAgentArchitecture.