lionagi

Orchestrate multi-agent AI workflows from the command line or Python.

Docs | Docs / Architecture (DeepWiki) | Discord | PyPI | Changelog

Lion Studio

Lion Studio is the built-in web UI for managing and operating your agent workflows. Projects, schedules, playbooks, shows, and runs — all in one place.

pip install lionagi

# Option 1: Docker (recommended — one command, no Node.js needed)
li studio                       # auto-pulls ghcr.io/ohdearquant/lion-studio
                                # UI → http://localhost:3000  API → http://localhost:8765

# Option 2: From source (for development)
git clone https://github.com/ohdearquant/lionagi.git && cd lionagi
pip install ".[studio]"
li studio --dev                 # starts backend + frontend with hot reload

What's New in 0.26

• Lion Studio — web UI for orchestrating agent workflows: projects, scheduled runs, execution DAGs, branch inspection, and multi-agent monitoring.
• Project management (ADR-0026) — per-repo .lionagi/config.toml for project identity. Sessions auto-group by project. --project NAME flag on all CLI commands.
• Scheduled runs (ADR-0027) — cron, interval, and GitHub-poll triggers with DAG-based conditional chains (on_fail/on_success). Studio becomes an active operator, not just a monitor.
• Agent infrastructure — AgentConfig preset (.coding()) with built-in permission policies, hooks, and tool registration via create_agent().
• Sandbox tool — SandboxSession dataclass with module-level async functions for git worktree isolation: create_sandbox() → edit → sandbox_diff() → sandbox_commit() → sandbox_merge() or sandbox_discard().

Install

pip install lionagi

CLI provider auth — CLI aliases spawn subprocess tools, not REST API calls:

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

First Flow

import asyncio
from lionagi import Branch

async def main():
    b = Branch()          # default: gpt-4.1-mini (requires OPENAI_API_KEY)
    reply = await b.communicate("Name 3 features of async Python, one sentence each.")
    print(reply)

asyncio.run(main())

# output:
1. Coroutines let you write non-blocking I/O without threads.
2. asyncio.gather runs multiple coroutines concurrently under one event loop.
3. async generators stream results lazily, pausing between each yield.

For multi-agent orchestration without Python, see CLI Quick Start.

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>.
AgentConfig	Preset agent configuration (.coding()) with permission policies, hooks, and tool registration.
Sandbox	Git worktree isolation for safe experimentation — create_sandbox() → edit → sandbox_diff() → sandbox_merge() or sandbox_discard().

CLI — li

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

# 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 .

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

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

# Skill: print a CC-compatible reference body to stdout (for agent context injection)
li skill commit

# Resume any run
li agent -r <branch-id> "follow up on your findings"

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

Full reference → docs/cli-reference.md · Installable templates → examples/

CLI Commands

li agent — Run a single agent session against any CLI-compatible model. li agent [MODEL] PROMPT [-a NAME] [-r BRANCH_ID] [-c] [--yolo] [--bypass] [--fast] [-v] [--theme {light,dark}] [--effort LEVEL] [--cwd DIR] [--timeout SECS] [--invocation ID] [--project NAME] Load a saved profile with -a/--agent; resume a previous branch by ID with -r/--resume; reattach to the last branch with -c/--continue-last.

li o flow — Run a multi-agent DAG flow where an orchestrator model plans and dispatches specialist agents. li o flow [MODEL] [PROMPT] [-f FILE] [-p PLAYBOOK] [-a AGENT] [--with-synthesis [MODEL]] [--max-concurrent N] [--output {text,json}] [--save DIR] [--team-mode [NAME]] [--team-attach NAME] [--dry-run] [--show-graph] [--background] [--bare] [--workers M1,M2,...] [--max-ops N] [--reactive MODE] plus shared flags (--yolo, --bypass, --fast, -v, --theme, --effort, --cwd, --timeout, --invocation, --project). Provide the flow spec via -f FILE (YAML/JSON), a named playbook via -p PLAYBOOK, or a free-form prompt. --dry-run prints the planned DAG without executing; --background runs detached and requires --save.

li o fanout — Run the same prompt against multiple worker models in parallel with optional synthesis. li o fanout [MODEL] PROMPT [-a AGENT] [-n N] [--workers M1,M2,...] [--max-concurrent N] [--with-synthesis [MODEL]] [--synthesis-prompt TEXT] [--output {text,json}] [--save DIR] [--team-mode [NAME]] plus shared flags. Set the worker count with -n; specify explicit model specs with --workers; add a final synthesis pass with --with-synthesis.

li play — Shortcut for li o flow -p NAME; runs a named playbook from ~/.lionagi/playbooks/. li play NAME [flow-flags...] | li play list | li play check NAME li play list enumerates installed playbooks; li play check NAME validates artifact contracts before a run; li play NAME --help shows playbook-declared parameters. All li o flow flags except -f/--file are forwarded after NAME.

li monitor / li mon — Inspect live and recent sessions, invocations, shows, and plays. li monitor [ID] [-w] [--refresh SECS] [--since WINDOW] [-t {session,invocation,show,play}] [-p PROJECT] Pass an ID or unique prefix for a detail view; -w/--watch enables live refresh at --refresh interval; --since accepts windows like 30m, 1h, 2d.

li kill — Stop a running session or invocation. li kill [ID] [--reason TEXT] [--recursive] [--all-stale] [--threshold SECS] [--dry-run] [--grace SECS] Target by entity ID or unique prefix; --recursive also kills child entities; --all-stale sweeps processes with dead PIDs; --dry-run previews without changing state.

li studio — Launch the Lion Studio web UI (backend API + React frontend). li studio [start] [--port PORT] [--host HOST] [--frontend-port PORT] [--no-frontend] [--dev] [--no-docker] Defaults to Docker (ghcr.io/ohdearquant/lion-studio; auto-pulled); --no-docker uses a local install; --no-frontend starts the API server only; --dev enables hot-reload frontend for development.

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/

Docs

Getting Started	Install, first flow, API key setup
Concepts	Branch, Session, flow, team, operate, persist
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
Migration 0.22.5 → 0.22.6	Breaking changes: branch.instruct removed, run paths changed
Contributing	Dev setup, PR workflow

Optional Extras

uv add "lionagi[reader]"    # Document reading (PDF, HTML, DOCX)
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]"     # Flow visualization
uv add "lionagi[postgres]"  # PostgreSQL persistence
uv add "lionagi[all]"       # Everything

Claude Code Marketplace

The lionagi marketplace provides installable Claude Code plugins for the lionagi agent runtime. Each plugin adds a focused set of skills and agents for a specific workflow: structured show runs, memory management, playbook authoring, developer tooling, and multi-agent orchestration.

Install:

claude /plugin marketplace add ohdearquant/lionagi

Prerequisites: lionagi (pip install lionagi or uv pip install lionagi) and Claude Code installed.

See marketplace/README.md for the full plugin list and per-plugin install instructions.

Community

• Discord — questions, ideas, help
• Issues — bugs and feature requests
• Contributing — PR workflow

Citation

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