Core Concepts

Core Concepts

LightAgent

LightAgent is the main runtime object. It owns:

• model configuration
• tool registry
• optional memory backend
• optional Skills discovery
• optional Tree-of-Thought planning
• optional tracing and debug logging
• optional MCP tool registration
• optional LightFlow workflow composition

Typical constructor:

from LightAgent import LightAgent

agent = LightAgent(
    name="SupportAgent",
    instructions="You are a helpful support agent.",
    role="Answer product support questions.",
    model="gpt-4.1",
    api_key="your_api_key",
    base_url="https://api.openai.com/v1",
)

Run Cycle

At a high level, agent.run() performs these steps:

1. Create a trace id for the run.
2. Register runtime tools passed through tools=[...].
3. Optionally let LightSwarm decide whether to hand off the task.
4. Build the system prompt from agent name, instructions, role, date, and time.
5. Add Skills metadata if Skills are discovered.
6. Retrieve memory context if a memory backend is configured.
7. Optionally run Tree-of-Thought planning.
8. Send a chat completion request.
9. Execute model-selected tools when tool calls are returned.
10. Return a string, RunResult, legacy stream generator, or StreamEvent generator.

LightFlow Workflows

LightFlow sits above individual agents. It does not replace LightAgent.run(); it coordinates multiple agent runs as named deterministic steps.

Use LightFlow when the workflow shape is known in advance:

• research then write
• extract then validate then summarize
• classify then route to a fixed follow-up step
• run independent steps and combine their outputs

Each step has a unique name, an agent, optional dependencies, optional runtime tools, and an optional custom query builder. Dependency outputs are available to later steps through the flow context.

Main Public Objects

Object	Purpose
LightAgent	Main agent runtime
LightFlow	Deterministic DAG-style workflow runner for named agent steps
LightFlowStep	Step configuration used by LightFlow.step()
LightFlowStepResult	Structured result for one completed or failed flow step
LightFlowResult	Structured result for the whole flow
LightSwarm	Simple multi-agent registration and handoff helper
ToolRegistry	Stores tool metadata and callable mappings
ToolLoader	Loads named tools from a tools directory
AsyncToolDispatcher	Executes sync, async, and generator tools
MemoryProtocol	Minimal memory interface contract
MemoryPolicy	Optional namespace and retrieval safety policy
RunResult	Optional structured non-streaming result
StreamEvent	Optional structured streaming event
TraceRecorder	Records structured trace events
SkillManager	Discovers and activates SKILL.md based Skills

Return Modes

Call	Return
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

Compatibility Notes

• Existing agent.run("hello") code remains compatible.
• Existing agent.run(query, stream=True, user_id=user_id) code remains compatible.
• Structured results and structured streaming events are opt-in.
• result_format="event" requires stream=True.
• result_format="object" and result_format="dict" are non-streaming modes.