Repository navigation
V1 Durable Runtime
简体中文 | English
适用版本:v1.0.0。普通持久任务用 ExecutionService,不要求研究契约或浏览器界面。它不是通用分布式 Worker 队列。
此示例在临时目录注册可信本地 fixture。提交后由 supervisor 领取,在同一个控制根中重新创建句柄查看状态:
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"])这个 fixture 不执行网络请求;示例 Context 没有要求 fixture 提供网络隔离。生产应用应按实际需求选择后端,例如要求 ExecutionRequirements(isolation="docker") 时,必须有真实 Docker 隔离,不能由宿主执行或 CLI sandbox 替代。后台工厂由可信宿主恢复注册,不能由 SQLite 配置任意导入 Python 对象。查看 完整任务示例。
| 能力 | 如何使用 | 需要注意 |
|---|---|---|
| 观察与重连 |
ExecutionHandle.connect()、status()、events(after=...)、records()
|
保存任务 ID 和控制根;不要直接向普通用户开放控制目录。 |
| 暂停与取消 |
pause()、resume()、cancel()
|
暂停停止后续领取,不等于立即终止正在运行的操作;取消需协作,不保证外部回滚。 |
| 消息与回执 |
send(content, idempotency_key=...)、receipt(message_id)
|
回执区分已接收与已应用;同键不同内容会被拒绝。 |
| 人工交互 |
InteractionRequests 的 question、plan_review、approval
|
关联 task、attempt、epoch、身份、过期;高风险审批必须绑定具体操作和参数,框架不提供业务审批 UI。 |
| 定时唤醒 |
WakeupScheduler 的 schedule()、cancel()
|
与 supervisor tick 一起运行,支持持久去重与错过触发的 skip/coalesce;不是另起第二个调度器。 |
| 用量和预算 |
budget()、BudgetLedger
|
预留与结算需幂等,子账户占用祖先额度;未知费用不算零。精确 token/费用硬上限要后端明确实施。 |
| 结果不明 |
reconciling、reconcile(action=..., note=...)
|
先查外部回执,再明确选择 retry 或 discard。没有 exactly-once 保证。 |
运行中断后按租约和 attempt epoch 拒绝陈旧回执,而不是猜测每个外部操作是否执行。后端配置发生变化时需要重新验证;不要改写历史配置摘要。持久任务 completed 只表明后端确认结束,不代替领域验收。
agent.runtime 提供有序 Inbox、Goals、BudgetLimits、Job 和 Subagent;也可独立创建 AgentRuntime(session_store=...)。以下是用于计划工作的一段本地示例,不会调用模型或启动 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)v1.0.0 的 Runtime Job、Subagent 和持久外部 Job 共享生命周期与 fencing 规则,但仍以各自的 Session 事件或 ControlStore 为记录来源。异步任务用 runtime.jobs,子 Agent 通过 runtime.subagents.register(..., persistent=True) 注册,再用 subagents.run(..., idempotency_key=..., lease_seconds=...)。重启后先打开同一 Session,再由应用 bind() 受信 Python 实例;不会反序列化或盲目重放 callable。协作取消的同步线程可能尚未退出;宿主确认后用 Job 核对接口处理。
python example/16.jobs_and_history.py该离线例子执行一个子代理 Job,备份关停后的历史,由新 Runtime 读取恢复副本并重新绑定实例,复用相同幂等键时不重复运行。API 细节见 持久执行契约 和 Job 与历史恢复。部署隔离、冻结旧版本演练和回退见 部署与验收。
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