Skip to main content

PyPI - Version PyPI - Downloads Python Version codecov

lionagi

lionagi is a governed multi-agent orchestration framework. Build agent workflows in Python with typed, inspectable state, or run them straight from the terminal with the li CLI: single agents, parallel fan-outs, and DAG flows where an orchestrator plans specialist workers. Built continuously since 2023.

Direction. lionagi's underlying architecture is migrating towards lion1, the runtime kept in the lion1/ directory of this repository until the migration completes, while lionagi stays the package you install and import. The migration is backward compatible: public imports, supported call shapes and return types stay as they are, and new capabilities arrive as additions. Removing a public name or behavior, or changing what a default install can do, needs its own versioned compatibility decision. lionagi v1.0 is planned for around the end of October 2026. The roadmap sets out the seven steps and the compatibility terms, and ADR-0125 records the decision.

Docs | How lionagi Compares | Discord | PyPI | Changelog

Demo

Lion Studio walkthrough (13 min): inspecting runs, checking agent claims against actual output, and launching work with approval gates. Built on lionagi, runs locally.

Quick start

pip install lionagi

# one agent
li agent claude/sonnet "Explain the observer pattern in 3 sentences"

# three workers in parallel, then a synthesis pass
li o fanout claude/sonnet "Identify code smells in this codebase" -n 3 --with-synthesis

# an orchestrator plans a DAG of specialists; workers run as dependencies resolve
li o flow claude/sonnet "Audit the auth module for security issues" --cwd .

CLI model aliases (claude, codex, ...) spawn the provider's own CLI as a subprocess, so an existing claude login subscription works with no API key. API providers take the usual environment keys (OPENAI_API_KEY, ...). Details in Providers.

The same engine from Python, with structured output as a first-class result:

import asyncio
from pydantic import BaseModel
from lionagi import Branch

class Assessment(BaseModel):
    risk: str
    reasons: list[str]

async def main():
    b = Branch(chat_model="codex/gpt-5.5", system="You are a careful reviewer.")
    result = await b.operate(
        instruction="Assess the risk of enabling auto-merge on this repository.",
        response_format=Assessment,
    )
    print(result.risk, result.reasons)

asyncio.run(main())

Why lionagi

  • You own the loop. Branches, sessions, and flows are ordinary Python objects and CLI commands. There is no framework runtime to surrender control to, and no hidden prompt assembly between you and the model.
  • Typed, inspectable state. Every conversation is a collection of typed messages with an explicit ordering. State serializes, persists, and resumes; it is never an opaque blob inside a chain.
  • CLI agents are first-class endpoints. Claude Code, Codex, and other coding CLIs sit in the same orchestration graph as API models, so subscription-based agents and API calls compose in one flow.
  • Durable runs. Every run persists under ~/.lionagi/runs/. Resume any branch with li agent -r, reattach with -c, watch live work with li monitor, and schedule recurring runs with li schedule.
  • Governance built in. Permission policies per tool call, guard hooks that block destructive commands and off-limits paths, and git-worktree sandboxing for speculative edits that never touch your branch until you merge them.

For the architecture-level comparison with LangChain / LangGraph (and a field matrix covering LlamaIndex and AG2), see How lionagi Compares.

Concepts

Term What it is
Branch Single conversation thread — message history, tools, model config. Primary API surface.
Session Coordinates multiple Branches; runs DAG workflows across them.
flow li o flow — orchestrator plans a DAG, workers execute with dependency edges resolved.
team Persistent inbox messaging between agents via li team send/receive.
operate branch.operate(instruction=…) — tool use + structured output + optional streaming.
persist Every run saved to ~/.lionagi/runs/{run_id}/. Resume with li agent -r <branch-id>.

The li CLI

# Single agent, resumable
li agent claude/sonnet "Explain the observer pattern in 3 sentences"
li agent -r <branch-id> "follow up on your findings"

# Fan-out: N workers in parallel, optional synthesis
li o fanout claude/sonnet "Identify code smells in this codebase" -n 3 --with-synthesis

# DAG flow: orchestrator plans agents with dependency edges
li o flow claude/sonnet "Audit the auth module for security issues" --cwd .

# Playbook: parametric flow spec at ~/.lionagi/playbooks/audit.playbook.yaml
li play audit --mode security "the auth service"

# Team messaging: inbox coordination between agents
li team create "review" && li team send "Start analysis" -t <id> --to analyst

# Observe and operate
li monitor --since 1h              # live and recent sessions, flows, plays
li schedule create ...             # cron / interval / repo-event triggers
li kill <id>                       # stop a running session or invocation

# Time-bounded run: injects a [DEADLINE] preamble so the agent paces itself
li agent claude/sonnet --timeout 300 "Audit the auth module and produce a summary"

Every command and flag: CLI Reference. Installable playbook and skill templates: examples/.

Python API

Chat

from lionagi import Branch

b = Branch(chat_model="openai/gpt-5.4", system="You are a concise assistant.")
reply = await b.communicate("What causes rainbows?")

Structured output

from pydantic import BaseModel

class Summary(BaseModel):
    points: list[str]
    confidence: float

result = await b.operate(instruction="Summarize this text.", response_format=Summary)

Tools + ReAct

from lionagi.tools.types import ReaderTool

branch = Branch(tools=[ReaderTool])
result = await branch.ReAct(
    instruct={"instruction": "Summarize /path/to/paper.pdf"},
)

