Skip to content

API Reference

weego edited this page May 28, 2026 · 3 revisions

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,
    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.

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.

Clone this wiki locally