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 avalan@avalan.ai.
Contributing
We welcome pull requests, issue reports, docs improvements, and new examples.
- Read the Code of Conduct before you start.
- Install the development environment with
poetry install --all-extras --with test. - Run
make lint. - Run
poetry run pytest --verbose -s.
Open a GitHub issue if you discover bugs or want to propose larger changes.
1 maintainer
Metadata
1 maintainer
Release files for avalan 1.5.11
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| avalan-1.5.11.tar.gz | 2.4 MB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| avalan-1.5.11-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 5.2 MB
Release files / avalan-1.5.11.tar.gz
| Download URL | avalan-1.5.11.tar.gz |
|---|---|
| Size | 2.4 MB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
b317153929cee142632db7d48f2ec8fa1502cfe62d9e9421186b27eb45fc4c7a
|
|
BLAKE2b-256 checksum How to use checksums |
f282abeae5e1ec421f6945938e9fe8cd68dbf58c852f6ffd04933784944851d1
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency logRelease files / avalan-1.5.11-py3-none-any.whl
| Download URL | avalan-1.5.11-py3-none-any.whl |
|---|---|
| Size | 2.8 MB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
1a9d659fedab2db0b247ceba9d14be0bed2da1c6aff1be41064059d5491eb693
|
|
BLAKE2b-256 checksum How to use checksums |
fb23d337ab0b24cfe717230ead528afe30ad40a26478c91050338101e51549a8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
PyPI Publish Attestation
PyPI verified that this artifact, at this checksum, originated from the publisher listed below.
Signed by GitHub Actions, verified by PyPI on Sep 26, 2026.
Transparency log
