Skip to content

V1 Operations and Migration en

weego edited this page Nov 15, 2026 · 2 revisions

Deployment, Migration, and Verification

简体中文 | English

Applies to LightAgent v1.0.0. Ordinary calls can stay unchanged; verify persistent state and external integrations separately. Neither the current branch, PyPI distribution, nor historical development records define what this tag shipped.

Choose optional dependencies

The base package directly depends on the OpenAI SDK, HTTPX, jsonschema, and PyYAML. Native Agents, Python tools, Skills, core workflows (LightFlow and LightDAG), local tracing, and the built-in memory protocol do not require extras. There is no skills extra. The base package does not install a model service.

pip install lightagent
pip install 'lightagent[mcp,langfuse]'
pip install 'lightagent[all]'

The first command installs the base package. The second adds only MCP and Langfuse dependencies. The third adds all the SDKs below. You can add extras to an environment that already has the base package. Pin PyPI with ==1.0.0 or install directly from the GitHub tag:

pip install 'lightagent[all]==1.0.0'
python -m pip install 'lightagent[all] @ git+https://github.com/wanxingai/LightAgent.git@v1.0.0'

This table is based on PyPI v1.0.0 and the tagged package configuration. All SDKs below are optional.

Extra Python dependency When you need it
mcp mcp Connect to MCP tool servers or serve MCP over stdio. The Codex dynamic tool bridge itself does not require it.
mem0 mem0ai Use Mem0 as a memory backend. Custom adapters and SharedMemoryPool do not need it.
langfuse langfuse Send traces to Langfuse. Local tracing does not need it.
litellm litellm Use LiteLLM model routing. An ordinary OpenAI-compatible connection does not need it.
oss or nos boto3 Use the corresponding object storage tools. Both extras install the same SDK.
signing cryptography Verify Ed25519 Provider signatures.
all All the SDKs above Use several integrations or set up a full development environment. For production, prefer only the extras you use.

all installs Python dependencies only. It does not enable integrations, write credentials, or install the Codex CLI, Docker, a browser, external services, or LightResearch. Set up service URLs, permissions, and credentials separately for the features you use.

Repeatable offline verification

git clone --branch v1.0.0 --depth 1 https://github.com/wanxingai/LightAgent.git
cd LightAgent
python -m pip install -e '.[signing]'
python example/13.runtime_v010.py
python example/14.dynamic_dag.py
python example/15.durable_execution.py
python example/16.jobs_and_history.py
python example/17.signed_providers.py

These examples check local RAG, a dynamic DAG, an ordinary durable task, Subagent and history reconnection, and signature invalidation. None needs a live model. Other model, Mem0, MCP, and browser examples have separate dependencies, services, and credential requirements.

Release CI is not live integration coverage

  • The release CI passed on Python 3.10, 3.11, 3.12, and 3.13, and MCP 1.12.4, 1.30.0, and 2.3.0. The core matrix checks a base install without MCP, the core suite with locked dependencies, wheel building, and an installed-wheel smoke test outside the repository. It does not cover every extra, OS, or production service combination.
  • Review separate evidence for Docker and real Workers, soak tests, real Codex, real Mem0 Graph, your remote MCP server, and joint LightResearch tests. A skipped opt-in test is not a pass. A 15-minute soak is a bounded local check, not a 24-hour stability guarantee.
  • The containerized tests/acceptance/clean_matrix.py records versions, dependency locks, JUnit reports, wheel digests, and logs. Without Docker, run tests/acceptance/verify.py in a clean virtual environment with a built core wheel. See Clean Environment Verification and the historical acceptance record for procedures and evidence.

Migrate, reconcile, and roll back

  1. Separate ordinary calls from long-running tasks. Existing run(), arun(), streaming, Tools, Hooks, Guardrails, Memory, LightFlow, LightSwarm, and LightDAG entry points remain available. Do not replace every conversation with ExecutionService. Add extras only for SDKs you use.
  2. Stop all writers before backing up. HistoryBundle.capture(source, backup, quiescent=True) copies controlled local history into a new directory. HistoryBundle.restore(backup, candidate) restores into another new directory. Keep the original history and do not overwrite the original database. A consistent SQLite backup with permission and hash checks is not a safe importer for untrusted input.
  3. Verify the copy. Check Jobs, Subagents, sessions, message receipts, budgets, and artifacts. Rebind trusted instances and execution settings. Record unanchored history as such; use SqliteSessionStore.anchor_legacy(...) only after explicit review. Stop on configuration, permission, path, or digest mismatches. Do not edit a digest to force compatibility.
  4. Reconcile unknown outcomes. Check external receipts and distinguish complete, incomplete, and unknown work. The host must explicitly reconcile unknown work rather than replaying possible side effects in bulk.
  5. Prepare rollback. Restore a read-only copy for the previous version from the pre-migration backup. Do not write to a newly anchored copy with the old version. Rehearse restoration with the frozen old wheel using Jobs and History Migration before a real upgrade.

LightResearch and application integration

Research loops, research chat, report search, evaluation, and the reference panel belong to the separate LightResearch extension. Legacy mode="persistent" still means research mode. Install a compatible LightResearch and explicitly call LightResearch.enable_legacy_api() on the host to enable it. For ordinary long-running tasks use ExecutionService. A LightResearch wheel that accepts only older prereleases of LightAgent will not work directly with 1.0.0.

Joint validation requires an explicit --research-source ../LightResearch or --research-wheel /path/to/lightresearch.whl; it does not search sibling directories automatically. Production applications provide authentication, tenant isolation, operations, monitoring, and their UI. The core does not provide distributed scheduling, a production UI, or exactly-once external side effects. See Research Migration and Service Templates.

Clone this wiki locally