Skip to content

V1 Durable Runtime en

weego edited this page Nov 15, 2026 · 1 revision

Durable Execution, Jobs, and Subagents

简体中文 | 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.

A reconnectable task without a model

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.

State, interactions, and budgets

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.

Session Runtime: Inbox, Goals, Jobs, and Subagents

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.py

The 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.

Clone this wiki locally