Skip to content

Provider Reference

API providers

Pass provider= to iModel(), or let lionagi infer from the model name.

Provider provider= string Aliases Key env var Endpoints
OpenAI "openai" — OPENAI_API_KEY chat/completions, responses, embeddings, audio/speech, audio/transcriptions, images/generations, images/edits
Anthropic "anthropic" — ANTHROPIC_API_KEY messages
Google Gemini "gemini" "gemini-api" GEMINI_API_KEY chat/completions
Ollama (local) "ollama" — — (no key needed) chat/completions, embeddings, generate
NVIDIA NIM "nvidia_nim" "nvidia", "nim" NVIDIA_NIM_API_KEY chat/completions, embeddings
Perplexity "perplexity" — PERPLEXITY_API_KEY chat/completions
Groq "groq" — GROQ_API_KEY chat/completions, audio/transcriptions
OpenRouter "openrouter" "open-router" OPENROUTER_API_KEY chat/completions
DeepSeek "deepseek" — DEEPSEEK_API_KEY chat/completions 
# Explicit provider
model = li.iModel(provider="anthropic", model="claude-opus-4-7-20251001")

# Default provider inferred (openai)
model = li.iModel(model="gpt-4o")

# Slash notation — provider inferred from prefix
model = li.iModel(model="anthropic/claude-opus-4-7")

# Custom base URL (proxy, local inference)
model = li.iModel(
    provider="openai",
    base_url="http://localhost:8080/v1",
    model="my-model",
)

DeepSeek's reasoning_effort field maps lionagi effort levels: low/medium → "high", xhigh → "max". DeepSeek native values (low, medium, high, max) pass through unchanged.

CLI / agentic providers

CLI endpoints spawn subprocess tools instead of calling REST APIs. Pass provider= to select one; is_cli is set True automatically. Use with Branch.run() or Branch.operate().

Provider provider= string Aliases CLI tool Auth
Claude Code "claude_code" "claude-code", "claude" claude claude login or ANTHROPIC_API_KEY
Codex "codex" "openai-codex" codex codex login (ChatGPT Plus/Pro)
Gemini CLI "gemini_code" "gemini-code", "gemini_cli", "gemini-cli" gemini gemini auth
Pi "pi" "pi-code", "pi_code" pi local pi binary 
# Claude Code CLI endpoint
claude_model = li.iModel(provider="claude_code", model="sonnet")

# Codex CLI endpoint
codex_model = li.iModel(provider="codex", model="o3")

async for msg in branch.run("Refactor this function:", chat_model=claude_model):
    print(msg.content, end="", flush=True)

Branch.operate() detects is_cli=True and routes to run_and_collect instead of communicate. See operations.md for routing details.

Search and scraping providers

These providers integrate as callable tools via branch.connect() — not as chat models.

Provider Purpose provider= string Key env var Endpoints
Exa Neural search "exa" EXA_API_KEY search, contents (alias: get_contents), findSimilar (aliases: similar, find_similar)
Firecrawl Web scraping "firecrawl" FIRECRAWL_API_KEY v1/scrape (alias: scrape), v1/map (alias: map), v1/crawl (alias: crawl)
Tavily Research search "tavily" TAVILY_API_KEY search, extract 
branch.connect(provider="exa", endpoint="search", name="search")
results = await branch.operate(
    instruction="Find recent papers on diffusion models",
    actions=True,
    tools=["search"],
)

AG2 (multi-agent)

AG2 GroupChat wraps AG2 v0.12's GroupChat as a streaming lionagi endpoint. Requires the optional ag2 extra:

pip install lionagi[ag2]
Provider provider= string Aliases Endpoint Type
AG2 "ag2" "autogen" group_chat (aliases: groupchat, chat) agentic

AG2GroupChatEndpoint is stream-only — it yields StreamChunk events for each agent turn. _call() raises NotImplementedError; use branch.run() or iterate endpoint.stream() directly.

# requires: pip install lionagi[ag2]
from lionagi.providers.ag2.groupchat.endpoint import AG2GroupChatEndpoint

endpoint = AG2GroupChatEndpoint(
    agent_configs=[
        {"name": "coder", "system_message": "Write Python code."},
        {"name": "reviewer", "system_message": "Review and critique code."},
    ],
    llm_config={"model": "gpt-4o-mini"},
)

