Integration guide

English | 简体中文 | Home

Choose the shortest integration path that meets your application's needs.

Before connecting real work, review the integration engineering principles. They cover version identity, supervised lifetime, evidence levels, candidate freezing and safe discovery without moving business policy into the SDK.

Goal	Start with	Working example
Run one managed local task	Managed application API	Managed task
Inspect activity and supervise long-running work	Execution activity and supervision	Parent/child example
Execute a function with persisted state	SDK and public API	Queued work after reopen
Submit a task with replayable identity	Atomic task submission	Complete example in that guide
Execute a script and notify an Agent	Scripts and wakeups, durable inbox	Script callback
Coordinate dependencies	SDK operations	Dependent tasks
Reconcile an interrupted external operation	Recovery	Effect recovery
Resume a failed or cancelled Run in place	Same-Run recovery	Code in the SDK guide
Validate LLM output and request repairs	Output contracts	Follow the application validation flow in that guide
Consume an audit trail	Integration FAQ	Durable audit
Use remote execution	Sandbox runtime, adapters	Follow the service setup in those guides
Inspect SQLite backlog and contention	SQLite operations	Run the contention benchmark on the target host
Activate a restored local snapshot	Local recovery	Local restore drill

Before connecting real work

Use persistent database and log paths. Choose a supported isolation mode and keep matching handler deployments available for queued work. Give each decision a stable identity and retain its original request for replay.

Callbacks should return promptly after durably accepting and deduplicating a notification. Process the inbox separately. Each external write needs its own idempotency or reconciliation scheme. Process execution alone does not restrict file or network access.

Reopen a terminal Run

Call inspect_reopen() before reopening a failed or cancelled Run. It reports unfinished attempts, pending deliveries, active notification leases and an existing continuation. reopen_run() checks those facts again before it commits the decision, keeps the same run_id and history, and increments the Run's generation.

After the reopen, pass expected_generation when changing the Run or submitting more work. New attempts need fresh execution and idempotency identities, and their handler binding must match the target deployment. A cancelled Run also needs an authorization record. Successful Runs and Runs with a continuation cannot be reopened.

Recovery progress is durable. The host can finish a prepared or committed record after a restart. Current Orchestrator stores use schema 4. Older stores need the preparation and copy-upgrade steps supported by the storage guide; never open an incompatible store as a current writer.

Check storage and upgrades before reusing old stores; 0.7 does not automatically migrate old Orchestrator databases. Review Windows status and Linux cleanup evidence for deployment limits.

For an Agent implementing the integration, use the English DocsforAgents entry point.