API Reference

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.

Imports

from LightAgent import (
    LightAgent,
    LightFlow,
    LightFlowResult,
    LightFlowStep,
    LightFlowStepResult,
    LightSwarm,
    MemoryPolicy,
    MemoryProtocol,
    RunResult,
    StreamEvent,
    LightAgentError,
)

LightAgent

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.

agent.run()

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" requires stream=True.
• stream=True does not support result_format="object" or result_format="dict".

RunResult

@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 = None

str(result) returns result.content.

StreamEvent

@dataclass
class StreamEvent:
    type: str
    data: Any = None
    trace_id: str | None = None

str(event) returns str(event.data).

MemoryProtocol

class MemoryProtocol(Protocol):
    def store(self, data: str, user_id: str) -> Any:
        ...

    def retrieve(self, query: str, user_id: str) -> Any:
        ...

MemoryPolicy

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.

setup_mcp()

import asyncio

asyncio.run(agent.setup_mcp(mcp_setting=mcp_settings))

Registers tools from enabled MCP servers into the agent tool registry.

export_trace()

response = agent.run("hello", trace=True)
events = agent.export_trace()

Returns structured trace events for the latest run.

create_tool()

agent.create_tool(user_input, tools_directory="tools")

Generates tool code from a natural-language specification. Review generated code before production use.

LightSwarm

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.

LightFlow

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().

LightFlowResult

@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 = None

result.success is True when error is None. str(result) returns result.content.

LightFlowStepResult

@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().

Error Helpers

from LightAgent import LightAgentError, classify_exception, format_lightagent_error

Common error codes include LA-401, LA-404, LA-413, LA-429, LA-JSON, and LA-TOOL.