wanxingai/LightAgent

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

What it is – LightAgent is a Python library that lets you build LLM‑driven agents with a focus on small footprint and modularity. It provides a single‑agent runtime, multi‑agent routing, deterministic workflow orchestration, persistent memory, tool integration, streaming‑compatible APIs and optional durability (sessions, checkpoints, replay). The core is deliberately tiny (no LangChain or LlamaIndex) and works with any OpenAI‑compatible model endpoint (OpenAI, OpenRouter, DeepSeek, Qwen, vLLM, llama.cpp, etc.).

---

Core concepts & API surface

Layer	Main class / API	What it gives you
Single agent	LightAgent	Model calls, tool use, memory, guard‑rails, streaming, optional trace.
Durable runtime	Session, AgentRuntime	Event‑sourced replay, checkpoints, inbox/goals/budgets, async entry points.
Capability & policy	CapabilityRegistry, PolicyEngine	Scoped providers, permission snapshots, audit hooks.
Multi‑agent routing	LightSwarm	Role‑based delegation to specialised agents.
Deterministic workflows	LightFlow	DAG‑based step orchestration, retries, approval nodes, resume/rerun, persistent run records.
Tools	tools, ToolRegistry, MCP adapters	Register Python functions or external MCP tool servers; auto‑generated tools via the Tool Generator.
Memory	MemoryPolicy, MemoryScope, SharedMemoryPool	Per‑user long‑term memory (via mem0), in‑memory shared pool, provenance metadata, write admission controls.
Safety	input_guardrails, tool_guardrails, output_guardrails	Privacy blocking, confirmation for high‑risk tools, output redaction.
Hooks	hooks, HookContext	Middleware that can observe, replace or block any lifecycle phase.
Observability	trace=True, export_trace()	Structured JSONL events (model request, tool call, errors, latency, cost).
Evaluation	LightEvaluator, EvaluationCase	Deterministic regression tests for agents or flows.
Human review	HumanApprovalHook, JsonReviewStore	Fail‑closed tool approvals, editable decisions, durable review storage.

---

Typical use‑cases

Scenario	How LightAgent helps
Chatbot with persistent user memory	Attach a mem0 backend; agent.run(query, user_id="alice") automatically reads/writes that user’s long‑term memory.
Tool‑augmented assistants	Register Python functions (or MCP services) as tools; the agent can select and invoke them, with optional guard‑rails and human approval.
Complex multi‑step tasks	Define a LightFlow DAG (e.g., research → write → review) with explicit dependencies, retries and checkpointing; resume after failures without re‑running earlier steps.
Multi‑agent orchestration	Use LightSwarm to route an incoming request to the most appropriate specialised agent (e.g., sales, support, data‑analysis).
Production‑grade observability	Enable trace=True to capture structured events; export to JSONL or a monitoring system for latency, cost and error analysis.
Safety‑critical actions	Attach HumanApprovalHook and guard‑rail templates so that high‑risk tool calls (payments, deletions) require explicit reviewer consent.
Rapid prototyping of hundreds of tools	Feed API documentation to the built‑in Tool Generator to auto‑create tool wrappers, dramatically reducing manual boiler‑plate.

---

Quick start (installation & hello‑world)

# Core library
pip install lightagent
# Optional memory backend (mem0)
pip install mem0ai

from LightAgent import LightAgent

# Minimal agent – replace with your own model endpoint
agent = LightAgent(
    model="gpt-4.1",
    api_key="YOUR_KEY",
    base_url="https://api.openai.com/v1"
)

print(agent.run("Hello, who are you?"))

The call returns a plain string by default. Adding stream=True yields OpenAI‑compatible streaming chunks, trace=True records a detailed run trace, and result_format="object" returns a structured response containing the content plus metadata.

---

More advanced example – a checkpointed workflow

from LightAgent import LightAgent, LightFlow, JsonLightFlowStore

research = LightAgent(model="gpt-4.1", api_key="k", base_url="u")
writer   = LightAgent(model="gpt-4.1", api_key="k", base_url="u")
store = JsonLightFlowStore(".lightflow_runs")
flow = (
    LightFlow(store=store)
    .step("research", agent=research, timeout=30)
    .step("write", agent=writer, depends_on=["research"], max_retry=2)
)

run = flow.run("Analyze this company", run_id="report-001", trace=True)
if not run.success:
    run = flow.resume("report-001")
print(run.status)

LightFlow persists each step’s output; a failure in the write step can be retried or resumed without re‑executing research.

---

Project health & community

Metric	Value
Latest release	v0.10.0 (development) – adds event‑sourced runtime, durable sessions, SQLite‑FTS5 retrieval, and unified skill/MCP adapters.
License	Apache‑2.0 (permissive, commercial‑friendly).
Python versions	3.9 – 3.12 (as shown on PyPI badge).
Stars / forks	Visible on GitHub (badge indicates active community).
Documentation	Full docs site, API reference, FAQ, and dozens of markdown guides (memory, guardrails, tooling, evaluation, etc.).
Contributions	Open issue tracker, contribution guidelines, and a contributors badge – the project welcomes PRs.

---

When to pick LightAgent

• You need an agent framework that stays under a few hundred kilobytes of dependencies and can be dropped into any Python service.
• You want first‑class support for tool use, memory and safety without pulling in large ecosystems.
• Your product requires deterministic, checkpointable workflows (e.g., report generation pipelines).
• You plan to run multiple specialized agents that need to hand off work to each other.
• You need observability and optional human review for compliance or high‑risk actions.

If you only need a quick LLM wrapper with a single prompt, a lighter library like openai or litellm may suffice. For anything that involves stateful agents, tool orchestration, or production‑grade safety, LightAgent offers a purpose‑built, open‑source stack.

---

Where to go next

• Docs – https://sufe-aiflm-lab.github.io/LightAgent/ (installation, API reference, tutorials).
• GitHub – https://github.com/wanxingai/LightAgent (issues, roadmap, contribution guide).
• PyPI – https://pypi.org/project/lightagent/ (download stats, release notes).
• Paper – arXiv pre‑print linked in the badge for deeper design rationale.

---

Bottom line: LightAgent is a production‑oriented, modular framework for building LLM‑powered agents, tools, and multi‑step workflows while keeping the dependency surface tiny and offering built‑in safety, tracing and durability features.