leagent

The open-source desktop AI agent that gets work done — an agent that plans and self-corrects, agentic visual workflows, generative UI, and 100+ offline tools in a single self-hostable stack.

中文文档 · 汉文 · Tutorial · Contributor guide · Releases

LeAgent is an open-source desktop AI agent that doesn't just chat — it gets work done. Unlike cloud chatbots and code-only CLIs, LeAgent fuses three capabilities most agents keep apart: a streaming agent runtime that plans, calls tools, and self-corrects in one think-act loop; agentic visual workflows where the agent designs, runs, and refines ReactFlow DAGs (and every one of its tools is automatically a typed node); and a generative UI layer that streams live, interactive interfaces — KPI boards, slide decks, galleries — right into the chat. It ships 100+ built-in offline tools (documents, web, data, code, databases, media, game-art generation) plus a declarative rule engine, Agent Skills, and the Model Context Protocol — all running locally with zero external dependencies by default (SQLite, single process). Bring your own model keys, or run fully offline against a local Ollama / vLLM endpoint.

It is built for people who want a private, hackable, self-hosted alternative to closed agent products: your documents, sessions, and credentials never leave the machine unless you point a provider at a remote API.

Highlights

• Agent runtime — multi-turn sessions with token streaming, tool execution, tiered model routing, layered prompt assembly, and a cognitive three-store memory (episodic / semantic / procedural). The QueryEngine session orchestrator drives both chat and background paths through one think-act loop, with durable checkpoints for pausing and resuming turns.
• 100+ offline tools — documents, web research, data wrangling, code execution, databases, generative UI, charts, media, and coding projects (see the tool catalog below).
• Visual workflows — a ReactFlow editor with YAML export, reusable templates, and automatic typed nodes for every tool. The engine stages ready batches, runs independent branches concurrently, and applies centralized retry/backoff and timeouts.
• Agent Skills — Agent Skills v1.0 SKILL.md bundles with progressive disclosure and on-demand loading. Ship built-in skills, install from links or archives, or plug in an HTTP skill registry.
• Research Paper Mode — open a PDF and the agent becomes a citation-grounded research analyst: structure & outline extraction, faithful section / whole-paper summaries, reference and LaTeX-formula extraction, and region translation — with reader tabs and matching agent tools, text extraction fully offline. (guide)
• Generative UI — agents stream declarative UI trees (KPI boards, slide decks, galleries, steppers) that render inline in chat and export to PDF or PPTX.
• Game-art asset pipeline — first-class, composable generation nodes (image / video / 3D mesh / VFX) with typed media sockets, a quality gate plus a bounded self-correction loop, and inline canvas previews. Runs end-to-end offline with no credentials. (docs)
• Multi-provider LLM — DeepSeek, DashScope (Qwen), OpenAI, Anthropic, Azure OpenAI, Ollama, and vLLM, with cost-tiered routing and failover. DeepSeek is the most thoroughly validated and recommended for first use.
• Sidebar desk pet — a customizable avatar with walk/jump animations and personality bubbles, synced to chat streaming and session state. Upload PNG / SVG / GIF or sprite sheets.
• Integrations — MCP servers, inbound webhooks, scheduled cron jobs, outbound channels (IM/console), and a declarative YAML rule engine.
• Zero-config default — SQLite out of the box and a single Docker container. Scale out with PostgreSQL and Milvus (vector-backed memory) when you need to.

What you can build

LeAgent is a complete agent platform, not a starter kit — the building blocks below are wired together and work out of the box, fully offline by default.

• Office automation — point it at a folder of invoices, contracts, or reports: it OCRs and classifies the files, extracts structured data into Excel, and produces a polished Word or PPTX summary in a single turn.
• Research & briefings — search across DuckDuckGo / SearXNG / Bing, scrape and download sources, then assemble a cited PDF report with charts and KPI dashboards.
• Data analysis — load CSV/Excel or query the database, clean, merge, aggregate, run SQL and vector search, and narrate the findings with generated charts.
• Coding companion — scaffold a project from a template, edit files across the tree, run a live dev server behind a preview proxy, and execute code in an isolated sandbox.
• Game-art production — turn a text brief into images, video, 3D meshes, and VFX sprite sheets through a node graph that self-corrects against a quality gate and exports an engine-ready (Unity / Unreal / Godot) bundle.
• Live, interactive answers — stream Generative UI (KPI boards, slide decks, galleries, steppers) straight into chat, then export it to PDF or PPTX.
• Always-on automation — schedule cron jobs, trigger flows from inbound webhooks, fan out to IM channels (DingTalk / Feishu / WeChat Work), and gate behaviour with declarative YAML rules.

