Data Models

agora_workbench.code_execution.code_execution_models

Data models for code execution configuration and results.

This module contains Pydantic models used by the code execution server: - ToolCallRecord: Structured record of a tool call - CodeExecutionResult: Output from code execution - ServerConfig: Configuration for a CodeExecutionServer instance

AssetSpec

Bases: BaseModel

Specification for a large artifact (model weights, data files) to provision.

Assets are fetched into the environment cache directory at server startup (when auto_provision=True on the parent ServerConfig) and skipped if already present with a matching checksum.

Supported source URI schemes: - https:// — streaming HTTP download with retry - abfss:// or https://*.blob.core.windows.net/ — Azure Blob Storage - file:///path or bare path — local copy (useful with Docker bind mounts)

Accessing assets from tool implementations

The MCP_ASSET_CACHE_DIR environment variable is set on every kernel process, pointing to the cache directory. Tool code can locate assets via::

import os
from pathlib import Path

cache = Path(os.environ["MCP_ASSET_CACHE_DIR"])
weights = cache / "models/weights.safetensors"

SidecarConfig

Bases: BaseModel

Specification for a long-lived helper process co-located with the server.

A sidecar is a background process the CodeExecutionServer launches at startup and shuts down on exit. It exists to host expensive, process-global state — most commonly a heavy model that would otherwise be reloaded (and its memory multiplied) inside every isolated kernel session. The model is loaded once in the sidecar; kernel-side tool code reaches it over loopback HTTP, so each execute_{name}_code session stays cheap.

By default the sidecar runs with the server's own kernel environment Python interpreter (ServerConfig.get_python_path()), so it can import the same heavy dependencies the tools use without a second environment. Set use_env_python=False to launch an arbitrary executable instead (e.g. a sidecar shipped as a standalone binary or served from another interpreter).

Discovery contract

The resolved base URL (http://{host}:{port}) is exported into the environment under url_env_var on the server process before any kernel is spawned, so every kernel inherits it. Tool code reads it::

import os, httpx
base = os.environ["MYMODEL_SERVICE_URL"]
resp = httpx.post(f"{base}/predict", json={...}, timeout=600)

The sidecar process is told where to bind via the SIDECAR_HOST and SIDECAR_PORT environment variables (in addition to any env overrides), so a single entrypoint can honor the configured address.

base_url()

The base URL kernels use to reach the sidecar.

Source code in src/agora_workbench/code_execution/code_execution_models.py

def base_url(self) -> str:
    """The base URL kernels use to reach the sidecar."""
    return f"http://{self.host}:{self.port}"

health_url()

The URL polled to determine readiness.

Source code in src/agora_workbench/code_execution/code_execution_models.py

def health_url(self) -> str:
    """The URL polled to determine readiness."""
    return f"{self.base_url()}{self.health_path if self.health_path.startswith('/') else '/' + self.health_path}"

ToolCallRecord

Bases: BaseModel

Structured record of a tool call made during code execution.

Captured by instrumented proxy wrappers injected into the kernel. Each record represents one tool invocation with its arguments, result, timing, and success/failure status.

CodeExecutionResult

Bases: BaseModel

Result of code execution with stdout, stderr, and metadata.

ServerConfig

Bases: BaseModel

Configuration for a CodeExecutionServer instance.

Fields are organized into logical groups:

Identity — server and tool naming/description: name, description, server_description, entra_client_id, entra_tenant_id

Environment — Python environment build settings: type, dependency_file, auto_build, build_dir, additional_commands

Assets — large artifact provisioning: assets, auto_provision

Execution — code execution policy: max_timeout, default_timeout, output_truncation_threshold, parallel_max_concurrency

Features — optional server capabilities: tool_search_backend, peer_registry

For fields that also have an environment variable counterpart (e.g., output_truncation_threshold / CODE_OUTPUT_TRUNCATION_THRESHOLD), the ServerConfig value takes precedence when set. The env var serves as a deployment-wide default.

get_build_dir()

Get the directory where environment will be built.

Source code in src/agora_workbench/code_execution/code_execution_models.py

def get_build_dir(self) -> Path:
    """Get the directory where environment will be built."""
    if self.build_dir:
        return self.build_dir
    return Path.home() / ".cache" / "mcp-envs" / self.name / self.type

get_cache_dir()

Get the root cache directory for this environment (parent of build_dir).

Asset destinations are resolved relative to this directory.

Source code in src/agora_workbench/code_execution/code_execution_models.py

def get_cache_dir(self) -> Path:
    """Get the root cache directory for this environment (parent of build_dir).

    Asset destinations are resolved relative to this directory.
    """
    if self.build_dir:
        return self.build_dir.parent
    return Path.home() / ".cache" / "mcp-envs" / self.name

get_python_path()

Get the path to the Python executable.

Source code in src/agora_workbench/code_execution/code_execution_models.py

def get_python_path(self) -> Path:
    """Get the path to the Python executable."""
    build_dir = self.get_build_dir()

    if self.type in ["conda", "uv", "pip"]:
        return build_dir / "bin" / "python"
    else:
        raise ValueError(f"Unknown environment type: {self.type}")