Skip to content

Architecture

weego edited this page Nov 15, 2026 · 3 revisions

Architecture

LightAgent keeps a small core and delegates persistence, external systems, and domain behavior to composable adapters.

Runtime Components

User Query
   |
   v
LightAgent.run()
   |
   +-- History
   +-- Memory.retrieve()
   +-- Skills metadata
   +-- Tree of Thought planning
   +-- ToolRegistry schemas
   |
   v
OpenAI-compatible Chat Completion
   |
   +-- Final answer
   +-- Tool calls
          |
          v
      AsyncToolDispatcher
          |
          +-- Python tools
          +-- Built-in tools
          +-- MCP tools
          +-- Skill tools

LightFlow
   |
   +-- Step dependency validation
   +-- Per-step retries
   +-- Dependency output passing
   +-- Flow trace events
   |
   v
Named LightAgent.run() steps

Main Modules

Module Responsibility
core.py LightAgent, run loop, tool calling, memory context, swarm handoff
flow.py LightFlow, step dependency execution, flow results, flow trace events
tools.py Tool registry, dynamic loading, async dispatch
protocol.py MemoryProtocol and MemoryPolicy
result.py RunResult and StreamEvent
tracing.py Trace event recording
skills.py Skill discovery and activation
skill_tools.py Tools for listing and activating Skills
mcp_client_manager.py Optional MCP stdio, SSE, and Streamable HTTP client integration
errors.py Error taxonomy and formatting
session.py, runtime.py Versioned Session history, replay, context projection, and Runtime state
dag/ Dynamic task graph, Worker outcomes, verifier-bound artifacts, and recovery
backends/ Explicit native and Codex execution adapters, probing and session bindings
persistent/ Reconnectable single-host tasks, transactional state, budgets, and interaction
security.py, supply_chain.py Capability authorization and opt-in Provider attestation

The diagram above is the native model loop, not the external Codex path. See Agent Backends and Durable Runtime for the additional v1.0.0 paths.

Extension Points

  • Python tools through tool_info.
  • Runtime tools through agent.run(..., tools=[...]).
  • Memory through store() and retrieve().
  • MCP tools through setup_mcp().
  • Skills through SKILL.md directories.
  • Deterministic workflow composition through LightFlow.
  • External tracing through tracetools.

Design Principle

Keep the framework small and let applications own domain policy:

  • persistence
  • user authorization
  • high-risk action approval
  • memory governance
  • deployment topology
  • business workflow orchestration above or around LightFlow

Clone this wiki locally