| 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.
