Skip to main content

DIAL Code Interpreter configuration

This reference covers Code Interpreter 0.2.0, Core 0.49.4, and Quick Apps Backend 0.13.2. It is for platform engineers enabling Python calculations for agents. It assumes the interpreter dependencies are available.

Where each setting lives​

PlaceWhat it controlsReference
Interpreter container environmentUpload size, download buffer, file directory, logging, and session header checkService environment
Core static settingsController endpoint, session image, deployment mode, expiry, and user permissionsCore session settings
App Controller settingsKubernetes namespaces, container resources, session probes, and startup waitController configuration
Quick Apps Backend environmentAPI base URL, credentials, and client retriesQuick Apps connection
Quick App manifest or editorWhether the Python tool is offered to the orchestratorEnable calculations in a Quick App

Service environment​

The first five variables are read by env.py. Values must be valid at process startup.

VariableDefaultDescription
UPLOAD_MAX_SIZE536870912Maximum uploaded file size, in bytes: 512 MiB. An oversized upload returns HTTP 413 and removes the partially written file.
DOWNLOAD_CHUNK_SIZE8192Buffer size used when streaming a file download, in bytes: 8 KiB.
MOUNT_FOLDERProcess working directory; /mnt/data in the imageBase directory used by upload, download, and file listing operations. Resolved to an absolute path at startup.
LOG_LEVELINFOInterpreter logger level, converted to uppercase.
SESSION_ID—When set, operation requests must supply the same value in x-dial-session-id. Core supplies the deployment ID in its pod-backed session mode.
TIMEOUT_KEEP_ALIVE60Uvicorn HTTP keep-alive timeout, in seconds. Read by the image's startup command, not by env.py.

The image also sets PYTHONDONTWRITEBYTECODE=1 and PYDEVD_DISABLE_FILE_VALIDATION=1; see Dockerfile. The HTTP API listens on 0.0.0.0:8080 in the published image.

SESSION_ID is optional at the service level. When it is set, missing headers return HTTP 400 and mismatches return HTTP 503. /health does not require the header. See session checking.

Kernel timing and state​

The interpreter constructs its Python kernel with a 10-second startup timeout and a 60-second execution timeout. These are constructor defaults, not environment variables in this release. Code Interpreter 0.2.0 exposes no environment setting to increase them.

Successful calls reuse the kernel and its variables. Execution exceptions restart it, including a timeout while waiting for kernel messages. A normal Python error is returned as status: FAILURE; it does not take the exception/restart path merely because Python raised an error. See Interpreter.

HTTP keep-alive, kernel execution timeout, client timeout, and Core's idle session lifetime are independent settings.

Core session settings​

The applications and codeInterpreter objects are static Core settings; changes require a Core restart.

SettingDefaultDescription
applications.controllerEndpoint—App Controller URL. Interpreter operations require an active controller connection.
applications.controllerTimeout240000Controller operation timeout, in milliseconds.
applications.controllerConnectTimeout10000Controller connection timeout, in milliseconds.
codeInterpreter.sessionImage—Interpreter image used when starting a session. Without it, interpreter operations are unavailable.
codeInterpreter.sessionProxyUrl—Unset: sessions use Knative deployments. Set: sessions use pods and requests pass through this proxy URL.
codeInterpreter.sessionTtl600000Idle lifetime after the last session use, in milliseconds: 10 minutes.
codeInterpreter.checkPeriod10000Expiration scan interval, in milliseconds.
codeInterpreter.checkSize256Maximum expired-session candidates processed per scan.

Sources: ApplicationOperatorService and CodeInterpreterService. The Quick Apps tool description mentions 15 minutes; the actual idle lifetime follows Core's configured sessionTtl.

Core checks interpreter execution permission through the same access.createCodeAppRoles control used for Code App creation. The check passes when the setting is unset or the request carries a per-request key. Quick Apps calls with the per-request key it receives from Core, so this setting does not restrict its calculation tool. Session resources and DIAL file transfers are scoped through the caller's context. See Core access settings, CodeInterpreterController, and AccessService.

Example settings fragment for Knative-backed sessions:

{
  "applications": {
    "controllerEndpoint": "http://dial-app-controller:8080"
  },
  "codeInterpreter": {
    "sessionImage": "epam/ai-dial-code-interpreter:0.2.0",
    "sessionTtl": 600000,
    "checkPeriod": 10000,
    "checkSize": 256
  }
}

The Knative infrastructure must exist for this example. Pod-backed mode additionally needs a compatible session proxy and its sessionProxyUrl; setting the URL alone does not deploy that proxy.

Quick Apps connection​

VariableDefaultDescription
PY_INTERPRETER_URLDIAL_URL when unset or emptyBase URL of the Core-compatible interpreter session API. The client appends /v1/ops/code_interpreter.
PY_INTERPRETER_LOCAL_RUNfalsefalse uses the incoming DIAL request key. true requires and selects PY_INTERPRETER_API_KEY. It does not change the client API paths to the raw container endpoints.
PY_INTERPRETER_API_KEY—Explicit API key required when PY_INTERPRETER_LOCAL_RUN=true.
PY_INTERPRETER_DEFAULT_SESSION_ID—Fallback session ID when the conversation does not already provide one.
PY_INTERPRETER_CLIENT_MAX_RETRIES3Client retry setting.

The normal setup needs no interpreter-specific URL override: the Quick Apps Backend uses DIAL_URL and the incoming request key. Sources: client construction and API paths.

Client timeouts follow the Quick App's tool_defaults.timeout_seconds, or the backend's DEFAULT_TOOL_TIMEOUT_SECONDS default of 300.0. The deprecated PY_INTERPRETER_CLIENT_TIMEOUT overrides that backend default only when explicitly set and no app-level timeout exists. Increasing a client timeout does not increase the kernel's 60-second execution timeout. See Quick Apps Backend configuration.

Enable calculations in a Quick App​

The editor's Code Interpreter toggle adds the Python interpreter tool. The equivalent tool_sets fragment in the application's manifest is:

{
  "tool_sets": [
    {"type": "predefined", "template_name": "py_interpreter"}
  ]
}

This fragment is added to an existing Quick App configuration with a tool-capable orchestrator. It references the shipped predefined Toolset. The user-facing toggle is documented in Build a Quick App.

After deployment, a prompt such as “Use Python to calculate the mean of 12, 18, and 24” exercises session creation and execution. A Python execution stage and an answer containing 18 provide a functional check. A file-analysis check additionally exercises the attachment transfer path.

Troubleshooting​

SymptomWhat to check
Core reports interpreter unavailable (503)sessionImage, controllerEndpoint, controller reachability, and workload startup.
Execution is forbidden (403)The caller's roles and Core's access.createCodeAppRoles setting. Requests with a per-request key skip the role check.
Quick Apps gets 404 for interpreter operationsPY_INTERPRETER_URL must serve Core-style /v1/ops/code_interpreter/* paths, not only raw /execute_code. A previously used session may also have expired.
Execution returns FAILURE after a timeoutThe kernel execution timeout is 60 seconds; changing HTTP keep-alive or Core session TTL does not extend it.
Variables disappear between requestsA new session, Core idle expiry, explicit close, or a kernel restart after an execution exception.
Session header is missing or mismatchedCore's session deployment ID, proxy routing, and the container's SESSION_ID.
Upload fails with 413The interpreter's UPLOAD_MAX_SIZE and any limits on the preceding proxy path.

Further reading​