Repository navigation
API Reference
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.
For v1.0.0, also see the tagged public API inventory, the backend guide, durable execution and Jobs, and security and evaluation. The constructor and calls below focus on the native Agent path.
from LightAgent import (
LightAgent,
LightFlow,
LightFlowResult,
LightFlowStep,
LightFlowStepResult,
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. |
flow = (
LightFlow()
.step("research", agent=research_agent)
.step("write", agent=writer_agent, depends_on=["research"], max_retry=2)
)
result = flow.run(
"Analyze this company",
user_id="default_user",
trace=True,
result_format="object",
)LightFlow runs named LightAgent steps in dependency order. It is available in v0.8.0 and is additive; existing LightAgent and LightSwarm code does not need to change.
| Method | Purpose |
|---|---|
step(name, *, agent, depends_on=None, query=None, tools=None, max_retry=1, metadata=None) |
Adds one named step and returns the flow for chaining. |
run(query, *, user_id="default_user", trace=False, result_format="object") |
Runs the flow and returns LightFlowResult, str, or dict. |
Step parameters:
| Parameter | Notes |
|---|---|
name |
Unique step name. |
agent |
Object with a compatible run() method, usually LightAgent. |
depends_on |
List of step names that must complete before this step. |
query |
Optional callable that receives flow context and returns the step prompt. |
tools |
Optional runtime tools for this step. |
max_retry |
Step-local retry count. Must be at least 1. |
metadata |
Optional per-step metadata for application use. |
Supported result_format values:
| Value | Return type |
|---|---|
object |
LightFlowResult |
str |
Final content string |
dict |
Serializable dictionary |
LightFlow validates duplicate step names, missing dependencies, dependency cycles, invalid retry counts, and agents without run().
@dataclass
class LightFlowResult:
content: str
steps: list[LightFlowStepResult] = field(default_factory=list)
trace_id: str | None = None
trace: list[dict] = field(default_factory=list)
error: str | None = Noneresult.success is True when error is None. str(result) returns result.content.
@dataclass
class LightFlowStepResult:
name: str
content: str
error: str | None = None
attempts: int = 1
trace: list[dict] = field(default_factory=list)LightFlowStep is the configuration object created by LightFlow.step().
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