Repository navigation
API Reference
weego edited this page May 28, 2026
·
3 revisions
This page summarizes the public API surface used by most LightAgent applications. It is not a replacement for source code, but it should be enough to wire an application without reading every module.
from LightAgent import (
LightAgent,
LightSwarm,
MemoryPolicy,
MemoryProtocol,
RunResult,
StreamEvent,
LightAgentError,
)Constructor:
agent = LightAgent(
name=None,
instructions=None,
role=None,
model="gpt-4.1",
api_key=None,
base_url=None,
websocket_base_url=None,
memory=None,
memory_policy=None,
memory_namespace=None,
tree_of_thought=False,
tot_model=None,
tot_api_key=None,
tot_base_url=None,
filter_tools=True,
self_learning=False,
tools=None,
skills_directories=None,
auto_discover_skills=True,
debug=False,
log_level="INFO",
log_file=None,
tracetools=None,
)| Parameter | Notes |
|---|---|
name |
Agent name. If omitted, LightAgent generates one. |
instructions |
Agent behavior instructions. Defaults to a helpful assistant instruction. |
role |
Role description added to the system prompt. |
model |
Model name for the OpenAI-compatible provider. Required by the constructor signature. |
api_key |
Provider key. If omitted, reads OPENAI_API_KEY. |
base_url |
Provider API root. If omitted, reads OPENAI_BASE_URL. |
websocket_base_url |
Reserved for websocket-compatible providers. |
memory |
Object with store() and retrieve() methods. |
memory_policy |
Optional shared-memory safety policy. |
memory_namespace |
Shortcut for MemoryPolicy(namespace=...). |
tree_of_thought |
Enables planning before the final model request. |
tot_model, tot_api_key, tot_base_url
|
Optional planning model configuration. |
filter_tools |
Allows Tree of Thought to narrow the active tool list. |
self_learning |
Allows the agent to write learned content into memory when memory is configured. |
tools |
Constructor-level tools, either callable tools or string tool names. |
skills_directories |
Directories scanned for SKILL.md. Defaults to ["skills"]. |
auto_discover_skills |
Discover Skills on startup and expose Skill tools. |
debug, log_level, log_file
|
Local logging controls. Logs are written under logs/. |
tracetools |
External tracing configuration, currently used for Langfuse-style integration. |
result = agent.run(
query,
tools=None,
light_swarm=None,
stream=False,
max_retry=10,
user_id="default_user",
history=None,
metadata=None,
use_skills=True,
result_format="str",
trace=False,
)| Parameter | Notes |
|---|---|
query |
User input. |
tools |
Runtime tools for this run. |
light_swarm |
Enables handoff to registered agents. Usually passed by LightSwarm.run(). |
stream |
Returns streaming output when True. |
max_retry |
Maximum retry count for model/tool continuation loops. |
user_id |
Stable identity for memory isolation and retrieval. |
history |
Prior messages in OpenAI chat format. |
metadata |
Extra parameters merged into the provider request. |
use_skills |
Includes discovered Skill metadata and Skill tools. |
result_format |
str, object, dict, or event. |
trace |
Records structured trace events for this run. |
Return modes:
| Call | Return type |
|---|---|
agent.run("hello") |
str |
agent.run("hello", result_format="object") |
RunResult |
agent.run("hello", result_format="dict") |
dict |
agent.run("hello", stream=True) |
generator of legacy chunks |
agent.run("hello", stream=True, result_format="event") |
generator of StreamEvent
|
Invalid combinations:
-
result_format="event"requiresstream=True. -
stream=Truedoes not supportresult_format="object"orresult_format="dict".
@dataclass
class RunResult:
content: str
reasoning_content: str | None = None
tool_calls: list[dict] = field(default_factory=list)
usage: dict | None = None
trace_id: str | None = None
trace: list[dict] = field(default_factory=list)
error: str | None = Nonestr(result) returns result.content.
@dataclass
class StreamEvent:
type: str
data: Any = None
trace_id: str | None = Nonestr(event) returns str(event.data).
class MemoryProtocol(Protocol):
def store(self, data: str, user_id: str) -> Any:
...
def retrieve(self, query: str, user_id: str) -> Any:
...policy = MemoryPolicy(
namespace="prod-tenant-a",
allow_unattributed_results=False,
)| Field | Meaning |
|---|---|
namespace |
Prefixes the user_id sent to memory backends. |
allow_unattributed_results |
Allows retrieved memory items without user_id metadata. |
import asyncio
asyncio.run(agent.setup_mcp(mcp_setting=mcp_settings))Registers tools from enabled MCP servers into the agent tool registry.
response = agent.run("hello", trace=True)
events = agent.export_trace()Returns structured trace events for the latest run.
agent.create_tool(user_input, tools_directory="tools")Generates tool code from a natural-language specification. Review generated code before production use.
swarm = LightSwarm()
swarm.register_agent(agent_a, agent_b)
response = swarm.run(agent=agent_a, query="Route this task.", stream=False)| Method | Purpose |
|---|---|
register_agent(*agents) |
Registers one or more LightAgent instances by name. |
run(agent, query, stream=False) |
Runs a registered entry agent with swarm handoff enabled. |
from LightAgent import LightAgentError, classify_exception, format_lightagent_errorCommon error codes include LA-401, LA-404, LA-413, LA-429, LA-JSON, and LA-TOOL.
LightAgent Wiki - see the repository, releases, and issues.
- Installation and Your First Agent
- Tools and Integrations
- Memory, Sessions, and RAG
- Workflows and Multiple Agents
- Agent Backends and Codex
- Durable Execution, Jobs, and Subagents
- Safety, Observability, and Evaluation
- Usage, Cost Estimates, and Budgets
- Deployment, Migration, and Verification
- 安装与第一个 Agent
- 工具和集成
- 记忆、会话与 RAG
- 工作流与多 Agent
- 执行后端与 Codex
- 持久执行、Jobs 与 Subagents
- 安全、观测与评测
- 用量统计、费用估算与预算
- 部署、升级与验收
- Quick Start
- Core Concepts
- API Reference
- Examples Cookbook
- Migration Guide
- Tools
- Tool Generator
- Memory
- MCP
- Skills
- LightFlow
- Tree of Thought
- Self-Learning
- Multi-Agent
- Tracing and Debugging
- Langfuse Observability
- Model Providers
- browser-use Integration
- Testing and CI
- Deployment Guide
- Architecture
- Security
- Known Limitations
- FAQ
- FAQ 中文
- Roadmap
- Release Process
- Contributing