feat(code_executors): Add GkeCodeExecutor for sandboxed code execution on GKE

contributing/samples/code_execution/gke_sandbox_agent.py

@@ -0,0 +1,49 @@
+# Copyright 2025 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+"""A Python coding agent using the GkeCodeExecutor for secure execution."""
+
+from google.adk.agents import LlmAgent
+from google.adk.code_executors import GkeCodeExecutor
+
+
+def gke_agent_system_instruction():
+  """Returns: The system instruction for the GKE-based coding agent."""
+  return """You are a helpful and capable AI agent that can write and execute Python code to answer questions and perform tasks.
+
+When a user asks a question, follow these steps:
+1.  Analyze the request.
+2.  Write a complete, self-contained Python script to accomplish the task.
+3.  Your code will be executed in a secure, sandboxed environment.
+4.  Return the full and complete output from the code execution, including any text, results, or error messages."""
+
+
+gke_executor = GkeCodeExecutor(
+    # This must match the namespace in your deployment_rbac.yaml where the
+    # agent's ServiceAccount and Role have permissions.
+    namespace="agent-sandbox",
+    # Setting an explicit timeout prevents a stuck job from running forever.
+    timeout_seconds=600,
+)
+
+root_agent = LlmAgent(
+    name="gke_coding_agent",
+    model="gemini-2.0-flash",
+    description=(
+        "A general-purpose agent that executes Python code in a secure GKE"
+        " Sandbox."
+    ),
+    instruction=gke_agent_system_instruction(),
+    code_executor=gke_executor,
+)

contributing/samples/gke_agent_sandbox/deployment_rbac.yaml

@@ -0,0 +1,50 @@
+apiVersion: v1
+kind: Namespace
+metadata:
+  name: agent-sandbox
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: adk-agent-sa
+  namespace: agent-sandbox
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: Role
+metadata:
+  name: adk-agent-role
+  namespace: agent-sandbox
+rules:
+- apiGroups: ["batch"]
+  resources: ["jobs"]
+  # create: Needed for _batch_v1.create_namespaced_job().
+  # watch: Needed for watch.stream(self._batch_v1.list_namespaced_job, ...) to wait for completion
+  # list/get: Required for the watch to initialize and to get job details.
+  verbs: ["create", "get", "watch", "list", "delete"]
+- apiGroups: [""]
+  resources: ["configmaps"]
+  # create: Needed mount the agent's code into the Job's Pod.
+  # delete: Needed for cleanup in the finally block
+  verbs: ["create", "get", "list", "delete"]
+- apiGroups: [""]
+  resources: ["pods"]
+  # list: Needed to find the correct Pod _core_v1.list_namespaced_pod(label_selector=...)
+  verbs: ["get", "list", "delete"]
+- apiGroups: [""]
+  # get: Needed for _core_v1.read_namespaced_pod_log() to get the code execution results and logs.
+  resources: ["pods/log"]
+  verbs: ["get", "list"]
+---
+apiVersion: rbac.authorization.k8s.io/v1
+kind: RoleBinding
+metadata:
+  name: adk-agent-binding
+  namespace: agent-sandbox
+subjects:
+- kind: ServiceAccount
+  name: adk-agent-sa
+  namespace: agent-sandbox
+roleRef:
+  kind: Role
+  name: adk-agent-role
+  apiGroup: rbac.authorization.k8s.io

pyproject.toml

@@ -110,12 +110,13 @@ test = [
   "langchain-community>=0.3.17",
   "langgraph>=0.2.60, <= 0.4.10",                 # For LangGraphAgent
   "litellm>=1.75.5, <2.0.0",                      # For LiteLLM tests
+  "kubernetes>=29.0.0",                   # For GkeCodeExecutor
   "llama-index-readers-file>=0.4.0",              # For retrieval tests
   "openai>=1.100.2",                              # For LiteLLM
+  "pytest>=8.3.4",
   "pytest-asyncio>=0.25.0",
   "pytest-mock>=3.14.0",
   "pytest-xdist>=3.6.1",
-  "pytest>=8.3.4",
   "python-multipart>=0.0.9",
   "rouge-score>=0.1.2",
   "tabulate>=0.9.0",
@@ -139,6 +140,7 @@ extensions = [
   "docker>=7.0.0",                             # For ContainerCodeExecutor
   "langgraph>=0.2.60",                         # For LangGraphAgent
   "litellm>=1.75.5",                           # For LiteLlm class. Currently has OpenAI limitations. TODO: once LiteLlm fix it
+  "kubernetes>=29.0.0",                        # For GkeCodeExecutor
   "llama-index-readers-file>=0.4.0",           # For retrieval using LlamaIndex.
   "llama-index-embeddings-google-genai>=0.3.0",# For files retrieval using LlamaIndex.
   "lxml>=5.3.0",                               # For load_web_page tool.

src/google/adk/code_executors/__init__.py

@@ -28,6 +28,7 @@
     'UnsafeLocalCodeExecutor',
     'VertexAiCodeExecutor',
     'ContainerCodeExecutor',
+    'GkeCodeExecutor',
 ]
 
 
@@ -52,4 +53,14 @@ def __getattr__(name: str):
           'ContainerCodeExecutor requires additional dependencies. '
           'Please install with: pip install "google-adk[extensions]"'
       ) from e
+  elif name == 'GkeCodeExecutor':
+    try:
+      from .gke_code_executor import GkeCodeExecutor
+
+      return GkeCodeExecutor
+    except ImportError as e:
+      raise ImportError(
+          'GkeCodeExecutor requires additional dependencies. '
+          'Please install with: pip install "google-adk[extensions]"'
+      ) from e
   raise AttributeError(f"module '{__name__}' has no attribute '{name}'")