Skip to content

V1 Durable Runtime

weego edited this page Nov 15, 2026 · 2 revisions

持久执行、Jobs 与 Subagents

简体中文 | 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 只表明后端确认结束,不代替领域验收。

Session Runtime:Inbox、Goals、Job、Subagent

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 与历史恢复。部署隔离、冻结旧版本演练和回退见 部署与验收。

Clone this wiki locally