mirror of
https://github.com/google/adk-docs.git
synced 2026-09-14 16:16:59 +08:00
George Weale
c21cd63918
* Fix code samples that do not compile against the shipped SDKs Checked the code samples against the real published libraries and corrected what does not compile or resolve. Verified against google-adk 2.8.0 for Python, @google/adk 2.0.0 for TypeScript, google-adk 1.6.0 for Java, adk-kotlin 0.8.0 for Kotlin, and adk/v2 2.3.0 for Go. Go: tool.Context does not exist in the v2 line and never has. The type is agent.Context, which this repository's own Go examples already use. Nine sites. Four import blocks also omitted the fmt they call. Java: two imports naming packages that do not exist, com.google.adk.agent (the package is agents) and com.google.adk.agents.Content (it is a genai type). Four wrong types, each confirmed against the jar with javap: EventActions.stateDelta returns Map not ConcurrentMap, artifactDelta returns Map<String, Integer> rather than ConcurrentMap<String, Part>, FunctionResponse.response yields Map<String, Object>, and loadArtifact takes the version as an int so the Optional argument matched no overload. Python: four coroutines used without await, which also masked a SearchMemoryResponse.results field that does not exist. The field is memories, holding MemoryEntry objects; the TypeScript and Java tabs of the same example had the same mistake. Also CodeExecutionInput imported from the wrong module, a calendar_tool_set object that does not exist in place of CalendarToolset, two positional Part.from_text calls against a keyword-only signature, five LlmAgent samples missing the required name, and an external access token sample built on an enum member and a field that the package does not define. Also corrects samples that could not parse at all: an unindented plugin class body, bracket and text block typos, a truncated call, an await in a non-async function, an await dedented out of the condition meant to guard it, a mid-file Java import, and a fence that opened at six spaces and closed at eight, which made a page render a literal code fence as body text. * Yield the workflow node's result instead of returning it code_workflow yields, which makes it an async generator, and returning a value from one is a syntax error. A generator node conveys its result by yielding an event whose output the runner copies to the context, which is the form the data handling page already uses. * docs(tools): simplify the toolset headings per review Drop the parenthetical class lists from the two toolset headings in the authentication page. Nothing links to either anchor. --------- Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>
161 lines
11 KiB
Markdown
161 lines
11 KiB
Markdown
---
|
|
catalog_title: GKE Code Executor
|
|
catalog_description: Run AI-generated code in a secure and scalable GKE environment
|
|
catalog_icon: /integrations/assets/gke.png
|
|
catalog_tags: ["code","google"]
|
|
---
|
|
|
|
# Google Cloud GKE Code Executor tool for ADK
|
|
|
|
<div class="language-support-tag">
|
|
<span class="lst-supported">Supported in ADK</span><span class="lst-python">Python v1.14.0</span>
|
|
</div>
|
|
|
|
The GKE Code Executor (`GkeCodeExecutor`) provides a secure and scalable method
|
|
for running LLM-generated code by leveraging Google Kubernetes Engine (GKE). You should use this executor for production environments on GKE where security and isolation are critical. It supports two execution modes:
|
|
|
|
1. **Sandbox Mode (Recommended):** Utilizes the [Agent Sandbox](https://github.com/kubernetes-sigs/agent-sandbox) client to execute code within sandbox instances created on-demand from a template. This mode offers lower latency by using [pre-warmed sandboxes](https://docs.cloud.google.com/kubernetes-engine/docs/how-to/agent-sandbox#create_a_sandboxtemplate_and_sandboxwarmpool) and supports more direct interaction with the sandbox environment.
|
|
2. **Job Mode:** Uses the GKE Sandbox environment with gVisor for workload isolation. For each code execution request, it dynamically creates an ephemeral, sandboxed Kubernetes Job with a hardened Pod configuration. This mode is provided for backward compatibility.
|
|
|
|
|
|
## Execution Modes
|
|
|
|
### Sandbox Mode (`executor_type="sandbox"`)
|
|
|
|
This is the recommended mode. It uses the `k8s-agent-sandbox` client library to create and communicate with the Agent Sandbox in the GKE Cluster. When a request to execute code is made, it performs the following steps:
|
|
|
|
1. Creates a `SandboxClaim` using the specified template.
|
|
2. Waits for the sandbox instance to become ready.
|
|
3. Executes the code in the claimed sandbox.
|
|
4. Retrieves the standard output and error.
|
|
5. Deletes the `SandboxClaim`, which in turn cleans up the sandbox instance.
|
|
|
|
This approach is faster than the Job mode as it leverages pre-warmed sandboxes and optimizes startup time provided by the Agent Sandbox controller.
|
|
|
|
**Key Benefits:**
|
|
|
|
In addition to all the benefits of the Job mode, Sandbox mode also offers the following features:
|
|
|
|
* **Lower Latency:** Aims to reduce startup time compared to creating full Kubernetes Jobs.
|
|
* **Managed Environment:** Leverages the Agent Sandbox framework for sandbox lifecycle management.
|
|
|
|
**Prerequisites:**
|
|
|
|
* An existing Agent Sandbox deployment in your GKE cluster, including the sandbox controller and it's extensions (e.g., sandbox claim controller & sandbox warmpool controller), router, gateway and relevant `SandboxTemplate` resources (e.g., `python-sandbox-template`).
|
|
* The necessary RBAC permissions for the ADK agent to create and delete `SandboxClaim` resources.
|
|
|
|
### Job Mode (`executor_type="job"`)
|
|
|
|
This mode is provided for backward compatibility. When a request to execute code is made, the `GkeCodeExecutor` performs the following steps:
|
|
|
|
1. **Creates a ConfigMap:** A Kubernetes ConfigMap is created to store the Python code that needs to be executed.
|
|
2. **Creates a Sandboxed Pod:** A new Kubernetes Job is created, which in turn creates a Pod with a hardened security context and the gVisor runtime enabled. The code from the ConfigMap is mounted into this Pod.
|
|
3. **Executes the Code:** The code is executed within the sandboxed Pod, isolated from the underlying node and other workloads.
|
|
4. **Retrieves the Result:** The standard output and error streams from the execution are captured from the Pod's logs.
|
|
5. **Cleans Up Resources:** Once the execution is complete, the Job and the associated ConfigMap are automatically deleted, ensuring that no artifacts are left behind.
|
|
|
|
**Key Benefits:**
|
|
|
|
* **Enhanced Security:** Code is executed in a gVisor-sandboxed environment with kernel-level isolation.
|
|
* **Ephemeral Environments:** Each code execution runs in its own ephemeral Pod, to prevent state transfer between executions.
|
|
* **Resource Control:** You can configure CPU and memory limits for the execution Pods to prevent resource abuse.
|
|
* **Scalability:** Allows you to run a large number of code executions in parallel, with GKE handling the scheduling and scaling of the underlying nodes.
|
|
* **Minimal Setup:** Relies on standard GKE features and gVisor.
|
|
|
|
## System requirements
|
|
|
|
The following requirements must be met to successfully deploy your ADK project
|
|
with the GKE Code Executor tool:
|
|
|
|
- GKE cluster with a **gVisor-enabled node pool** (required for both Job Mode's default image and typical Agent Sandbox templates).
|
|
- Agent's service account requires specific **RBAC permissions**:
|
|
- **Job Mode:** Create, watch, and delete **Jobs**; Manage **ConfigMaps**; List **Pods** and read their **logs**. For a complete, ready-to-use configuration for Job Mode, see the
|
|
[deployment_rbac.yaml](https://github.com/google/adk-python/blob/main/contributing/samples/integrations/gke_agent_sandbox/deployment_rbac.yaml)
|
|
sample.
|
|
- **Sandbox Mode:** Permissions to create, get, watch, and delete **SandboxClaim** and **Sandbox** resources within the namespace where the Agent Sandbox is deployed.
|
|
- Install the client library with the appropriate extras: `pip install google-adk[gke]`
|
|
|
|
## Configuration parameters
|
|
|
|
The `GkeCodeExecutor` can be configured with the following parameters:
|
|
|
|
| Parameter | Type | Description |
|
|
| ---------------------- | ----------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
| `namespace` | `str` | Kubernetes namespace where the execution resources (Jobs or SandboxClaims) will be created. Defaults to `"default"`. |
|
|
| `executor_type` | `Literal["job", "sandbox"]` | Specifies the execution mode. Defaults to `"job"`. |
|
|
| `image` | `str` | (Job Mode) Container image to use for the execution Pod. Defaults to `"python:3.11-slim"`. |
|
|
| `timeout_seconds` | `int` | (Job Mode) Timeout in seconds for the code execution. Defaults to `300`. |
|
|
| `cpu_requested` | `str` | (Job Mode) Amount of CPU to request for the execution Pod. Defaults to `"200m"`. |
|
|
| `mem_requested` | `str` | (Job Mode) Amount of memory to request for the execution Pod. Defaults to `"256Mi"`. |
|
|
| `cpu_limit` | `str` | (Job Mode) Maximum amount of CPU the execution Pod can use. Defaults to `"500m"`. |
|
|
| `mem_limit` | `str` | (Job Mode) Maximum amount of memory the execution Pod can use. Defaults to `"512Mi"`. |
|
|
| `kubeconfig_path` | `str` | Path to a kubeconfig file to use for authentication. Falls back to in-cluster config or the default local kubeconfig. |
|
|
| `kubeconfig_context` | `str` | The `kubeconfig` context to use. |
|
|
| `sandbox_gateway_name` | `str \| None` | (Sandbox Mode) The name of the sandbox gateway to use. Optional. |
|
|
| `sandbox_template` | `str \| None` | (Sandbox Mode) The name of the `SandboxTemplate` to use. Defaults to `"python-sandbox-template"`. |
|
|
|
|
## Usage Examples
|
|
|
|
=== "Python - Sandbox Mode (Recommended)"
|
|
|
|
```python
|
|
from google.adk.agents import LlmAgent
|
|
from google.adk.code_executors import GkeCodeExecutor
|
|
from google.adk.code_executors.code_execution_utils import CodeExecutionInput
|
|
from google.adk.agents.invocation_context import InvocationContext
|
|
|
|
# Initialize the executor for Sandbox Mode
|
|
# Namespace should have RBAC for SandboxClaims and Sandbox
|
|
gke_sandbox_executor = GkeCodeExecutor(
|
|
namespace="agent-sandbox-system", # Typically where agent-sandbox is installed
|
|
executor_type="sandbox",
|
|
sandbox_template="python-sandbox-template",
|
|
sandbox_gateway_name="your-gateway-name", # Optional
|
|
)
|
|
|
|
# Example direct execution:
|
|
ctx = InvocationContext()
|
|
result = gke_sandbox_executor.execute_code(ctx, CodeExecutionInput(code="print('Hello from Sandbox Mode')"))
|
|
print(result.stdout)
|
|
|
|
# Example with an Agent:
|
|
gke_sandbox_agent = LlmAgent(
|
|
name="gke_sandbox_coding_agent",
|
|
model="gemini-flash-latest",
|
|
instruction="You are a helpful AI agent that writes and executes Python code using sandboxes.",
|
|
code_executor=gke_sandbox_executor,
|
|
)
|
|
```
|
|
|
|
=== "Python - Job Mode"
|
|
|
|
```python
|
|
from google.adk.agents import LlmAgent
|
|
from google.adk.code_executors import GkeCodeExecutor
|
|
from google.adk.code_executors.code_execution_utils import CodeExecutionInput
|
|
from google.adk.agents.invocation_context import InvocationContext
|
|
|
|
# Initialize the executor for Job Mode
|
|
# Namespace should have RBAC for Jobs, ConfigMaps, Pods, Logs
|
|
gke_executor = GkeCodeExecutor(
|
|
namespace="agent-ns",
|
|
executor_type="job",
|
|
timeout_seconds=600,
|
|
cpu_limit="1000m", # 1 CPU core
|
|
mem_limit="1Gi",
|
|
)
|
|
|
|
# Example direct execution:
|
|
ctx = InvocationContext()
|
|
result = gke_executor.execute_code(ctx, CodeExecutionInput(code="print('Hello from Job Mode')"))
|
|
print(result.stdout)
|
|
|
|
# Example with an Agent:
|
|
gke_agent = LlmAgent(
|
|
name="gke_coding_agent",
|
|
model="gemini-flash-latest",
|
|
instruction="You are a helpful AI agent that writes and executes Python code.",
|
|
code_executor=gke_executor,
|
|
)
|
|
```
|