avalan

The multi-backend, multi-modal micro-framework for AI agent development, orchestration, and deployment

Avalan is a Python SDK and CLI for building your own intelligence harness across local and hosted models. Prompts, model routing, tools, memory, workflows, tasks, and serving protocols stay explicit, so the model is a component you control rather than the whole system.

🧠 Build Your Intelligence Harness

Avalan is for teams that want the model to be one part of the system, not the system itself. It gives you the runtime harness around inference, tools, memory, orchestration, tasks, protocols, and human control.

With Avalan, you can:

• 💻 Run local and hosted models behind one interface, with inference-time control over prompts, sampling, streaming, backends, and vendor routing.
• 🛠️ Execute tools as first-class runtime steps, including browser automation, code, databases, shell media tools, MCP servers, and A2A agents.
• 🧱 Choose runtime isolation for execution surfaces with local, sandbox, and container modes, trusted profiles, and fail-closed policy.
• 🔁 Compose flows where each node, edge, input, output, and review boundary is visible.
• ✅ Package repeatable work as tasks with typed inputs, file handling, queues, durable execution, privacy settings, and schema-validated outputs.
• 🌐 Serve your agents through OpenAI-compatible APIs, MCP, and A2A without changing the agent runtime.
• 🔒 Add human-in-the-loop and least-privilege controls around tool execution, data access, files, and networked agent calls.

📦 Install

Avalan supports Python 3.11 through 3.14.

🍺 Homebrew (macOS)

brew install avalan-ai/avalan/avalan

🐧 Ubuntu (PPA)

sudo add-apt-repository -y ppa:avalan-ai/avalan
sudo apt update
sudo apt install -y avalan

🐍 Pip

python3 -m pip install -U "avalan[agent,server,tool,vendors]"

🛠️ From Source with Poetry

poetry install --extras "agent server tool vendors" --with test

See docs/INSTALL.md for pip extras, backend-specific dependencies, DS4 setup, and source build prerequisites.

⚡ Quickstart

💬 Call a hosted model from the CLI

Export a vendor key, then run:

export OPENAI_API_KEY=...
echo "Who are you, and who is Leo Messi?" \
    | avalan model run "ai://env:OPENAI_API_KEY@openai/gpt-4o" \
        --system "You are Aurora, a helpful assistant" \
        --max-new-tokens 100

🐍 Use the Python SDK

from asyncio import run
from os import environ
from avalan.entities import GenerationSettings, TransformerEngineSettings
from avalan.model.nlp.text.vendor.openai import OpenAIModel
from avalan.model.stream import StreamItemKind

async def main() -> None:
    api_key = environ["OPENAI_API_KEY"]
    settings = TransformerEngineSettings(access_token=api_key)

    with OpenAIModel("gpt-5-mini", settings) as model:
        async for item in await model(
            "Give me five facts about Leo Messi.",
            settings=GenerationSettings(use_async_generator=True),
        ):
            if (
                item.kind is StreamItemKind.ANSWER_DELTA
                and item.text_delta is not None
            ):
                print(item.text_delta, end="", flush=True)

run(main())

✅ Run a flow-backed task

This example requires task, PDF image conversion, agent, and vendor dependencies:

python3 -m pip install -U "avalan[agent,task,task-pdf-images,vendors]"

avalan task run docs/examples/tasks/poc_extraction/image_flow_task.toml \
    --ephemeral \
    --pdf docs/examples/tasks/poc_extraction/sample.pdf \
    --json \
    --output image.json

For task contracts, flow graphs, file conversion, queues, and schema output, see docs/TASKS.md, docs/FLOWS.md, and docs/examples/tasks/poc_extraction/README.md.

Documentation & Resources

• docs/README.md - Complete documentation index.
• docs/INSTALL.md - Platform setup, extras, backends, and source builds.
• docs/MODELS.md - Model URIs, local and hosted backends, generation settings, and streaming.
• docs/AGENT_GUIDE.md - Agent TOML, prompts, tools, memory, structured output, multimodal inputs, and serving.
• docs/TOOLS.md - Built-in tools, MCP, A2A, shell tools, confirmation, safety controls, and reasoning strategies.
• docs/MEMORIES.md - Recent and permanent memory, namespaces, indexing, retrieval, and storage backends.
• docs/FLOWS.md - Explicit graph workflows, strict definitions, Mermaid views, branching, and review boundaries.
• docs/TASKS.md - Durable task contracts, file delivery, queues, storage, privacy, and schema validation.
• docs/MODALITIES.md - Text, vision, and audio CLI and Python examples.
• docs/CLI.md - Command and flag reference.
• docs/examples - Runnable examples.

Community & Support

• Join the Avalan Discord to ask questions, share workflows, and follow release announcements.
• Browse generated documentation or ask follow-up questions in Google Code Wiki.
• For commercial support, email [email protected].

Contributing

We welcome pull requests, issue reports, docs improvements, and new examples.

1. Read the Code of Conduct before you start.
2. Install the development environment with poetry install --all-extras --with test.
3. Run make lint.
4. Run poetry run pytest --verbose -s.

Open a GitHub issue if you discover bugs or want to propose larger changes.