Full reference → docs/api/

Lion Studio

Lion Studio is the built-in web UI for operating your agent workflows: projects, schedules, playbooks, execution DAGs, and run inspection in one place.

Lion Studio — Mission Control: live agents, completion pulse, and run history

No download or build required. Lion Studio is a client-side web app: li studio starts your local daemon and opens lion-studio.khive.ai paired with it, and the page talks to the daemon at http://127.0.0.1:8765. Your data never leaves your machine; the hosted page is just the UI. Available in 16 languages: English, 中文, Español, Français, हिन्दी, বাংলা, Deutsch, Bahasa Indonesia, Português (Brasil), 한국어, Türkçe, اردو, Tiếng Việt, العربية, Русский, and 日本語 — with full right-to-left support.

li studio             # default: starts the local daemon and opens
                      # https://lion-studio.khive.ai — nothing is built locally
li studio --docker    # self-contained: auto-pulls ghcr.io/ohdearquant/lion-studio
                      # UI + API → http://127.0.0.1:8765 (published on --host)
li studio --no-frontend  # backend API only, no UI
li studio --dev       # from a source checkout: backend + in-repo frontend, hot reload

--web, --docker, --no-frontend, and --dev are mutually exclusive; --web is the default when no flag is given. Pass --no-open to skip auto-opening the hosted UI in your browser; li studio then prints a one-time link to open instead.

Providers

CLI aliases spawn subprocess tools, not REST API calls:

  • claude: install Claude Code CLI → claude login (subscription) or export ANTHROPIC_API_KEY=sk-ant-...
  • codex: requires ChatGPT Plus/Pro → npm install -g @openai/codex → codex login
  • deepseek: export DEEPSEEK_API_KEY=sk-...
  • pi: install Pi Code CLI
  • Python API (iModel, Branch): export OPENAI_API_KEY=sk-... for the default model

API-endpoint providers (OpenAI, Anthropic, Gemini, Ollama, NVIDIA NIM, Perplexity, Groq, OpenRouter): Providers reference.

Docs

Getting Started Install, first flow, API key setup
RuVector memory Optional native retrieval, branch memory and tools
Concepts Branch, Session, flow, team, operate, persist
How lionagi Compares Architecture-level comparison with LangChain / LangGraph
CLI Reference li agent, li o fanout, li o flow, li team — all flags
Cookbook 5 runnable scenarios: codebase audit, research synthesis, multi-model pipeline, team coordination, resumable background run
API Reference branch.operate, branch.ReAct, iModel, Session
Architecture (DeepWiki) Auto-generated architecture walkthrough
Roadmap Migration towards lion1, compatibility terms, v1.0 target
Contributing Dev setup, PR workflow

Optional Extras

uv add "lionagi[mcp]"       # MCP server support
uv add "lionagi[ollama]"    # Local models via Ollama
uv add "lionagi[rich]"      # Rich terminal output
uv add "lionagi[graph]"     # networkx export (drawing also needs matplotlib)
uv add "lionagi[postgres]"  # PostgreSQL persistence
uv add "lionagi[ruvector]"  # Native vector memory and retrieval (RuVector)
uv add "lionagi[all]"       # Everything

Agents that need memory across sessions can use khive, a hosted memory and knowledge graph served over MCP: https://khive.ai/?utm_source=github&utm_campaign=lionagi-readme

Claude Code Marketplace

Installable Claude Code plugins for the lionagi agent runtime — structured show runs, memory management, playbook authoring, developer tooling, and multi-agent orchestration:

claude /plugin marketplace add ohdearquant/lionagi

Full plugin list: marketplace/README.md.

Community

Citation

@software{Li_LionAGI_2023,
  author = {Haiyang Li},
  year   = {2023},
  title  = {LionAGI: Towards Automated General Intelligence},
  url    = {https://github.com/ohdearquant/lionagi},
}

Metadata

Release files for lionagi 0.37.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for lionagi 0.37.0
File Size Uploaded Provenance Actions
lionagi-0.37.0.tar.gz 8.1 MB Without provenance Details for lionagi-0.37.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for lionagi 0.37.0
File Interpreter ABI Platform Actions
lionagi-0.37.0-py3-none-any.whl Python 3 none any Details for lionagi-0.37.0-py3-none-any.whl

Total release size: 10.8 MB

Release files / lionagi-0.37.0.tar.gz

Download URL lionagi-0.37.0.tar.gz
Size 8.1 MB
Tags Source
SHA-256 checksum
How to use checksums
72acda8950c1d9c084d44c7fb1dbe00d329a3d87cb0e76572828bb84dc091ec6
BLAKE2b-256 checksum
How to use checksums
0770106f8c88aa138ce7eafde0f473639df27339af71fa3dbb3bd1453ac1ee8a
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Release files / lionagi-0.37.0-py3-none-any.whl

Download URL lionagi-0.37.0-py3-none-any.whl
Size 2.7 MB
Tags Python 3
SHA-256 checksum
How to use checksums
0b25fc9f07f84cb5088fd80e77e102dc8593819f98218443902d0756a8cd4cf2
BLAKE2b-256 checksum
How to use checksums
2c54a74ad5f58817fd09a9969919efc7780454cbc1f2a33842515b33db604009
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via twine/7.0.0 CPython/3.10.22

Security for lionagi 0.37.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.

Release history Release notifications | RSS feed

This release

0.37.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page