Code Executor Questions

[g-reedbauer]

Question on Code Execution tool(s):

• When the code execution happens, what exactly is the architecture there? some container that is isolated to run the code?
• What is the timeout of the code if it is a long running process?
• Is there any way of feeding the code execution flat files, without having those files be read in by the LLM (and hitting the context window / token limit)?
• Does the code execution "sandbox" impersonate the agent and have the same permissions? I.e. can i have it access things like a cloud storage bucket if the agent has access?
• With the GKE and the VertexAI code executor, does any of the above change? What would be the primary use cases for them?

[adk-bot]

Response from ADK Answering Agent (experimental, answer may be inaccurate)

TLDR: ADK's code executors run your code in isolated, sandboxed environments. The AgentEngineCodeExecutor and VertexAiCodeExecutor are stateful and ideal for multi-step data analysis, while the GkeCodeExecutor is stateless, using ephemeral, high-security pods for each execution, making it suitable for production on GKE. Timeouts are configurable, and you can provide files directly to the execution environment to avoid LLM token limits. The sandboxes do not inherit the agent's cloud permissions.

---

Hello! Here are the answers to your questions about ADK's code execution tools.

1. Code Execution Architecture

The code execution happens in a secure, isolated sandbox. The specific architecture depends on the executor you are using:

• AgentEngineCodeExecutor / VertexAiCodeExecutor: These use a managed sandbox service on Google Cloud. The environment is stateful, meaning the memory state (variables, functions, and files) persists across multiple tool calls within the same session. This is useful for complex, multi-step tasks. [1]
• GkeCodeExecutor: This executor leverages the GKE Sandbox environment with gVisor for strong, kernel-level isolation. For each code execution request, it creates a new, ephemeral Kubernetes Job. This means the environment is completely stateless and no information is carried over from one execution to the next, which is a key security feature. [2]

2. Timeout

Yes, there are timeouts for code execution:

• GkeCodeExecutor: Has a configurable timeout_seconds parameter, which defaults to 300 seconds (5 minutes). You can adjust this when you configure the tool. [5]
• AgentEngineCodeExecutor: This executor has a Time-to-Live (TTL) feature that can be specified upon the creation of the sandbox, which determines its lifespan. [1]

3. Feeding Files to the Executor

Yes, you can feed files to the code execution environment without passing their content through the LLM, which avoids issues with context windows and token limits.

• The AgentEngineCodeExecutor supports uploading data files (up to 100MB) for analysis. [1]
• The VertexAiCodeExecutor also has a mechanism to add files to the execution context. Samples show how to provide local files to the execution environment. [4] This allows the LLM to reference the file by its name while the executor accesses the full file contents in its sandboxed environment.

4. Permissions and Impersonation

The code execution sandbox does not impersonate the agent or automatically inherit its permissions. The sandboxes are designed with a "no network" default to prevent data exfiltration and limit access to other cloud resources. [3]

The permissions required for the agent's service account are for managing the execution environment itself (e.g., creating the sandbox or the GKE Job), not for the code running inside the sandbox to access things like Cloud Storage buckets. [1, 2] If the code within the sandbox needs to access other Google Cloud services, you would need to configure separate, explicit authentication for that tool.

5. GkeCodeExecutor vs. VertexAiCodeExecutor

The core differences lie in their state management, security model, and intended use case:

• GkeCodeExecutor:
  • Use Case: Best for production environments running on GKE where security and isolation are paramount.
  • Key Features: It is stateless. Each execution runs in a brand-new, ephemeral, and highly isolated gVisor sandbox. This provides maximum security by preventing any state from persisting. It also provides more control over the execution resources (CPU, memory). [2]
• AgentEngineCodeExecutor / VertexAiCodeExecutor:
  • Use Case: Ideal for interactive, multi-step agentic workflows like data analysis, where a persistent state is beneficial.
  • Key Features: It is stateful. The sandbox persists throughout a session, allowing code to build upon previous executions (e.g., reusing variables or loaded data). It is a fully managed service designed for efficiency and low latency. [1]

---

Footnotes:
[1] Agent Engine Code Executor Documentation
[2] GKE Code Executor Source Code
[3] ADK Safety Documentation
[4] Vertex Code Execution README
[5] Built-in Tools Documentation