Runtime

The runtime determines how an agent’s inner loop runs — how each turn calls the model, interprets intent, and invokes tools. The default runtime is built on Google ADK’s execution flow and works out of the box; you can also switch the execution backend or inject shared processing logic into the flow, without changing the agent itself.

Default runtime

The ADK runtime is the default and needs no extra configuration:

from veadk import Agent

agent = Agent(name="assistant")  # uses the ADK runtime by default

Switch the execution backend

Use runtime to select the inner-loop execution backend:

agent = Agent(name="assistant", runtime="codex")

Value	Description
`adk` (default)	Google ADK’s built-in execution flow; suitable for most cases.
`codex`	Runs the inner loop through the Codex SDK and bridges function tools, MCP tools, and skills.
`piagent`	Runs the inner loop through PiAgent RPC and bridges function tools, MCP tools, and skills. Added in 1.0.5.

Use the Codex runtime

The Codex runtime requires the optional codex dependency group, which is not installed with VeADK by default. Install the required dependencies before using it:

pip install "veadk-python[codex]"

The codex extra includes the OpenAI Codex SDK and the Codex CLI binary. The model name, API endpoint, and API key still come from the agent’s model configuration:

from veadk import Agent

agent = Agent(
    name="coding_assistant",
    runtime="codex",
    model_name="doubao-seed-2-1-pro-260628",
)

Tools and skills use the standard Agent configuration; the Codex runtime does not require a separate registration path:

function tools in tools are exposed as callable tools to the model;
an MCPToolset in tools supports tool discovery and invocation;
skills loaded through SkillToolset or VeADK’s legacy entry are made available through the Codex skill mechanism.

Codex security configuration

The Codex runtime defaults to least-privilege settings suited to a multi-tenant service: each invocation uses a session-isolated workspace, the workspace_write sandbox, no network access, and denial of escalated operations. Broader access must be enabled explicitly. Pass a CodexRuntimeConfig through the Agent codex_runtime_config parameter:

agent.py

from veadk import Agent
from veadk.runtime.codex import CodexRuntimeConfig

agent = Agent(
    name="assistant",
    runtime="codex",
    codex_runtime_config=CodexRuntimeConfig(
        sandbox="workspace_write",
        approval_mode="auto_review",
        network_access=True,
        # Set this explicitly to work inside an existing project.
        workspace_root="/workspace/codex",
    ),
)

The full set of CodexRuntimeConfig parameters:

Parameter	Type	Default	Description
`approval_mode`	`"deny_all"` \| `"auto_review"`	`"deny_all"`	Review policy for escalated operations. `deny_all` rejects every escalation request; `auto_review` lets the model’s self-review decide whether to run.
`sandbox`	`"read_only"` \| `"workspace_write"` \| `"full_access"`	`"workspace_write"`	Sandbox level. `read_only` only reads the workspace; `workspace_write` reads and writes inside the workspace; `full_access` grants full host access.
`network_access`	`bool`	`False`	Whether network access is allowed, effective only under the `workspace_write` sandbox.
`workspace_root`	`str` \| `None`	`None`	Workspace root directory. When unset, a session-isolated temporary directory is used.
`reuse_workspace`	`bool`	`False`	Whether to reuse the same workspace directory across invocations, effective only when `workspace_root` is set.
`reasoning_effort`	`"minimal"` \| `"low"` \| `"medium"` \| `"high"` \| `"xhigh"`	`"medium"`	Reasoning effort level.
`personality`	`"none"` \| `"friendly"` \| `"pragmatic"`	`"pragmatic"`	Reply personality.
`max_tool_iterations`	`int`	`8`	Maximum tool-call iterations per turn, range 1–64.
`tool_timeout_seconds`	`float` \| `None`	`120.0`	Timeout in seconds for a single tool call.

The following environment variables override the corresponding CodexRuntimeConfig field without changing code, and take precedence over codex_runtime_config:

Environment variable	Type	Default	Description
`VEADK_CODEX_SANDBOX`	`str`	—	Overrides `sandbox`.
`VEADK_CODEX_APPROVAL_MODE`	`str`	—	Overrides `approval_mode`.
`VEADK_CODEX_WORKSPACE_ROOT`	`str`	—	Overrides `workspace_root`.
`VEADK_CODEX_NETWORK_ACCESS`	`str`	—	Overrides `network_access`; accepts `1`, `true`, `yes`, `on` (case-insensitive) as enabled.

