Repository navigation
V1 Durable Runtime en
简体中文 | English
Applies to v1.0.0. Use ExecutionService for ordinary durable work. It does not require a research contract or browser UI and is not a general distributed Worker queue.
This example registers a trusted local fixture in a temporary directory. The supervisor claims the submitted task; a new handle then reads its state from the same control root:
from pathlib import Path
from tempfile import TemporaryDirectory
from LightAgent import (
BackendCapabilities, BackendProbe, BackendResult, ExecutionHandle,
ExecutionService, SecurityContext,
)
class LocalFixture:
def probe(self):
return BackendProbe("offline-fixture", "1", BackendCapabilities())
async def execute(self, request):
request.emit("progress", completed=1)
return BackendResult("本地验收完成")
with TemporaryDirectory() as directory:
root = Path(directory)
workspace = root / "workspace"
workspace.mkdir()
service = ExecutionService(root / "control", backend_factories={"local": LocalFixture})
handle = service.submit(
"检查本地任务契约", workspace, backend="local",
security_context=SecurityContext(
user_id="alice", tenant_id="local", project_id="docs", network_allowed=True,
),
idempotency_key="guide-task",
budget={"backend_calls": 1},
)
service.serve_forever(max_ticks=1)
restored = ExecutionHandle.connect(handle.id, root=service.root)
assert restored.status()["status"] == "completed"
print(restored.status()["status"], restored.budget()["used"]["backend_calls"])The fixture does not make a network request. The example context does not require it to enforce network isolation. In production, choose a backend that meets your actual constraints. For example, ExecutionRequirements(isolation="docker") requires real Docker isolation, not host execution or a CLI sandbox. The trusted host restores registered factories; the SQLite database cannot direct arbitrary Python imports. See the complete durable task example.
| Capability | How to use it | What to watch for |
|---|---|---|
| Inspect and reconnect |
ExecutionHandle.connect(), status(), events(after=...), records()
|
Save the task ID and control root. Do not expose the control directory directly to end users. |
| Pause and cancel |
pause(), resume(), cancel()
|
Pausing stops new claims, not necessarily an active call. Cancellation is cooperative and does not roll back external effects. |
| Messages and receipts |
send(content, idempotency_key=...), receipt(message_id)
|
Received and applied are distinct states. The same key cannot be reused with different content. |
| Human interaction |
InteractionRequests: question, plan_review, and approval
|
Bind task, attempt, epoch, identity, and expiry. High-risk approval must bind the exact operation and arguments. The framework has no application approval UI. |
| Scheduled wakeups |
WakeupScheduler.schedule() and cancel()
|
Runs in the supervisor tick; supports durable deduplication and skip/coalesce for missed triggers. It does not start a second scheduler. |
| Usage and budget |
budget(), BudgetLedger
|
Reserve and settle idempotently; child accounts consume ancestor budgets. Unknown cost is not zero. Hard token or cost limits must be enforced by the backend. |
| Unknown outcome |
reconciling, reconcile(action=..., note=...)
|
Inspect external receipts before explicitly choosing retry or discard. There is no exactly-once guarantee. |
After an interruption, leases and attempt epochs reject stale receipts without guessing whether an external action ran. Revalidate after backend configuration changes; do not rewrite historical configuration digests. A durable task marked completed means the backend confirmed execution ended, not that the result meets domain requirements.
agent.runtime exposes ordered Inbox messages, Goals, BudgetLimits, Jobs, and Subagents. You can also create a standalone AgentRuntime(session_store=...). This planning example calls no model and starts no Worker:
from LightAgent import AgentRuntime, InMemorySessionStore
runtime = AgentRuntime(session_store=InMemorySessionStore())
runtime.open_session("docs-runtime")
goal = runtime.goals.create("准备发布", acceptance_criteria=["回归通过"])
runtime.goals.activate(goal.goal_id)
runtime.inbox.enqueue("steering", "先完成验收,不发布", message_id="hold")
print(goal.goal_id)Runtime Jobs, Subagents, and persistent external Jobs share lifecycle and fencing rules in v1.0.0. Each still uses its own Session events or ControlStore records as the source of truth. Use runtime.jobs for async jobs. Register a child with runtime.subagents.register(..., persistent=True), then call subagents.run(..., idempotency_key=..., lease_seconds=...). After restart, open the same Session and have the application bind() a trusted Python instance; callables are not deserialized or blindly replayed. A synchronous thread may still be running after cooperative cancellation. Reconcile through the Job API once the host confirms the outcome.
python example/16.jobs_and_history.pyThe offline example runs a child Job, backs up stopped history, opens the restored copy in a new Runtime, and rebinds the trusted instance. Reusing the idempotency key does not run the work again. See Durable Execution and Jobs and History Recovery. For deployment isolation, migration rehearsals with the frozen wheel, and rollback, see Deployment and Verification.
LightAgent Wiki - see the repository, releases, and issues.
- Installation and Your First Agent
- Tools and Integrations
- Memory, Sessions, and RAG
- Workflows and Multiple Agents
- Agent Backends and Codex
- Durable Execution, Jobs, and Subagents
- Safety, Observability, and Evaluation
- Usage, Cost Estimates, and Budgets
- Deployment, Migration, and Verification
- 安装与第一个 Agent
- 工具和集成
- 记忆、会话与 RAG
- 工作流与多 Agent
- 执行后端与 Codex
- 持久执行、Jobs 与 Subagents
- 安全、观测与评测
- 用量统计、费用估算与预算
- 部署、升级与验收
- Quick Start
- Core Concepts
- API Reference
- Examples Cookbook
- Migration Guide
- Tools
- Tool Generator
- Memory
- MCP
- Skills
- LightFlow
- Tree of Thought
- Self-Learning
- Multi-Agent
- Tracing and Debugging
- Langfuse Observability
- Model Providers
- browser-use Integration
- Testing and CI
- Deployment Guide
- Architecture
- Security
- Known Limitations
- FAQ
- FAQ 中文
- Roadmap
- Release Process
- Contributing