Runtime & deployment

Choose an execution backend

Local does not automatically become a distributed scheduler. Temporal does not wrap LocalEngine in an activity. They share concepts without complete parity for sessions, tool nodes or nested combinations. Temporal is explicitly configured within its experimental Alpha scope. Read the Temporal guide and current support status (Chinese) before choosing it.

This website is static and can be hosted on Cloudflare. A Python agent application needs its own Python execution environment or worker. Hosting the website does not run an agent or provide a Temporal service.

Manage components with a profile

After source installation, generate a new offline configuration project:

ralf init my-config-agent --template config
cd my-config-agent
python -m agent_app --input hello --command-id hello-1
python -m agent_app --input pending --command-id pending-1 --submit-only
ralf --config runtime.toml --format text inspect RUN_ID
ralf --config runtime.toml resume RUN_ID

Replace RUN_ID with the second submission’s ID. runtime.toml defines runtime components; agent.toml defines the agent. The template’s offline-echo provider verifies assembly and execution.

A basic profile has the following shape. The template already contains editable, complete configuration:

schema_version = 1
[default]
name = "assistant"
version = "1"

[[profiles]]
name = "assistant"
version = "1"
[profiles.providers.default]
adapter = "offline-echo"
[profiles.providers.default.config]
label = "example"

Configuration selects registered components without executing Python or dynamically importing arbitrary plugins. Relative resource paths resolve from the configuration directory. Across directories, retain the same absolute database and configuration paths and keep the original factory importable. Asynchronously constructed resources use the corresponding async assembly entry point.

Change configuration and recover old tasks

A profile’s name/version identifies configuration that cannot be overwritten. Moving a default affects new tasks; old runs resolve their original profiles. Retain declarations, adapter implementations and data. The catalog does not archive code or migrate databases for you.

The same command ID and request retrieve the original task. Changed input with the same ID conflicts. Use a new command ID for a new task under new configuration. Resolve definition_mismatch by restoring the original version, rather than changing aliases or relaxing defaults.

Allowances, limits and completion checks

Effective agent limits combine the spec, host and selected policy constraints. Pure limit policies perform no I/O and cannot expand permissions. Recovering an existing action does not allocate a new distinct tool-action slot. Limits are pinned with the original task.

Observe, control and shut down

status, events, inspect and attach observe execution. A wait can end at a pause or observation timeout; inspect the snapshot’s actual state. Resume explicitly when needed and submit a separate cancellation command to cancel.

At shutdown, stop new admission, finish or cancel and await your execution tasks, then close owned clients and data connections. Directly injected borrowed components remain their owner’s responsibility. A cancelled Python await does not prove that a tool thread, subprocess or uncertain remote write has finished.

Backups need execution records, selected session/fact/knowledge/artifact stores and business-effect evidence. Copying one idle database file does not establish complete application recovery. See the recovery guide (Chinese) for concrete procedures.

Continue from a local pilot

Validate an offline task, a real tool and approval/recovery first. Add dependencies and services for your chosen models, remote data, MCP or Temporal. From the source repository root, install the Temporal extra with python -m pip install -e '.[temporal]', then provide the service, workers and matching release. This guide starts no services implicitly.

APIs and some combinations remain Alpha. Evaluate deployment using evidence from your actual components and failure scenarios; current qualification is in the implementation status (Chinese). Use approval and recovery to diagnose execution by state.

Verified baseline and support boundaries

This site documents SDK 0.1.0a1 at the published commit shown above, verified on 2026-10-21. The date records these tutorial checks, not a guarantee for every deployment or hosted model.

Use API & CLI reference for signatures, durable user input for pauses, and testing and evaluation before changing providers or deploying. The pinned technical sources describe that snapshot; newer repository development does not change old-run recovery requirements.