Architecture

LeAgent is an async Python (FastAPI) backend plus a React 19 single-page app, packaged as a modular monolith. The backend uses a strict, downward-only layered domain model — File → Code → Project — over a single persistence layer, and every agent turn (chat, SDK, background task, sub-agent, workflow node) converges on one think-act kernel.

LeAgent/
├── backend/                 # FastAPI backend (Python 3.11+, uv-managed)
│   └── leagent/
│       ├── agent/           # QueryEngine orchestrator, planner, subagents
│       ├── sdk/             # Versioned public Agent SDK (runtime, kernel, protocols)
│       ├── api/             # FastAPI routers (v1 + incubating v2)
│       ├── llm/             # LLM service, providers, transport, streaming, generation
│       ├── tools/           # 100+ tools across 13 categories
│       ├── workflow/        # Workflow engine, nodes, art-asset pipeline, templates
│       ├── context/         # Source-driven, relevance-gated prompt assembly
│       ├── prompts/         # Layered PromptBuilder, registry, templates
│       ├── memory/          # Episodic / semantic / procedural agent memory
│       ├── skills/          # Agent Skills v1.0 loader + registry
│       ├── rules/           # Declarative YAML rule engine
│       ├── mcp/             # Model Context Protocol
│       ├── file/ code/ project/   # Layered file → code → project domain model
│       ├── db/              # Persistence: engine, SQLModel models, repositories
│       └── services/        # DB, auth, chat, session, gen-ui, cron, ...
├── frontend/                # React 19 + TypeScript SPA (Vite, Zustand, React Query)
├── desktop/                 # Electron shell (bundled Python runtime)
├── deploy/                  # Dockerfile + SQLite-only Compose
├── config/                  # Demo workflows + workflow templates
├── docs/                    # Architecture, guides, deployment docs
└── start.sh / start.ps1     # Dev orchestrator (uv + npm)

Execution model

Regardless of where a request enters, it flows through one set of well-defined boundaries. Each ingress mints a single ExecutionRun (with a run_id and, for child scopes, a parent_run_id), goes through a thin facade, runs on the shared kernel, and persists to durable state with one owner per state class:

Ingress   HTTP/SSE · WebSocket · Cron · Background task · GenUI
   │
   ▼
Facade    ServiceManager.runtime_context · AgentRuntime · WorkflowService
   │
   ▼
Kernel    run_loop → QueryEngine → tool executor          (single think-act loop)
   │
   ▼
State     TieredSessionStore · CheckpointStore · WorkflowStateStore
   │
   ▼
Observe   EventManager (FLOW_*/TASK_*/AGENT_*) · OpenTelemetry

• One kernel. Chat and every background path drive through leagent.sdk.kernel.run_loop. Turns pause to a durable checkpoint when they await user input, then resume exactly where they left off.
• Three workflow shapes, one engine. Saved DAG flows, chat playbook step-cards (compiled to linear flows), and in-chat graph embeds all execute on the same WorkflowExecutor, which stages ready batches, runs independent branches concurrently, and applies centralized retry/backoff and timeouts.
• Clear state ownership. The chat transcript lives in TieredSessionStore, paused turns in CheckpointStore (agent_checkpoints), and workflow runs in WorkflowStateStore — no shared mutable state across subsystems.

See AGENTS.md for the full subsystem map and docs/technical/execution-topology.md for the authoritative agent-loop / workflow-engine state contract.

Tool catalog

Every tool is auto-exposed as a typed workflow node, so anything the agent can call can also be wired into a visual flow.

Capabilities in depth

Agent runtime & memory

• Multi-turn streaming sessions with tiered model routing, automatic context compaction (micro + auto), and abort-safe tool execution.
• Hybrid reasoning — ReAct-style tool loops plus plan-and-execute — with sub-agent delegation and per-turn recovery.