Connect agent tool calls to Polyaxon execution

An agent tool call is a request to do work, not proof that the work is authorized. Between a model response and a running process, your application needs to validate arguments, select an execution environment, and define how failure is reported.

Polyaxon's sandbox client supplies the execution interface. A trusted controller supplies the policy around it.

Define a small tool contract

Start with a named operation such as “calculate dataset summary” instead of exposing an unrestricted terminal to every agent. Its arguments can be a permitted dataset identifier and a small set of summary options.

The controller resolves that identifier to an approved input bundle. It chooses the Polyaxon project and run from authenticated session state, not from a model-supplied UUID. It also enforces request size, deadline, and tenant ownership.

If the product genuinely requires generated Python, treat the program as untrusted input. Limit available credentials, mounts, resources, and network destinations through the execution environment and cluster policy. Argument validation is not a substitute for that boundary.

Execute through an established service

The following controller-side example assumes a configured Polyaxon client, an authorized running sandbox service, and an application-owned analysis.py already uploaded to its workspace. Replace the run UUID with the service assigned to this session.

from polyaxon.client import SandboxClient

with SandboxClient(
    project="quick-start",
    run_uuid="REPLACE_WITH_AUTHORIZED_RUN_UUID",
) as sandbox:
    sandbox.ping()
    result = sandbox.process.exec(
        command=["python", "/workspace/analysis.py"],
        workdir="/workspace",
        timeout_ms=30_000,
    )

    receipt = {
        "exit_code": result.exit_code,
        "timed_out": result.timed_out,
        "duration_ms": result.duration_ms,
        "stdout_truncated": result.stdout_truncated,
        "stderr_truncated": result.stderr_truncated,
    }
    print(receipt)

A command list avoids an extra shell-parsing layer. It does not make the Python program safe. The process reference describes the execution result and streaming alternatives.

Do not treat a created run as ready. Follow the sandbox quick start to wait for a running service and check sandbox health before accepting tool requests.

Translate execution into an application result

Check timeout and exit status before interpreting stdout. If output was truncated, do not silently treat it as a complete JSON response. For larger results, write a bounded file and retrieve it through the filesystem interface.

Return a structured application response containing a request identifier, outcome, safe summary, and approved artifact references. Keep raw tracebacks out of model context when they may include credentials or private paths.

Track the tool name, execution run UUID, duration, and evaluator result in the controller's Polyaxon run. This creates a navigable relationship between the agent decision and the work it caused.

Own retries and cleanup

A lost connection can leave the outcome uncertain. Do not automatically repeat an operation that writes to an external system. Use application-level idempotency keys or inspect a durable receipt before retrying.

Closing SandboxClient releases the client connection; it does not stop the service. The session manager must decide when to preserve results and terminate the run. Add an absolute termination timeout as a backstop.

The resulting integration is deliberately simple: the model proposes, the controller authorizes, Polyaxon executes, and the application evaluates the result.