Vega AI code mode

Vega AI can use run_code to analyze data with Python. It can query VegaDB into a pandas DataFrame, combine results from tools it has already activated, and print a summary. The answer receives only the printed text and the representation of the last expression or returned value.

Code runs in a fresh offline sandbox for each call. It has Python 3.13, pandas, PyArrow, Polars, DuckDB and NumPy. Top-level await and asyncio.gather are supported; tool requests are processed one at a time.

Tools and permissions

The generated vega module contains async functions for the run's active tools. Deferred tools must be activated with tool_search first. Functions accept keyword arguments from each tool's input schema. Stub names are readable lowercase Python identifiers, such as vegadb_query or github_issues_list. The code tool's description lists the active names and required arguments. Use await vega.call(tool_id, **arguments) to call an exact active tool ID. Child failures raise vega.ToolError with the tool's error code and a bounded message.

Every tool request uses the same user permissions, agent grants, policy, data classification and audit as a direct tool call. Reading untrusted or sensitive data in code carries those labels into the run. A later external write can therefore require approval even in auto mode.

Code can invoke READ and DRAFT tools. WRITE and DESTRUCTIVE functions raise vega.ApprovalRequired without executing anything or opening an approval. The error names the function, the tool's display name and its exact ID. Vega AI must call those tools directly to use the normal approval flow. A tool that needs connection selection or reconnection must also be called directly.

Querying VegaDB

import vega

df = await vega.query("SELECT category, amount FROM vegadb.public.sales")
print(df.groupby("category")["amount"].sum())

Queries are read-only and return a pandas DataFrame through Arrow. Code-mode queries return at most 100,000 rows and 64 MiB by default; max_rows can request a smaller result. Ordinary model-facing query calls retain their existing 200-row ceiling.

Decimal columns remain Arrow decimals containing Python Decimal values. df.select_dtypes('number') may omit them. To use floating-point arithmetic, convert explicitly, for example df['amount_aed'] = df['amount_aed'].astype('float64'); keep decimals when exact arithmetic matters.

Limits and lifetime

The code's wall clock starts when the jail starts executing. Sandbox startup has its own bounded readiness budget. If startup times out, the tool explains that the code did not run and can be retried shortly. If the sandbox is unavailable, the tool also returns a retryable error.

Each call defaults to 60 seconds of wall and CPU time, 2 GiB of address space, 256 MiB of temporary files, 64 KiB of source and model-visible output, an 8 KiB stderr tail on failure, and 50 nested tool requests. The run's existing tool budget also applies. Output above its ceiling receives a truncation marker. Python exceptions, memory exhaustion, timeouts and refused tool requests are tool errors; the agent can continue the run.

Nothing written in the sandbox survives the call. Variables, temporary files and installed packages do not carry between calls. Network access, package installation and subprocess creation are unavailable.

Custom agent definitions opt in with "tools": {"code": {"enabled": true}}. Optional limits fields may only lower the defaults: wall_seconds, memory_mib, tmp_mib, source_bytes, output_bytes, stderr_bytes, nested_calls, query_rows and query_bytes.

Code mode is offered only when the workspace's compute policy and runtime provide an enabled VM-isolated Python sandbox, or the definition uses suitable dedicated compute. New Vega AI conversations use the updated built-in definition; existing conversations retain their pinned definition version. Code mode is excluded from Vega AI's inbound MCP tool catalog.