Run a process through the SDK

Start with context

SDK beta.3 adds the current read_process_operations, execute_process_operation and recover_process_operation request contracts. Beta.2 supports the read-only walkthrough but does not include these three operations. Use the SDK quickstart first to read the permitted published model and stages.

Your application owns the conversation and chooses the operation from the user’s request. These tools use Neuron’s existing execution gateway without calling its hosted process planner. Older processes.guide and processes.execute helpers can be unavailable in external-reasoning mode; never silently substitute them.

Authorize execution separately

Creating a run requires toolkits:execute plus the separately selected Operating model and current workspace rights. The toolkits:read scope remains necessary for definitions and saved state. Request only the required scopes, have the user approve the selected model, and inspect availableTools() before proceeding.

The packaged browser walkthrough stays read-only. Do not expect its consent to authorize execution. A run can have connected capabilities: calling it a test does not make those capabilities harmless. Use a disposable synthetic workspace and a fictional adapter for acceptance.

Create an isolated run

Use a unique fictional case and a stable start key. Read the saved run before choosing another operation. Reusing the same key with the same request retrieves the original run instead of creating another one. The client below is your application’s authenticated SDK client after explicit execution consent.

const run = await client.processes.start({
  workspace, process_id: processId, case_id: fictionalCaseId,
  idempotency_key: startKey, message: 'Run this isolated acceptance case only.',
});
const current = await client.processes.read({workspace, run_id: run.id});
const contracts = await client.call('read_process_operations', {
  workspace, run_id: run.id,
});

Read the whole operation contract

Choose an operation actually returned in contracts.operations. Its contract supplies the operation ID/revision and business-input schema; its binding supplies the capability ID. Keep the current release fingerprint and run revision. Do not invent IDs or use descriptor metadata as permission.

A large response can contain ordered operation_json segments instead of the operations array. Follow next_context_offset with the initial expected_fingerprint, concatenate all segments and parse before choosing. The envelope fingerprint pins the segmented payload; the parsed result’s fingerprint is the release fingerprint used by the execution command. These are distinct proofs.

Execute only the requested operation

The example below assumes you have read a complete direct or assembled contract, selected a binding from it, and collected businessArguments according to its input schema. Use a stable toolCallId and operationKey for that exact request. Do not supply policy assessments, an actor override or fabricated observations.

const receipt = await client.call('execute_process_operation', {
  workspace, run_id: run.id,
  expected_revision: current.revision,
  idempotency_key: operationKey,
  command: {
    operation_ref: {id: binding.contract.id, revision: binding.contract.revision},
    capability_id: binding.capability_id,
    fingerprint: contracts.fingerprint,
    arguments: businessArguments,
    tool_call_id: toolCallId,
  },
});
const saved = await client.processes.read({workspace, run_id: run.id});

Judge the receipt accurately

Check the actual returned status and execution_performed value. A completed operation is not proof the whole process is complete. Missing inputs, confirmation, governance or independent prose-policy assessment can block an effect. Do not report a blocked or uncertain request as a success.

Large receipts can return details_available and read_details. Read the referenced full process-run snapshot before deciding what happened. These new calls return structured JSON; the SDK does not add a high-level whole-process completion or result-assembly helper for them.

Resume and recover

A new authorized SDK connection can reopen the saved run and inspect its history without the old chat transcript. After an uncertain response, retrieve saved state and the exact receipt before considering another operation. Never generate a new request key merely to retry an uncertain effect.

recover_process_operation retrieves the current pending operation receipt by run_id and call_id, with the current expected_revision and a stable recovery idempotency_key. It does not reissue an uncertain source effect or make a pending result successful. A stale revision means refresh and reassess; it is not permission to replace the expected number and blindly repeat the mutation.

What has been tested

The isolated qualification used the current Neuron runtime, actual MCP HTTP transport and OAuth grants, disposable SQLite state and a fictional adapter. It created one run, executed a lookup and one fictional private-draft effect, read durable receipts, and resumed from a fresh SDK connection. Replays caused no duplicate effect; stale revisions, forged authority and read-only run creation were rejected.

This establishes local execution and persistence with no production data changes or provider calls. It does not establish production connector effects, AI decision quality or completion of an entire business workflow.