Execution helpers

The Playground supports individual calls, argument drafts and ordered batches. Personal organizations always act as their owner; business projects select the authorized end user and, when needed, an eligible group.

Argument drafts

Choose a pinned tool and describe its inputs. Arc0 sends only your request and that tool’s schema to the configured OpenAI model, validates the result and returns one of:

• ready: review and edit the arguments before execution.
• needs_input: supply the listed missing inputs.
• refused: the generation request was declined.
• invalid: the output did not satisfy the tool schema.

Generating or applying a draft does not execute a tool. The execution path rechecks permissions, version pins and approval policy. Do not put credentials in the natural-language request. The integration requests store: false; this is not a promise of provider-side zero retention.

const draft = await arc0.draftArguments(actionId, {
  actionVersion: version,
  prompt: "Find the order numbered 1234",
});
// Review draft.arguments before making a separate execute call.

Python: arc0.draft_arguments(action_id, action_version=version, prompt="Find order 1234").

Ordered batches

A batch contains at most ten ordered steps. Each step uses the normal execution pipeline; there is no cross-app transaction or rollback of completed work. Reuse the same idempotency key when retrying the same logical batch request.

const batch = await arc0.createExecutionBatch({
  idempotencyKey: "your-stable-batch-key",
  endUserId: "your-end-user-id",
  stopOnError: true,
  steps: [
    { action: firstAction, actionVersion: firstVersion, arguments: firstArguments },
    { action: secondAction, actionVersion: secondVersion, arguments: secondArguments },
  ],
});
const progress = await arc0.getExecutionBatch(batch.id);

Use resumeExecutionBatch after resolving a waiting step and cancelExecutionBatch to stop remaining work. Cancellation does not undo dispatched operations. Child execution IDs link progress to normal receipts and approvals. The dashboard can reopen a batch using its ID.

Batches with local functions use runExecutionBatch in a client with the required handlers registered. This selects client mode and handles returned local execution claims. The helper returns waiting approvals or unresolved work to the caller; it does not grant approval or poll forever. Dashboard/server-mode batches reject an SDK-local step before starting any child, with HTTP 409 local_runtime_required. Use client mode for those function bodies.

Python provides create_execution_batch, get_execution_batch, resume_execution_batch, cancel_execution_batch and run_execution_batch. Local function registration and provenance are described in Custom apps.