wanxingai/LightAgent

LightAgent – an ultra‑lightweight, open‑source agent framework

What it is – LightAgent is a Python library that lets you build, run, and orchestrate LLM‑powered agents. It focuses on a small code‑base, modular design, and production‑ready features such as persistent memory, tool integration, multi‑agent routing, deterministic workflows, and OpenAI‑compatible streaming APIs.

Key capabilities

Feature	What it gives you
Single‑agent runtime	LightAgent handles model calls, optional tools, memory, guardrails and streaming with a single run() call.
Memory	Built‑in support for long‑term user memory (via the mem0 module) and a prototype shared‑memory pool for multi‑agent experiments.
Tool use	Register Python functions as tools; a safe expression tool is provided by default. Arbitrary Python execution is disabled unless you add a sandboxed tool.
Tree‑of‑Thought reasoning	Decompose complex queries into multi‑step reasoning with reflection.
Multi‑agent collaboration	LightSwarm routes user intents to specialised agents; agents can delegate tasks to one another.
Workflow orchestration	LightFlow builds deterministic DAG workflows with step dependencies, retries, checkpointing, approval nodes and resume/re‑run support.
Dynamic DAGs	LightDAG (opt‑in) persists runtime graph changes, runs workers concurrently, and requires verification before publishing artifacts.
Streaming API	Returns OpenAI‑style streaming chunks, so you can drop the agent into any chat UI that expects the OpenAI streaming format.
Observability & tracing	trace=True records structured events (model calls, tool usage, errors, latency) without changing the default string return.
Safety & guardrails	Input, tool and output guardrail templates block private data, require human confirmation for risky tools, and redact sensitive output.
Human‑in‑the‑loop	HumanApprovalHook lets you pause execution for manual review of high‑impact actions.
Evaluation harness	LightEvaluator runs deterministic regression cases to verify behaviour, latency, cost, and policy compliance.
Extensible runtime	Sessions, AgentRuntime, capability registry, policy engine, inbox/goals/budgets, and optional SQLite‑FTS5 retrieval for scalable production use.

Typical usage patterns

from LightAgent import LightAgent, LightFlow, HumanApprovalHook, LightEvaluator

# Basic agent
agent = LightAgent(model="gpt-4.1", api_key="…")
print(agent.run("Hello, who are you?"))

# Streaming response
for chunk in agent.run("Tell me a story", stream=True):
    print(chunk, end="")

# Add a tool and guardrails
agent = LightAgent(
    model="gpt-4.1",
    tools=[my_search_tool],
    input_guardrails=[block_private_data],
    hooks=[HumanApprovalHook(tools={"send_payment"})]
)

# Deterministic workflow with LightFlow
flow = LightFlow().step(name="search", tool=my_search_tool).step(name="summarize", depends_on="search")
result = flow.run("Give me a summary of recent AI papers")

# Evaluate agent behaviour
report = LightEvaluator().run(agent, [
    EvaluationCase(name="payment policy", query="Pay invoice 42", expected_trace_events=("approval_required",))
])
print(report.to_dict())

Installation

pip install lightagent          # core library
pip install mem0ai            # optional memory backend

The package is published on PyPI, supports Python 3.8+, and works with any OpenAI‑compatible endpoint (OpenAI, OpenRouter, DeepSeek, Qwen, vLLM, llama.cpp, etc.).

Why you might choose LightAgent

• Small footprint – no heavy dependencies like LangChain or LlamaIndex.
• Production‑ready – durable sessions, checkpointed flows, approval hooks, and structured tracing.
• Extensible – plug in custom tools, memory adapters, capability policies, or your own sandbox.
• Open source – Apache‑2.0 license, active community, extensive documentation and examples.

---

Resources

• Docs: https://sufe-aiflm-lab.github.io/LightAgent/
• GitHub: https://github.com/wanxingai/LightAgent
• PyPI: https://pypi.org/project/lightagent/
• Paper (arXiv): https://arxiv.org/abs/2509.09292