API & CLI reference

This is a curated reference for the common Local path, checked against SDK 0.1.0a1. It is not an exhaustive generated API listing. Start with the application tutorial for a complete program; use models and tools for provider setup. Temporal and optional backends have separate contracts in operations.

Definitions and runnable entries

Import these names from ralf_agent.

Keep declarations named spec and runnable facades named agent. Changing the submitted declaration, such as output_schema, changes the request digest. Tool and Provider registration identities are fixed in the accepted release; use changed components for new tasks and retain original components to recover old Runs.

Runtime.from_profile(profile, db_path, *, builder=None, scope=None, ...) owns the built assembly. await Runtime.afrom_profile(...) supports asynchronous factories. Runtime assembly details (Chinese) describe component registration; the English Local Agent contract covers hosting and shutdown.

Submit, run and wait

All facade calls below are awaited. command_id is required for submitting business intent.

WaitResult contains ref, snapshot, wait_reason and observed_at. Reasons are state_reached, control_available and observation_timeout. Always check observed.snapshot.state before using observed.snapshot.result. A pause or observation timeout is not business success. terminal_only=True waits through pauses and can need a finite observation timeout.

Cancelling an awaited wait does not cancel business execution. Use await run.cancel(command_id=...) for an explicit cancellation decision; cancellation does not roll back remote effects.

The raw engine has different return types and driving semantics:

# Inside an async function; engine and spec are already assembled.
handle = engine.submit(spec, "Check INC-001", command_id="request-001", budget=32)
snapshot = await engine.drive(handle.run_id)
print(snapshot.state, snapshot.result)

engine.submit(...) is synchronous and returns RunHandle(run_id, receipt) without starting execution. await engine.drive(...) returns RunSnapshot at completion or a pause. Do not interchange RunHandle, AgentRun and WaitResult. Stateless facade submission rejects shared session_id and queue=True; use an explicit Session.

Durable Sessions

A Session retains one unfinished Turn, including approval, input and unknown effects. A terminal snapshot alone does not establish that the lane is idle. Answer an old question on its original Run, then confirm the Session is idle before a new Turn. See Sessions and memory, user input and the English Session contract.

Pending work and controls

await run.pending() returns original pending evidence, including nested owners. Each item includes ref; attach that owner with runtime.attach(RunRef.from_dict(item["ref"])). Inspect kind before choosing a control. An auxiliary item may describe a context/memory/save obligation; it is not an approval request.

For approvals use the item’s action_id and digest; for input use pending_id and target_digest. Hosted facade controls wake the original root; an applied input reply continues its original Run. Raw engine.approve / engine.send_input and CLI controls only record the decision: explicitly drive/resume afterward. See the complete input reply sequence and approval/recovery path.

Identity, receipts and reconnect

Use distinct, stable control IDs per Run/action/digest/decision. Repeating a decision retries that same ID. A fixed ID such as approve-1 cannot approve every later action. Scope(workspace="default", principal="local-owner") comes from the trusted host; it is not enterprise authentication.

After closing, reconstruct the original engine/components/database and Runtime, then runtime.attach(saved_ref) (or await runtime.aattach(saved_ref)). Attach/status/events are observations; explicitly await run.resume() or apply a required control to continue. A RunRef contains no client or credentials and is not an execution authority or a database backup.

Ownership and errors

Use async with for Agent/Runtime. Standalone Agent closes its created Runtime. Closing a borrowed Agent only detaches it. A Runtime drains its hosted work and closes the engine only with owned=True; LocalEngine owns its Store/Coordinator. Directly injected Providers, clients and other borrowed components remain their owner’s responsibility. Profile builders can explicitly own resources.

Default close policy is drain, with a 30-second close timeout. aclose() returns CloseReport(state, parked, owned). CloseIncomplete retains the report and shutdown responsibility: keep resources and retry aclose(). close_policy="cancel" requests cancellation and waits for actual managed work to settle; neither policy establishes rollback of remote writes.

Typed exceptions derive from RalfError and expose .code. CLI errors print a structured error (JSON by default) to stderr and return exit code 2. Business outcome is still in the snapshot; a successful CLI invocation alone does not prove task success.

CLI lookup and control

Global options precede the subcommand: --db defaults to .ralf/runs.sqlite, --format to json; --format text gives a readable view. --config runtime.toml and --factory module:callable are mutually exclusive trusted assembly choices. Keep the same database and original assembly for mutation/recovery commands.

ralf --version
ralf --help
ralf run --help
ralf send-input --help

status/inspect/events read the local SQLite authority without importing a factory. They do not provide generic Temporal inspection. For an end-to-end CLI exercise use user input or quickstart. For regression and protocol commands use testing and evaluation. The broader repository API index (Chinese) is optional deeper reading.