📦 Universal Agent File (UAF) — The Standard for Portable AI Agents
Package once. Run anywhere. Share stateful AI agents as binaries.
Overview • Features • Installation • Quick Start • CLI • Specification • AgentComet
🚀 Overview
Universal Agent File (UAF) is a standardized binary format for packaging and distributing AI agents.
It solves a core problem in the agent ecosystem:
❌ Agents are fragmented, framework-locked, and not portable ✅ UAF makes agents portable, reproducible, and shareable
A .uaf file is a compressed, verifiable artifact that bundles agent logic, dependencies, metadata, tools, and optional state.
This enables: Write once → run anywhere → resume anytime
✨ Features
- 📦 Portable Binary Format - Package complete agents into a single
.uaffile. - 🧠 Stateful Agents - Persist and transfer agent memory across environments.
- 🛡️ Strict Validation - Enforced schema (
agent.yaml) ensures reliability. - 🔍 Inspect Without Running - View metadata, tools, and config without execution.
- 🔌 Framework Agnostic - Works across LangChain, LangGraph, CrewAI, Google ADK.
- ⚡ Runtime Loader - Dynamically load and execute agents from
.uaf.
🛠️ Installation
Install from PyPI (Python 3.9+):
pip install uaf_cli
Or from source:
git clone https://github.com/vaibhavhaswani/uaf-cli.git
cd uaf-cli
pip install .
⚡ Quick Start
1️⃣ Project Structure
Create an agent folder with the following structure:
my-agent/
├── agent.py # Framework logic (LangChain, CrewAI, etc.)
├── agent.yaml # Manifest metadata
├── requirements.txt # Dependencies
├── agent.state # (Optional) Initial state
└── uaf_setup.yaml # Compiler build instructions
2️⃣ Configure Build (uaf_setup.yaml)
output: my-agent.uaf
files:
agent.py: ./agent.py
agent.yaml: ./agent.yaml
requirements.txt: ./requirements.txt
agent.state: ./agent.state
3️⃣ Compile
uaf compile -f uaf_setup.yaml
✅ Output: my-agent.uaf
💻 CLI
Compile, package, and execute agents with simple commands:
uaf init # Scaffold absolute path project
uaf compile # Compile into .uaf artifact
uaf validate # Validate schema compliance
uaf inspect # View deep metadata
uaf run # Run CLI agent turn loop
uaf update # Inject incremental builds
Full technical guide → docs/usage_guide.md
🔗 Loading Agents
The UAFLoader dynamically routes directly into execution setups powered by target frame pipelines.
from uaf_compiler.loader import UAFLoader
# 1. Initialize Loader
uaf_loader = UAFLoader("my-agent.uaf")
# 2. Dynamic Router Injection
# Load LangChain/LangGraph
agent_app = uaf_loader.load(llm=my_llm)
# Load CrewAI
agent_crew = uaf_loader.load(llm_model="ollama/gemma3", base_url="http://...")
# Load Google ADK
agent_runner = uaf_loader.load(llm_model="ollama/gemma3", base_url="http://...")
Full Loading & Integration workflows → docs/integration.md
📜 Protocol Specification
Complete binary spec design detailing underlying tarball structure, manifest validation rules, and lifecycle bindings.
See frameworks & schema docs → docs/frameworks.md
🏗️ Development & Testing
Standard installation and developer workflows:
pip install -e .
Run End-to-End Tests
To verify loaders and correct tool-use turn loops across all SDK adaptors (LangChain, CrewAI, ADK, Comet) over a local Ollama endpoint:
python testing/test_dummy_agents.py
AgentComet natively loads and executes UAF agents using its SDK-level hooks without wrapping logic adapters.
from agentcomet import load_agent
# 1. Load UAF directly
agent = load_agent("my-agent.uaf")
# 2. Run agent natively
response = agent.run("Calculate current stock performance")
print("Response:", response)
# 3. Export / Save state
agent.export("my_assistant.uaf")
Metadata
Release files for uaf-cli 0.8.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 | Provenance | Actions |
|---|---|---|---|---|
| uaf_cli-0.8.0.tar.gz | 19.5 kB | Without provenance | Details for uaf_cli-0.8.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| uaf_cli-0.8.0-py3-none-any.whl | Python 3 | none | any | Details for uaf_cli-0.8.0-py3-none-any.whl |
Total release size: 40.0 kB
Release files / uaf_cli-0.8.0.tar.gz
| Download URL | uaf_cli-0.8.0.tar.gz |
|---|---|
| Size | 19.5 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
0b0e0028779f618bf57c67735bf95128ac18ce4d386c4c0f7362e48a1682126d
|
|
BLAKE2b-256 checksum How to use checksums |
4c9d1326f431b045f848b873b7f5cf58e83c01d2c61d3e3f9b6cb8f9d536ca58
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.4
|
Release files / uaf_cli-0.8.0-py3-none-any.whl
| Download URL | uaf_cli-0.8.0-py3-none-any.whl |
|---|---|
| Size | 20.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
33ab7af5c5b3e2b2f642f67e8f85e8127bee9e29e76301836d8f0de03c6d0c34
|
|
BLAKE2b-256 checksum How to use checksums |
91c96924a87d3d18f4b78130bfba8d79e2ccb58c83c984198a6695f0f321ebe8
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/6.2.0 CPython/3.12.4
|
Security for uaf-cli 0.8.0
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.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.