lughus

Micro-framework for building A2A agents with LiteLLM. Register tools, run an agentic loop, get a result. No graphs, no runners, no magic.

Installation

pip install lughus              # Core: agent loop, tool registry, LiteLLM
pip install "lughus[server]"    # + FastAPI, uvicorn, A2A gateway & developer console
pip install "lughus[all]"       # Everything (including OpenTelemetry SDK)

🚀 Two Tracks to Get Started

Track 1: Micro-Agent in 30 Seconds (Standalone Script)

Run an autonomous agent loop directly in a Python script without starting a server:

import asyncio
import json

from lughus import ToolRegistry, agent_loop
from lughus.testing import MockLLM

# 1. Create a tool registry and register tools (automatic schema inference)
registry = ToolRegistry()


@registry.tool
def greet(name: str) -> str:
    """Greet a user by name.

    Args:
        name: Name to greet
    """
    return json.dumps({"greeting": f"Hello, {name}!"})


# 2. MockLLM for offline tests or swap with LLM for production
llm = MockLLM(
    [
        [{"name": "greet", "arguments": {"name": "World"}, "id": "call_1"}],
        "Hello, World!",
    ]
)


# 3. Execute the loop
async def main():
    result = await agent_loop(
        llm,
        system="You are a greeting assistant. Use the greet tool.",
        context="Say hello to World",
        registry=registry,
        tool_names=["greet"],
    )
    print(result)  # "Hello, World!"
    print(f"{result.iterations} iterations, {result.total_tokens} tokens")


asyncio.run(main())

For live execution against 100+ LLM providers, swap MockLLM for LLM:

from lughus import LLM

llm = LLM(model="openai/gpt-4o", max_output_tokens=16384)

Track 2: Production A2A Agent (Server & Developer Console)

When your agent needs network transport, streaming, task status, and an interactive UI:

1. Scaffold an agent project

lughus new my_agent
cd my_agent && pip install -e ".[dev]"

2. Start the A2A server

export AGENT_MODEL="openai/gpt-4o"
export OPENAI_API_KEY="sk-..."
export ENABLE_CONSOLE="true"

python -m my_agent  # Starts ASGI server on http://localhost:8080

3. Explore the Developer Console (/ui)

Open http://localhost:8080/ui in your browser to access the interactive console:

• Live Streaming & Timeline: real-time token stream and step-by-step agent trajectory.
• Rich GFM Markdown & KaTeX: rendered tables, GitHub alerts ([!NOTE], [!WARNING]), and LaTeX math ($E=mc^2$).
• Interactive Human Approvals: live amber cards with Approve / Reject actions for sensitive tools.
• Artifact Downloads: view and download files generated by the agent.

🛡️ Governance & Deterministic Policy

Tools declare risk levels, required permission scopes, and approval gates. The policy engine evaluates actions before execution — prompt instructions are never used as access controls:

import json

from lughus import ToolEffect, ToolRegistry, ToolRisk

registry = ToolRegistry()


@registry.tool(
    risk=ToolRisk.CRITICAL,
    effects=frozenset([ToolEffect.WRITE, ToolEffect.IRREVERSIBLE]),
    requires_approval=True,  # Suspends the run until human confirms
)
def deploy(service: str) -> str:
    """Deploy a service to production."""
    return json.dumps({"status": "deployed", "service": service})

Container-confined Python Code Interpreter

Lughus provides an isolated Python code execution tool with automatic output truncation and timeout handling:

from lughus import ToolRegistry, register_code_interpreter

registry = ToolRegistry()
register_code_interpreter(registry, timeout_s=30.0, requires_approval=True)

⚙️ Configuration

All configuration is managed through environment variables loaded automatically via .env:

🏛️ Comparison Matrix

📚 Documentation & Resources

• 5-Minute Quickstart Guide
• Architecture & ADRs
• Agentic Design Guidelines
• Contract Stability Policy
• Framework Guarantees
• CHANGELOG
• CONTRIBUTING

Governed execution

See the unified run/stream guide. Before 1.0, minor releases may break APIs; pin and test upgrades.

License

MIT — see LICENSE.

Native clients and Python confinement

See A2A, MCP and Python security. The interpreter now requires an explicit Docker/Podman backend and artifact store; there is no unsafe fallback.