version: "1.0.0" name: async-execution description: > Run long-running or parallel code asynchronously. Activate when code will take more than 30 seconds, when processing many independent inputs, or when the user asks to run something in the background.

Asynchronous Execution

Background Jobs

For code that takes more than ~30 seconds, submit it as a background job:

execute_{server}_code(
    code="result = long_running_computation(...)",
    description="Running expensive simulation",
    background=True,
    timeout=3600
)
# Returns immediately with a job_id

Then poll for completion:

{server}_check_job(job_id="...")
# Returns status: "running", "completed", or "failed"
# When completed, includes stdout, stderr, success, and error (if any)

Rules for background jobs

• The job runs in the same session kernel — variables are accessible after completion.
• Use {server}_inspect_session to check both job status and namespace state.
• Set an appropriate timeout — background jobs still have a maximum execution time.
• Do not submit trivial code as background — only use for genuinely long-running tasks.

Parallel Execution

Run the same code template across multiple independent inputs concurrently:

{server}_parallel_execute(
    code="result = process_item(input_id=input_id, params=params)",
    inputs=[{"input_id": "item_1", "params": {...}}, {"input_id": "item_2", "params": {...}}, ...],
    result_variable="result"
)
# Returns batch_id

Managing batches

{server}_check_batch(batch_id="...")
# Returns aggregate status and available results
 
{server}_cancel_batch(batch_id="...")
# Stops all running jobs and cleans up child sessions

How parallel execution works

• Each input gets its own child session/kernel.
• The code template receives each input dict's keys as local variables.
• The variable named by result_variable is collected from each child session.
• Individual items can fail without blocking others.

When to use parallel execution

• Processing a list of independent inputs with the same logic.
• Tasks where individual items are independent and order does not matter.
• Workloads that benefit from concurrent kernel execution.

When NOT to use parallel execution

• Tasks that depend on shared state across iterations.
• Small loops (< 5 items) — sequential execution in one execute_{server}_code call is simpler and has less overhead.
• Tasks where items must be processed in order.