sandbox="full_access" and reuse_workspace=True relax filesystem isolation between invocations and should only be enabled in trusted environments. In production, use a least-privilege isolated container and restrict the credentials, files, and network destinations it can access.

Codex observability

Codex-native lifecycle notifications and ADK Function/MCP tool calls are converted into standard ADK Events, so tool calls, results, state changes, confirmations, and authentication surface in Session, Trace, and the UI. Runtime logs use stable codex_* event names and attribution fields such as invocation_id, call_id, tool, status, and duration_ms. Tool arguments, tool results, API tokens, credentials, and backend addresses are not logged. Token usage is exposed through codex_event_type=token_usage events and the corresponding log entry.

Configure transient-error retries

When the Codex runtime calls the model backend, it retries transient failures such as rate limits, server errors, overloads, and timeouts. It retries at most twice by default. Use these environment variables to change the behavior:

Environment variable	Type	Default	Description
`CODEX_SHIM_NUM_RETRIES`	`int`	`2`	Maximum retries for transient failures. Set to `0` to disable retries.
`CODEX_SHIM_TIMEOUT`	`float`	`0`	Timeout in seconds for one model-backend call. `0` uses the underlying client’s default timeout.

Use PiAgent

from veadk import Agent

agent = Agent(
    name="coding_assistant",
    runtime="piagent",
    model_name="doubao-seed-2-1-pro-260628",
)

The VeADK Python package does not vendor the PiAgent binary. The runtime checks the following locations in order:

the executable referenced by PIAGENT_BINARY;
the managed cache under PIAGENT_INSTALL_DIR, which defaults to ~/.cache/veadk/piagent;
if the cache is missing, a downloaded and verified PiAgent release.

Environment variable	Default	Description
`PIAGENT_BINARY`	—	Path to an installed PiAgent executable. Recommended for production.
`PIAGENT_INSTALL_DIR`	`~/.cache/veadk/piagent`	Managed download and cache directory.
`PIAGENT_AGENT_DIR`	A temporary directory per run	Isolated PiAgent configuration and session directory; it cannot point to the user’s real `~/.pi/agent`.
`PIAGENT_WORKDIR`	Current directory	PiAgent working directory.
`PIAGENT_TIMEOUT_SECONDS`	`600`	Per-run timeout in seconds.
`PIAGENT_TOOL_ALLOWLIST`	Empty	Comma-separated built-in tools that may run.
`PIAGENT_EXCLUDE_TOOLS`	Empty	Comma-separated tools that may not run.

Automatic installation requires access to the PiAgent release host. In offline or restricted networks, install the binary in advance and set PIAGENT_BINARY.

Request processing

Without touching business logic, you can inject shared cross-cutting processing into each run. Pass a processor to run_processor, for example to enforce login via identity authentication:

from veadk import Agent
from veadk.integrations.ve_identity import AuthRequestProcessor

agent = Agent(name="assistant", run_processor=AuthRequestProcessor())

When unset, the default processor is used and behavior is unchanged. VeADK ships AuthRequestProcessor as a ready-made implementation for identity authentication.

Custom processors

Every processor subclasses the abstract base BaseRunProcessor and implements its process_run(runner, message) method. That method returns a decorator wrapping the run’s event stream, letting you:

inject logic before and after the whole run (auth, logging, monitoring);
intercept, rewrite, or inject events produced during the run;
build control logic such as retries on top of that.

from veadk.processors.base_run_processor import BaseRunProcessor

class LoggingProcessor(BaseRunProcessor):
    def process_run(self, runner, message, **kwargs):
        def decorator(event_generator):
            async def wrapper():
                # Before: record start, validate, ...
                async for event in event_generator():
                    yield event  # intercept or rewrite events here
                # After: summarize, report, ...
            return wrapper
        return decorator

Overview

Get started

Core components

Observability

Extensions

Frontend

Security

Deployment

Default runtime

Switch the execution backend

Use the Codex runtime

Codex security configuration

Codex observability

Configure transient-error retries

Use PiAgent

Request processing

Custom processors

​Default runtime

​Switch the execution backend

​Use the Codex runtime

​Codex security configuration

​Codex observability

​Configure transient-error retries

​Use PiAgent

​Request processing

​Custom processors

Default runtime

Switch the execution backend

Use the Codex runtime

Codex security configuration

Codex observability

Configure transient-error retries

Use PiAgent

Request processing

Custom processors