Choose a code execution API for AI workflows
Compare code execution API shapes and implement clear request, result, cancellation, and artifact contracts for Polyaxon agent workflows.
“Run this code” can mean a command in an existing workspace, a new batch job, or a cell in a persistent interpreter. Those interfaces have different state and failure behavior.
Choose the API shape before connecting it to an agent. Polyaxon provides jobs, services, and sandbox process access; your adapter should expose the smallest interface that meets the application's needs.
Match the API to the state model
| API shape | Appropriate use | State to clarify |
|---|---|---|
| Submit a job | Fixed preparation or evaluation | Inputs and durable outputs |
| Execute a command in a service | Interactive file-based work | Workspace lifetime |
| Stream a command | Long output or progress updates | Completion after disconnection |
| Background process | Work that outlives one response | Process handle and cleanup |
| Interpreter session | Repeated cells sharing variables | Kernel lifecycle and reset |
A sandbox command API is not automatically a notebook kernel. Separate Python processes can share files while retaining no common in-memory variables.
Review the process interface and notebook workflow before assuming those semantics are interchangeable.
Define request limits in the adapter
An execution request should include an application request ID, an approved operation or code payload, input references, and a bounded deadline. Resolve the project, assigned service, and credentials from trusted context.
Reject unsupported languages, oversized inputs, forbidden paths, and unauthorized data references before dispatch. For an approved operation, prefer a fixed command with validated arguments to a shell string assembled from model output.
If arbitrary code is required, the adapter's validation does not make it safe. Its effective permissions still depend on the service image, mounts, identity, resources, and cluster controls.
Return a result that explains uncertainty
Polyaxon's command result includes stdout, stderr, exit code, timing, timeout information, and truncation indicators. Preserve the relevant fields in the application receipt.
A useful result distinguishes:
- Rejected before execution.
- Accepted but not yet complete.
- Completed successfully.
- Completed with a process error.
- Deadline reached.
- Outcome uncertain after a transport interruption.
Do not translate every exception into “the code failed.” A client may lose the response after the process already changed external state.
Use file transfer for bounded report files instead of forcing large results through stdout. Validate content and size before passing it into model context.
Separate cancellation from client timeout
A timeout while waiting for a background handle does not necessarily terminate the process. Similarly, closing a stream or client connection should not be treated as proof that the service stopped.
Define who owns cancellation and how completion is reconciled afterward. Use run termination settings as a workload-level backstop, with application-level rules for individual requests.
For operations with side effects, use durable request receipts or idempotency controls. The model should not decide whether an ambiguous write is safe to repeat.
Keep execution evidence portable
Record the operation, image revision, input references, execution run UUID, and result summary with Polyaxon tracking. Persist approved output files through the artifact workflow.
This contract makes future changes easier. You can move a stable analysis from interactive commands to a job without changing how callers interpret authorization, completion, and evidence.