orchestrate

lionagi

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

Docs | Discord | PyPI | Changelog

What's New in 0.23

• Agent infrastructure — AgentConfig presets (.coding(), .research()) with built-in permission policies, hooks, and tool registration via create_agent().
• Sandbox tool — SandboxSession uses git worktrees for isolated editing: create() → edit → diff() → commit() → merge() or discard().
• New providers — DeepSeek (DEEPSEEK_API_KEY) and Pi (via Pi Code CLI) are now supported as CLI agent backends.
• Settings merge — global ~/.lionagi/settings.yaml and per-project .lionagi/settings.yaml are merged automatically at startup.

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 configurations (coding, research) with permission policies, hooks, and tool registration.
Sandbox	Git worktree isolation for safe experimentation — SandboxSession.create() → edit → diff → merge or 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"

Full reference → docs/cli-reference.md · Installable 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"},
)