async for chunk in endpoint.stream({"prompt": "Build a Fibonacci function"}):
    print(chunk.content, end="", flush=True)

Provider folder structure

Each provider is a directory under lionagi/providers/{company}/. The subdirectories are capabilities — the directory listing is the capability map.

lionagi/providers/
├── openai/
│   ├── _config.py          # OpenAIConfigs + CodexConfigs enums
│   ├── chat/               # chat/completions endpoint
│   │   ├── endpoint.py
│   │   └── models.py
│   ├── codex/              # Codex CLI endpoint
│   ├── audio/              # speech + transcription
│   ├── embed/
│   ├── images/
│   └── response/           # Responses API
├── anthropic/
│   ├── _config.py          # AnthropicConfigs + ClaudeCodeConfigs enums
│   ├── messages/
│   └── claude_code/        # CLI endpoint
├── google/
│   ├── _config.py          # GeminiChatConfigs + GeminiCodeConfigs enums
│   ├── chat/
│   └── gemini_code/        # CLI endpoint
├── deepseek/
│   ├── _config.py
│   └── chat/
├── ollama/
│   ├── _config.py
│   ├── chat/
│   ├── embed/
│   └── generate/
├── nvidia_nim/
│   ├── _config.py
│   ├── chat/
│   └── embed/
├── perplexity/
│   ├── _config.py
│   └── chat/
├── groq/
│   ├── _config.py
│   ├── chat/
│   └── audio_transcription/
├── openrouter/
│   ├── _config.py
│   └── chat/
├── exa/
│   ├── _config.py
│   ├── search/
│   ├── contents/
│   └── find_similar/
├── firecrawl/
│   ├── _config.py
│   ├── scrape/
│   ├── map/
│   └── crawl/
├── tavily/
│   ├── _config.py
│   └── search/
├── pi/
│   ├── _config.py
│   └── cli/
└── ag2/
    ├── _config.py          # AG2Configs enum
    └── groupchat/

Each leaf directory contains endpoint.py (the Endpoint subclass) and models.py (Pydantic request/response schemas). The _config.py at the provider root declares one or more ProviderConfig enums; each member carries the endpoint path, aliases, type, options class, base URL, and auth type.

Adding a new provider

Step 1 — create the folder tree

lionagi/providers/{name}/
    _config.py
    {endpoint_type}/
        endpoint.py
        models.py

Step 2 — declare the config enum in _config.py

from enum import Enum
from lionagi.service.connections.provider_config import LazyType, ProviderConfig
from lionagi.service.connections.registry import EndpointType

class MyProviderConfigs(ProviderConfig, Enum):
    CHAT = (
        "chat/completions",          # endpoint path
        ["chat"],                    # aliases
        EndpointType.API,
        LazyType("lionagi.providers.myprovider.chat.models:MyChatRequest"),
        "https://api.myprovider.com/v1",
        "bearer",                    # auth_type
    )

MyProviderConfigs._PROVIDER = "myprovider"
MyProviderConfigs._PROVIDER_ALIASES = ["my-provider"]

Step 3 — write endpoint.py using the @register decorator

from lionagi.service.connections import Endpoint, EndpointConfig
from ._config import MyProviderConfigs  # noqa: F401 — side effect: registers

@MyProviderConfigs.CHAT.register
class MyProviderChatEndpoint(Endpoint):
    pass  # config is auto-created from _ENDPOINT_META injected by the decorator

Step 4 — add the import to registry.py

In lionagi/service/connections/registry.py, add the module to _modules inside _import_all_providers():

def _import_all_providers():
    import importlib

    _modules: list[str] = [
        # ... existing entries ...
        "lionagi.providers.myprovider._config",
        "lionagi.providers.myprovider.chat.endpoint",
    ]
    for mod in _modules:
        try:
            importlib.import_module(mod)
        except ImportError:
            pass

EndpointRegistry.match(provider="myprovider", endpoint="chat") will then find the endpoint automatically.

Default provider config

Set environment variables to avoid repeating provider= on every iModel() call:

export LIONAGI_CHAT_PROVIDER=openai
export LIONAGI_CHAT_MODEL=gpt-4.1-mini

Or configure per branch:

branch = li.Branch(
    chat_model=li.iModel(provider="anthropic", model="claude-opus-4-7-20251001"),
    parse_model=li.iModel(model="gpt-4o-mini"),
)

Next: Troubleshooting