Generative AI Google Brain

agents-agent-engine-tutorial-get-started-with-code-execution

4 min read

Get started with Code Execution on Vertex AI Agent Engine

Source notebook

Repo path: agents/agent_engine/tutorial_get_started_with_code_execution.ipynb · Open on GitHub · intermediate

Runs LLM-generated Python securely with Vertex AI Agent Engine Sandbox and ADK agents.

Summary

This notebook teaches how to create an Agent Engine Sandbox, execute Python code through the Vertex AI SDK, and parse stdout, stderr, and generated files. It then shows direct and tool-calling integrations with Gemini and Claude on Vertex AI. The end-to-end workflow compares ADK agents using AgentEngineSandboxCodeExecutor versus BuiltInCodeExecutor and finishes with a sales data analyst agent and sandbox lifecycle operations.

Key code patterns

Initialize Vertex AI

os.environ["GOOGLE_CLOUD_PROJECT"] = PROJECT_ID
os.environ["GOOGLE_CLOUD_LOCATION"] = LOCATION
os.environ["GOOGLE_GENAI_USE_VERTEXAI"] = "1"
vertexai.init(project=PROJECT_ID, location=LOCATION)
client = vertexai.Client(project=PROJECT_ID, location=LOCATION)

Sets project, region, and ADK Vertex AI mode before creating Agent Engine resources.

Create sandbox

agent_engine = client.agent_engines.create()
sandbox_operation = client.agent_engines.sandboxes.create(
    name=agent_engine.api_resource.name,
    config=types.CreateAgentEngineSandboxConfig(display_name="my_custom_sandbox"),
    spec={"code_execution_environment": {"code_language": language_config, "machine_config": machine_config}},
)
sandbox_resource_name = sandbox_operation.response.name

Creates a managed, isolated code execution environment with configurable language and machine resources.

Execute and parse output

response = client.agent_engines.sandboxes.execute_code(
    name=sandbox_resource_name, input_data={"code": code}
)
for output in response.outputs:
    if output.mime_type == "application/json" and output.metadata is None:
        result = json.loads(output.data.decode("utf-8"))
        stdout = result.get("msg_out")
        stderr = result.get("msg_err")

The sandbox returns typed byte outputs, so JSON stdout and stderr must be decoded explicitly.

Gemini direct execution

model = GenerativeModel("gemini-2.5-flash")
response = model.generate_content(prompt)
generated_code = response.text.replace("```python", "").replace("```", "").strip()
exec_response = client.agent_engines.sandboxes.execute_code(
    name=sandbox_resource_name, input_data={"code": generated_code}
)

Separates code generation from execution for one-off tasks where the engineer controls the run step.

Gemini tool calling

code_tool = Tool(function_declarations=[FunctionDeclaration.from_func(execute_python_code)])
response = model.generate_content(contents=[user_content], generation_config=GenerationConfig(temperature=0), tools=[code_tool])
for function_call in response.candidates[0].function_calls:
    execution_output = execute_python_code(function_call.args["code"])
    parts.append(Part.from_function_response(name=function_call.name, response={"result": execution_output}))
final_response = model.generate_content([user_content, response.candidates[0].content, Content(role="function", parts=parts)], tools=[code_tool])

Lets Gemini decide when to call the sandbox tool, then feeds execution results back for a final answer.

Claude tool use

claude = AnthropicVertex(project_id=PROJECT_ID, region="us-east5")
message = claude.messages.create(
    model="claude-sonnet-4@20250514",
    max_tokens=1000,
    messages=[{"role": "user", "content": prompt}],
    tools=[code_execution_tool],
)
if message.stop_reason == "tool_use":
    result = execute_code_tool(content.input["code"])

Shows the same sandbox pattern is model-agnostic and can be used with Claude on Vertex AI.

ADK managed executor

vertex_agent = LlmAgent(
    model="gemini-2.5-flash",
    name="vertex_code_executor_agent",
    code_executor=AgentEngineSandboxCodeExecutor(sandbox_resource_name=sandbox_resource_name),
)
runner = Runner(agent=vertex_agent, app_name="vertex_code_app", session_service=vertex_session_service, artifact_service=artifact_session_service)
async for event in runner.run_async(user_id="user1", session_id="session1", new_message=message):
    parse_event(event)

Connects an ADK LlmAgent to the managed sandbox with session and artifact services.

ADK built-in executor

builtin_agent = LlmAgent(
    model="gemini-2.5-flash",
    name="builtin_code_executor_agent",
    code_executor=BuiltInCodeExecutor(),
)
builtin_runner = Runner(agent=builtin_agent, app_name="builtin_code_app", session_service=builtin_session_service)

Provides a simpler Gemini-only path for prototypes without creating a separate sandbox.

Models & APIs used

  • Models: gemini-2.5-flash, claude-sonnet-4@20250514
  • APIs / services: Vertex AI, Vertex AI Agent Engine, Agent Engine Sandbox, Cloud Storage
  • SDKs / libraries: google-cloud-aiplatform, vertexai, google-adk, google-genai, anthropic, pydantic, matplotlib

When to use this

Use this pattern when building agents that need to generate, execute, inspect, and explain Python code in a managed Vertex AI environment.

Gotchas & caveats

  • Install google-cloud-aiplatform>=1.112.0, anthropic, and google-adk before running the notebook.
  • Colab requires authenticate_user() before accessing Vertex AI services.
  • PROJECT_ID and LOCATION must be set, and GOOGLE_GENAI_USE_VERTEXAI is set to 1 for ADK Vertex AI use.
  • Claude model availability varies by region; the notebook uses us-east5 for AnthropicVertex.
  • BuiltInCodeExecutor works only with Gemini models, while AgentEngineSandboxCodeExecutor can be used with other LLMs.
  • AgentEngineSandboxCodeExecutor artifacts are auto-saved to GCS, and the notebook says users cannot manage those GCS artifacts at this moment.
  • Managed sandbox state can persist variables across calls for up to 14 days.
  • Delete sandboxes no longer needed to avoid unnecessary costs.

Best practices

  • Run generated or untrusted code in an isolated Agent Engine Sandbox instead of the host system.
  • Initialize Vertex AI with explicit project and location before creating Agent Engine resources.
  • Parse sandbox outputs by mime_type and metadata, handling stdout, stderr, and generated files separately.
  • Use temperature=0 for the Gemini tool-calling example to make the function-call flow more deterministic.
  • Send function_response or tool_result messages back to the model before asking for the final answer.
  • Use ADK session, memory, and artifact services when building stateful agents.
  • Choose AgentEngineSandboxCodeExecutor for production agents needing isolation, artifacts, multi-model support, or resource control.
  • Choose BuiltInCodeExecutor for rapid Gemini-only prototypes and demos.

Graph View

Backlinks