Skip to content
GkPy

Agents (LlmAgent, LangGraphAgent, RemoteA2aAgent, Parallel, Loop, Sequential)

All agent primitives shipped by google-adk: LlmAgent, LangGraphAgent, RemoteA2aAgent, and the deprecated shell agents.

Verified against google-adk 2.13.0 (google/adk/agents/), checked 2026-11-19. The examples were run against a stub model that stands in for Gemini. ManagedAgent arrived in 2.4.0; LangGraphAgent needs the langgraph package.

ADK exposes one LLM-backed agent (LlmAgent, also re-exported as Agent), three shell agents for composition (SequentialAgent, ParallelAgent, LoopAgent — deprecated in 2.x), a LangGraph bridge (LangGraphAgent), and a remote-agent client (RemoteA2aAgent). New projects should compose with Workflow rather than the deprecated shell agents — see the workflows page.

import asyncio
from google.adk.agents import LlmAgent
from google.adk.runners import InMemoryRunner
root = LlmAgent(
name="tutor",
model="gemini-3.8-flash",
instruction="Answer concisely. If you do maths, show the steps.",
)
async def main():
runner = InMemoryRunner(agent=root, app_name="demo")
await runner.session_service.create_session(
app_name="demo", user_id="u1", session_id="s1"
)
events = await runner.run_debug("What is 15 + 27?", user_id="u1", session_id="s1")
print(events[-1].content.parts[0].text)
asyncio.run(main())

Agent is a type alias for LlmAgent (agents/llm_agent.py:end). InMemoryRunner wires in-memory session/memory/artifact services so the example runs with no GCP setup.

ClassModulePurposeStatus
LlmAgentgoogle.adk.agentsLLM-backed; uses tools= + sub_agents= for orchestrationStable
SequentialAgentgoogle.adk.agentsRuns sub-agents in sequenceDeprecated → Workflow
ParallelAgentgoogle.adk.agentsRuns sub-agents concurrentlyDeprecated → Workflow
LoopAgentgoogle.adk.agentsRuns sub-agents in a loop until escalate or max_iterationsDeprecated → Workflow
LangGraphAgentgoogle.adk.agents.langgraph_agentWraps a compiled LangGraph graph as a BaseAgentStable (concept)
RemoteA2aAgentgoogle.adk.agents.remote_a2a_agentCalls a remote A2A-compatible agent over HTTP@a2a_experimental

The deprecation notices are emitted via typing_extensions.deprecated at class level (see sequential_agent.py, parallel_agent.py, loop_agent.py).

LangGraphAgent, RemoteA2aAgent and ManagedAgent have their own sections below; the A2A side (serving agents, authentication, task mode) is on MCP and A2A.

Pydantic model. Constructor accepts every field as a kwarg.

from google.adk.agents import LlmAgent
from google.adk.tools import google_search
from pydantic import BaseModel
class Reply(BaseModel):
answer: str
confidence: float
agent = LlmAgent(
name="research_assistant", # required; must be a Python identifier
model="gemini-3.8-flash", # str or BaseLlm; inherits from ancestors when ""
description="Answers research questions with web search.",
instruction="You are a research assistant. Cite the URLs you consulted.",
tools=[google_search],
output_schema=Reply, # optional; tools still work alongside output_schema
output_key="latest_reply", # writes final text to session.state[key]
include_contents="default", # or "none" to wipe history
disallow_transfer_to_parent=False,
disallow_transfer_to_peers=False,
)

Field reference (verified in agents/llm_agent.py):

FieldTypeDefaultNotes
namestrrequiredIdentifier; used for agent-transfer routing
modelstr | BaseLlm""Empty inherits; built-in default is gemini-3.5-flash (DEFAULT_MODEL)
instructionstr | InstructionProvider""Supports {state_key} placeholders resolved from session state
global_instructionsame""Deprecated → use GlobalInstructionPlugin
static_instructiontypes.ContentUnionNoneFor context-cache friendly prefixes
toolslist[Callable | BaseTool | BaseToolset][]Callables are auto-wrapped as FunctionTool
generate_content_configtypes.GenerateContentConfigNoneTemperature, safety, thinking, etc.
mode'chat' | 'task' | 'single_turn' | NoneNoneA root LlmAgent must be 'chat' (the default) or 'task'
input_schema / output_schemaPydantic model / schemaNoneoutput_schema and tools can be used together
output_keystrNoneWrites final text to session.state[key]
include_contents'default' | 'none''default''none' → stateless single-turn
plannerBasePlannerNoneBuiltInPlanner forwards thinking_config to the model
code_executorBaseCodeExecutorNoneSee code executors
disallow_transfer_to_parent / disallow_transfer_to_peersboolFalseGoverns agent-transfer reachability
before_model_callback / after_model_callback / on_model_error_callbackfn or listNoneSee callbacks-and-plugins
before_tool_callback / after_tool_callback / on_tool_error_callbackfn or listNoneSame
before_agent_callback / after_agent_callbackfn or listNoneInherited from BaseAgent

generate_content_config — temperature, safety, thinking

Section titled “generate_content_config — temperature, safety, thinking”

All generation parameters (temperature, top-p, max tokens, safety settings, thinking mode) live inside types.GenerateContentConfig. Do not pass them as top-level fields on LlmAgent — they are not accepted there.

from google.adk.agents import LlmAgent
from google.genai import types
agent = LlmAgent(
name="precise_analyst",
model="gemini-4-argon",
instruction="Analyse the data carefully.",
generate_content_config=types.GenerateContentConfig(
temperature=0.2, # lower = more deterministic
max_output_tokens=4096,
top_p=0.95,
safety_settings=[
types.SafetySetting(
category=types.HarmCategory.HARM_CATEGORY_DANGEROUS_CONTENT,
threshold=types.HarmBlockThreshold.BLOCK_ONLY_HIGH,
)
],
),
)
# Thinking (Gemini 3 models take thinking_level; Gemini 2.5 models took thinking_budget)
thinking_agent = LlmAgent(
name="thoughtful",
model="gemini-4-argon",
generate_content_config=types.GenerateContentConfig(
thinking_config=types.ThinkingConfig(
include_thoughts=True,
thinking_level=types.ThinkingLevel.HIGH,
)
),
)

A bare string is looked up in LLMRegistry. The registered prefixes are Gemini, Gemma, ApigeeLlm, optionally Claude, LiteLlm, Gemma3Ollama (models/__init__.py). Setting LlmAgent.set_default_model("gemini-4-argon") changes the class-level default used when model="" and no ancestor sets it. The built-in class constants are LlmAgent.DEFAULT_MODEL = "gemini-3.5-flash" and LlmAgent.DEFAULT_LIVE_MODEL = "gemini-live-2.5-flash-native-audio".

from google.adk.models import Gemini, LiteLlm
# A Gemini instance, where per-model settings such as retry_options go
agent = LlmAgent(name="analyst", model=Gemini(model="gemini-4-argon"))
# OpenAI via LiteLlm (requires `pip install google-adk[extensions]`)
agent = LlmAgent(name="gpt", model=LiteLlm(model="openai/gpt-6.1-sol"))
# Change the class-level default for all agents in the process
LlmAgent.set_default_model("gemini-4-argon")

instruction can be a callable receiving a ReadonlyContext:

async def instruction_provider(ctx):
user = ctx.state.get("user_name", "there")
return f"You are talking to {user}. Be friendly."
agent = LlmAgent(name="greeter", instruction=instruction_provider)

static_instruction — context-cache optimisation

Section titled “static_instruction — context-cache optimisation”

static_instruction is a fixed system-level prefix that never changes between turns. When set, the runtime sends it as system_instruction (the ideal cache key for Gemini’s implicit context cache) and moves the dynamic instruction field into user content. This layout maximises cache hits because the static prefix is always the first thing the model sees.

from google.adk.agents import LlmAgent
from google.genai import types
# ── Without static_instruction (no caching benefit) ─────────────────────────
agent_no_cache = LlmAgent(
name="legal_assistant",
model="gemini-3.8-flash",
instruction="You are a legal assistant specialising in UK contract law. "
"Always cite relevant legislation. User: {user_name}.",
)
# ── With static_instruction (static part is cache-eligible) ─────────────────
# The static part (large reference content) is sent as system_instruction.
# The dynamic part (personalisation) is injected as user content each turn.
agent_with_cache = LlmAgent(
name="legal_assistant",
model="gemini-3.8-flash",
# This large, fixed block is eligible for Gemini's implicit context cache:
static_instruction=(
"You are a legal assistant specialising in UK contract law. "
"Always cite relevant legislation. "
"Reference: Sale of Goods Act 1979, Consumer Rights Act 2015, "
"Companies Act 2006. When citing a section, include the full section "
"number and a one-sentence summary. Never give legal advice; only "
"provide general information about how the law operates."
),
# Dynamic per-turn personalisation — sent as user content, not cached:
instruction="You are currently helping {user_name} ({user_role}).",
)
# ── With rich content (files, images) ────────────────────────────────────────
# static_instruction accepts types.ContentUnion, so you can include file refs:
agent_with_doc = LlmAgent(
name="doc_analyst",
model="gemini-3.8-flash",
static_instruction=types.Content(
role="user",
parts=[
types.Part(text="You are an expert document analyst. Refer to the "
"attached policy document for all answers."),
types.Part(
file_data=types.FileData(
mime_type="application/pdf",
file_uri="gs://my-bucket/policy-v3.pdf",
)
),
],
),
instruction="Answer questions about the policy document. Keep answers under 3 sentences.",
)

Note: Setting static_instruction does not automatically create an explicit cache entry. Explicit cache management requires ContextCacheConfig at the App level. static_instruction simply optimises the prompt layout so Gemini’s implicit (automatic) cache can recognise the fixed prefix as a stable cache key.

The mode field controls dispatch behaviour, agent-transfer eligibility, and how content history is handled. It matters most when placing agents inside a Workflow.

ModeDispatch styleTransfer toolsinclude_contents defaultValid placement
'chat'Continuous conversation loopInjected (if sub_agents set)'default' (full history)Root LlmAgent; first node after START in a Workflow
NoneResolved by context——Root LlmAgent (runner → 'chat'); Workflow node (build_node() → 'single_turn')
'single_turn'One LLM call, then exitNot injected'none' (stateless)Any Workflow node; build_node() default
'task'Multi-round work that ends with a finish_task callNot injected'default'Sub-agent of a mode='chat' coordinator, a Workflow node, ctx.run_node(), or the root

When mode=None, the runner auto-sets 'chat' for a root LlmAgent, but build_node() resolves it to 'single_turn' when the agent is placed inside a Workflow. A mode='task' agent works as a static Workflow node: it is offered a finish_task tool, keeps going until it calls it, and the validated arguments become the node’s output. A RemoteA2aAgent in task mode is the exception: it is only supported in tool-delegation mode, not as a standalone node.

This is the default for a root agent. It drives a multi-turn conversation and, when given sub_agents, gains transfer_to_agent routing.

import asyncio
from google.adk.agents import LlmAgent
from google.adk.runners import InMemoryRunner
from google.adk.apps import App
from google.genai import types
billing = LlmAgent(
name="billing",
model="gemini-3.8-flash",
description="Handles invoice and refund questions.",
instruction="Answer billing questions concisely.",
)
support = LlmAgent(
name="support",
model="gemini-3.8-flash",
description="Handles technical support questions.",
instruction="Help users fix technical problems.",
)
coordinator = LlmAgent(
name="triage",
model="gemini-3.8-flash",
# mode='chat' is set automatically by the runner for root agents
instruction="Route each question to the right specialist.",
sub_agents=[billing, support],
)
async def main():
app = App(name="demo", root_agent=coordinator)
runner = InMemoryRunner(app=app)
session = await runner.session_service.create_session(
app_name="demo", user_id="u1"
)
async for event in runner.run_async(
user_id="u1",
session_id=session.id,
new_message=types.Content(
role="user",
parts=[types.Part(text="I have a question about my last invoice.")]
),
):
if event.is_final_response() and event.content:
print(event.content.parts[0].text)
asyncio.run(main())

mode='single_turn' — stateless workflow node

Section titled “mode='single_turn' — stateless workflow node”

single_turn agents run one LLM call and exit. They receive their input via node_input (set to the preceding node’s output), not from session history (include_contents defaults to 'none' unless you explicitly set it). This makes them ideal as Workflow stages.

import asyncio
from google.adk.agents import LlmAgent
from google.adk.workflow import Workflow, START
from google.adk.runners import InMemoryRunner
from google.adk.apps import App
drafter = LlmAgent(
name="drafter",
model="gemini-3.8-flash",
mode="single_turn", # processes one turn, no history
instruction="Write a punchy 2-sentence summary of the input topic.",
)
editor = LlmAgent(
name="editor",
model="gemini-3.8-flash",
mode="single_turn",
instruction="Polish the summary. Fix grammar, tighten sentences. Return only the final text.",
)
pipeline = Workflow(
name="summarize",
edges=[(START, drafter, editor)], # drafter output → editor input
)
async def main():
app = App(name="demo", root_agent=pipeline)
runner = InMemoryRunner(app=app)
session = await runner.session_service.create_session(
app_name="demo", user_id="u1"
)
events = await runner.run_debug(
"Electric vehicles are outselling petrol cars in Norway.",
user_id="u1", session_id=session.id,
)
# Workflow node completions are Event(output=...) — read event.output directly
output = next((e.output for e in reversed(events) if e.output is not None), None)
print(output)
asyncio.run(main())

build_node(agent) produces the same result — it sets mode='single_turn' automatically when no parent agent is provided.

mode='task' — structured I/O with input/output schemas

Section titled “mode='task' — structured I/O with input/output schemas”

task mode agents accept a structured input_schema and return a validated output_schema. The ADK uses a FinishTaskTool handshake internally: the LLM calls finish_task(result=...) when ready, ADK validates the Pydantic model, and the result surfaces as event.output on the parent. If validation fails, the model is prompted to retry.

Task agents can be a chat coordinator’s sub_agents (below), static Workflow nodes, or dispatched with ctx.run_node().

import asyncio
from pydantic import BaseModel, Field
from google.adk.agents import LlmAgent
from google.adk.runners import InMemoryRunner
from google.adk.apps import App
from google.genai import types
# ── Pydantic schemas for structured I/O ──────────────────────────────────────
class ResearchInput(BaseModel):
topic: str = Field(description="The subject to research.")
depth: str = Field(default="brief", description="'brief' or 'detailed'.")
class ResearchOutput(BaseModel):
summary: str = Field(description="A concise summary of findings.")
key_points: list[str] = Field(description="3-5 bullet points.")
sources: list[str] = Field(description="Cited URLs or references.")
# ── Task sub-agent — structured I/O, no transfer tools ──────────────────────
researcher = LlmAgent(
name="researcher",
model="gemini-3.8-flash",
mode="task",
instruction=(
"Research the given topic. Return a structured summary with "
"key points and cited sources."
),
input_schema=ResearchInput,
output_schema=ResearchOutput,
)
# ── Chat coordinator — delegates structured work to researcher ────────────────
writer = LlmAgent(
name="writer",
model="gemini-3.8-flash",
instruction=(
"You write blog posts. For every topic, first ask the 'researcher' "
"sub-agent for a structured brief, then write a 3-paragraph post."
),
sub_agents=[researcher], # researcher is auto-wrapped as _TaskAgentTool
)
async def main():
app = App(name="blog_app", root_agent=writer)
runner = InMemoryRunner(app=app)
session = await runner.session_service.create_session(
app_name="blog_app", user_id="u1"
)
async for event in runner.run_async(
user_id="u1",
session_id=session.id,
new_message=types.Content(
role="user",
parts=[types.Part(text="Write a post about quantum computing.")]
),
):
if event.is_final_response() and event.content:
print(event.content.parts[0].text)
asyncio.run(main())

Task mode dispatch via ctx.run_node() (from inside a Workflow @node):

from google.adk.workflow import node, Workflow, START
@node(rerun_on_resume=True)
async def orchestrate(node_input: str, ctx) -> str:
# Dispatch the task agent dynamically — ctx.run_node supports task-mode agents
result = await ctx.run_node(researcher, ResearchInput(topic=node_input), run_id="research")
# result is a ResearchOutput instance (Pydantic model)
summary = result.summary if hasattr(result, "summary") else str(result)
return summary
wf = Workflow(name="research_pipeline", edges=[(START, orchestrate)])

When output_key does not apply. In task mode, output_key has no effect — the result surfaces only via event.output, not via session.state. Use ctx.state["key"] = result in the calling @node if you need to thread the output through session state.

parallel_worker — fan-out over a list input

Section titled “parallel_worker — fan-out over a list input”

Setting parallel_worker=True on an LlmAgent tells the Workflow engine to invoke the agent once per item in a list input, running all items concurrently up to max_parallel_workers. This is the idiomatic way to process a batch of inputs with an LLM agent without writing explicit fan-out logic in a @node.

The field is declared on LlmAgent itself (agents/llm_agent.py) and is wired up by build_node() when the agent appears in a Workflow edge.

import asyncio
from google.adk.agents import LlmAgent
from google.adk.workflow import Workflow, node, START
from google.adk.apps import App
from google.adk.runners import InMemoryRunner
from google.genai import types
# ── Fan-out agent ─────────────────────────────────────────────────────────────
_summariser_agent = LlmAgent(
name="summariser",
model="gemini-3.8-flash",
mode="single_turn",
instruction="Summarise the given text in one sentence.",
)
# Use the public node() API to wrap the agent as a parallel worker.
# node() with parallel_worker=True internally creates a _ParallelWorker;
# do not pass parallel_worker=True on the LlmAgent itself when calling node()
# — that would double-wrap the agent and cause unexpected behaviour.
summariser = node(_summariser_agent, parallel_worker=True, max_parallel_workers=3)
# ── Upstream node produces a list for the fan-out ────────────────────────────
@node
def split_articles(node_input: str) -> list[str]:
"""Split a newline-separated batch into individual articles."""
return [line.strip() for line in node_input.splitlines() if line.strip()]
# ── Downstream node collects all summaries ───────────────────────────────────
@node
def combine(node_input: list[str]) -> str:
"""Join per-article summaries into a single digest."""
return "\n".join(f"• {s}" for s in node_input)
pipeline = Workflow(
name="batch_summariser",
edges=[(START, split_articles, summariser, combine)],
)
async def main():
app = App(name="batch_app", root_agent=pipeline)
runner = InMemoryRunner(app=app)
session = await runner.session_service.create_session(
app_name="batch_app", user_id="u1"
)
articles = "\n".join([
"Google releases Gemini 3.5 with 2M context window.",
"EU AI Act enters enforcement phase from August 2026.",
"Anthropic publishes Claude's model spec publicly.",
])
async for event in runner.run_async(
user_id="u1",
session_id=session.id,
new_message=types.Content(role="user", parts=[types.Part(text=articles)]),
):
# FunctionNode (@node) returns land in event.output, not event.content.
if event.node_name == "combine" and event.output is not None:
print(event.output)
asyncio.run(main())

How it works: node(agent, parallel_worker=True) wraps the agent in a parallel-worker node. When the predecessor outputs a list, it runs the agent once per element, at most max_parallel_workers at a time, and passes the list of results to the next node in input order. Setting parallel_worker=True on the LlmAgent itself has the same effect when the agent is placed in an edge, but has no concurrency cap; use node(...) when you need one. Passing max_parallel_workers without parallel_worker=True raises WorkflowConfigurationError.

An LlmAgent with sub_agents=[...] gets the transfer_to_agent tool injected automatically. On the next user message, the runner routes to the agent that replied last, as long as transfers allow it to keep the conversation.

from google.adk.agents import LlmAgent
billing = LlmAgent(name="billing", description="Handles refunds, invoices.", instruction="...")
support = LlmAgent(name="support", description="Handles tech issues.", instruction="...")
root = LlmAgent(
name="triage",
instruction="Route the user to the right specialist.",
sub_agents=[billing, support],
)

Set disallow_transfer_to_parent=True on a specialist to prevent it from returning control to the triage agent. Pair with disallow_transfer_to_peers=True to lock the conversation to the single agent (the runtime will then use SingleFlow instead of AutoFlow, disabling transfer-tool injection entirely — llm_agent.py).

Set code_executor= on an LlmAgent to let the model run code:

ExecutorWhere it runsExtra install
BuiltInCodeExecutorGemini-side (safe, sandboxed)none
UnsafeLocalCodeExecutorcurrent Python processnone — unsafe
AgentEngineSandboxCodeExecutorVertex AI Agent Engine code sandboxnone beyond Google Cloud credentials
ContainerCodeExecutorLocal Docker containergoogle-adk[extensions]
GkeCodeExecutorGKE podgoogle-adk[extensions]
CloudRunSandboxCodeExecutorCloud Run sandbox (google.adk.integrations.cloud_run)Google Cloud credentials
VertexAiCodeExecutorVertex AI Code Interpreter extensionDeprecated; needs google-cloud-aiplatform>=2.2,<3 installed separately
from google.adk.code_executors import BuiltInCodeExecutor
agent = LlmAgent(
name="analyst",
model="gemini-4-argon",
instruction="Use Python to compute anything numeric.",
code_executor=BuiltInCodeExecutor(),
)

Note: RunConfig(support_cfc=True) (compositional function calling) makes the root agent use BuiltInCodeExecutor whatever code_executor says, and the runner raises ValueError: CFC is not supported for model ... unless the model name starts with gemini-2.

Every executor inherits these BaseCodeExecutor fields:

FieldDefaultPurpose
optimize_data_fileFalsePull CSV files out of the request and hand them to the executor
statefulFalseKeep interpreter state across code blocks
error_retry_attempts2Consecutive code errors tolerated before giving up
code_block_delimiters```tool_code and ```python fencesHow code blocks are found in model output
execution_result_delimiters```tool_output fenceHow results are fed back to the model
timeout_secondsNoneWall-clock limit per execution

UnsafeLocalCodeExecutor runs each block in a fresh subprocess of the current interpreter (sending SIGTERM, then SIGKILL after 5 s on timeout), so stateful=True and optimize_data_file=True raise ValueError. It has full OS access; use it only in a trusted sandbox. To run code somewhere else, subclass BaseCodeExecutor and implement the synchronous execute_code:

import subprocess
from google.adk.code_executors import BaseCodeExecutor
from google.adk.code_executors.code_execution_utils import CodeExecutionInput, CodeExecutionResult
class DockerCodeExecutor(BaseCodeExecutor):
image: str = "python:3.13-slim"
def execute_code(self, invocation_context, code_execution_input: CodeExecutionInput) -> CodeExecutionResult:
proc = subprocess.run(
["docker", "run", "--rm", "-i", "--network=none", self.image, "python", "-"],
input=code_execution_input.code.encode(),
capture_output=True,
timeout=self.timeout_seconds or 30,
)
return CodeExecutionResult(stdout=proc.stdout.decode(), stderr=proc.stderr.decode())

BuiltInCodeExecutor — the full signature

Section titled “BuiltInCodeExecutor — the full signature”

Source-verified against google.adk.code_executors.built_in_code_executor (first verified in 2.7.1; re-checked against 2.13.0). Every field is inherited from BaseCodeExecutor; BuiltInCodeExecutor overrides only process_llm_request (attaches types.Tool(code_execution=types.ToolCodeExecution()) to the request) and stubs out execute_code because execution happens inside the Gemini API call, not client-side.

from google.adk.code_executors import BuiltInCodeExecutor
from google.adk.agents import LlmAgent
executor = BuiltInCodeExecutor(
optimize_data_file=False, # no-op for Gemini side execution (CSV path is external-executor only)
stateful=False, # ignored — Gemini manages its own execution session
error_retry_attempts=2, # tracked by ADK's response processor for external executors; unused here
code_block_delimiters=[
("```tool_code\n", "\n```"),
("```python\n", "\n```"),
],
execution_result_delimiters=("```tool_output\n", "\n```"),
timeout_seconds=None, # None = no client-side timeout wrapper
)
agent = LlmAgent(
name="quant",
model="gemini-4-argon", # MUST be a Gemini model — raises ValueError otherwise
instruction=(
"You are a quantitative analyst. Solve numerical problems by "
"writing and executing Python. Always show intermediate steps."
),
code_executor=executor,
)

Model check. process_llm_request calls is_gemini_model(llm_request.model) and raises ValueError("Gemini code execution tool is not supported for model {model}") for anything else. To silence the check (e.g. when routing through LiteLlm to a Gemini-compatible endpoint), set the env var ADK_DISABLE_GEMINI_MODEL_ID_CHECK=1 — is_gemini_model_id_check_disabled() reads it via is_env_enabled (any truthy string: 1, true, yes).

What actually reaches the model. Because execution happens server-side, code and output events are not emitted as function calls. Gemini returns types.Part.executable_code (the program it ran) and types.Part.code_execution_result (stdout / stderr) inline in the response content. To audit each step, walk event.content.parts and pull those two Part types out — event.get_function_calls() returns [] for built-in code execution because no tool call was invoked from the client side.

AgentEngineSandboxCodeExecutor — managed sandbox on Google Cloud

Section titled “AgentEngineSandboxCodeExecutor — managed sandbox on Google Cloud”

Runs model-written code in a Vertex AI Agent Engine code-execution sandbox, outside your process. Pass an existing agent_engine_resource_name (projects/.../locations/.../reasoningEngines/...) and the executor creates a sandbox per session; pass sandbox_resource_name to pin one; pass neither and it creates an Agent Engine for you.

from google.adk.agents import LlmAgent
from google.adk.code_executors import AgentEngineSandboxCodeExecutor
analyst = LlmAgent(
name="analyst",
model="gemini-3.8-flash",
instruction="Answer data questions by writing and running Python.",
code_executor=AgentEngineSandboxCodeExecutor(
agent_engine_resource_name="projects/my-project/locations/us-central1/reasoningEngines/123",
),
)

VertexAiCodeExecutor is deprecated in 2.13.0: Vertex AI Extensions is being retired and the Code Interpreter extension it wraps has no replacement, so ADK points to AgentEngineSandboxCodeExecutor instead. google-adk[gcp] no longer installs what it needs; existing code keeps working with google-cloud-aiplatform>=2.2,<3 installed and logs a deprecation warning. For reference, it runs code client-side via the extension and turns file output (images, CSVs, JSON) into ADK artifacts:

from google.adk.code_executors.vertex_ai_code_executor import VertexAiCodeExecutor
from google.adk.agents import LlmAgent
# ── Option A: create a fresh extension for this executor ─────────────────────
executor = VertexAiCodeExecutor(
# resource_name=None → creates a new Code Interpreter extension in your project
optimize_data_file=True, # ADK swaps inline CSVs for `data_N_M.csv` placeholders + pandas hints
stateful=True, # persist a single execution session across turns in a session
error_retry_attempts=3, # ADK retries up to N times when the response processor detects a code error
timeout_seconds=60,
)
# ── Option B: re-use one you already provisioned ─────────────────────────────
shared_executor = VertexAiCodeExecutor(
resource_name=(
"projects/123456789/locations/us-central1/extensions/9876543210"
),
stateful=True,
)
agent = LlmAgent(
name="charts",
model="gemini-4-argon",
instruction=(
"Answer with data analysis. Use pandas + matplotlib. "
"Save every chart to a PNG file — I will retrieve it as an artifact."
),
code_executor=shared_executor,
)

Output file handling (verified from _execute_code_interpreter): image outputs (.png, .jpg, .jpeg, .gif) get mime_type=image/{ext}; data outputs (.csv, .tsv, .json) get mime_type=text/{ext}; everything else falls through mimetypes.guess_type with application/octet-stream as final fallback. Each output file becomes a File on the returned CodeExecutionResult and is written to the artifact_service bound on the Runner. Retrieve them by filename with artifact_service.load_artifact(...).

Why prefer resource_name. Creating an extension on every VertexAiCodeExecutor() construction incurs a several-second cold start and creates a resource you must clean up. Provision one extension per environment (e.g. via Terraform) and pin all executors to that resource_name.

All three accept name and sub_agents via BaseAgent. Creating one emits a DeprecationWarning (the classes are marked with typing_extensions.deprecated), and they will be removed in a future release. Workflow cannot yet be an LlmAgent sub-agent, so these remain the way to put a fixed pipeline under a transferring coordinator.

from google.adk.agents import SequentialAgent, LlmAgent
draft = LlmAgent(name="drafter", instruction="Draft an essay.", output_key="draft")
polish = LlmAgent(
name="polisher",
instruction="Polish the draft in state['draft']. Return only the final text.",
)
pipeline = SequentialAgent(name="writer", sub_agents=[draft, polish])

Sub-agents run in order. State is shared across them; use output_key to pass a value forward.

from google.adk.agents import ParallelAgent, LlmAgent
algo_a = LlmAgent(name="algo_a", instruction="Answer using approach A.")
algo_b = LlmAgent(name="algo_b", instruction="Answer using approach B.")
fanout = ParallelAgent(name="multi_try", sub_agents=[algo_a, algo_b])

Sub-agents run concurrently in isolated branches. run_live is not supported (parallel_agent.py).

from google.adk.agents import LoopAgent, LlmAgent
from google.adk.tools import exit_loop
critic = LlmAgent(
name="critic",
model="gemini-3.8-flash",
instruction=(
"Here is the draft: {draft?}. If it is good enough, call exit_loop. "
"Otherwise reply with an improved draft only."
),
tools=[exit_loop], # sets actions.escalate, which ends the loop
output_key="draft",
)
loop = LoopAgent(name="refine", sub_agents=[critic], max_iterations=5)

Exit conditions: max_iterations reached, or any event with actions.escalate=True. A model cannot set that flag by itself; the exit_loop tool (or a callback or tool that sets tool_context.actions.escalate = True) does it. max_iterations=None, the default, means loop until something escalates.

LangGraphAgent bridges an existing LangGraph compiled graph into ADK’s agent system. Install langgraph and langchain-core first (pip install langgraph langchain-core). Verified in agents/langgraph_agent.py.

import asyncio
from langgraph.graph import StateGraph, MessagesState, START, END
from langgraph.checkpoint.memory import MemorySaver
from langchain_core.messages import AIMessage
from google.adk.agents.langgraph_agent import LangGraphAgent # not re-exported from google.adk.agents
from google.adk.runners import InMemoryRunner
# --- Build a minimal LangGraph ------------------------------------------------
def chatbot(state: MessagesState):
# Replace this with your actual LLM call (e.g. ChatGoogleGenerativeAI)
last = state["messages"][-1].content
return {"messages": [AIMessage(content=f"Echo: {last}")]}
builder = StateGraph(MessagesState)
builder.add_node("chatbot", chatbot)
builder.add_edge(START, "chatbot")
builder.add_edge("chatbot", END)
checkpointer = MemorySaver()
graph = builder.compile(checkpointer=checkpointer)
# --- Wrap as an ADK agent ------------------------------------------------------
agent = LangGraphAgent(
name="echo_bot",
graph=graph,
instruction="You are a helpful assistant.", # prepended as SystemMessage if graph is empty
)
async def main():
runner = InMemoryRunner(agent=agent, app_name="demo")
session = await runner.session_service.create_session(
app_name="demo", user_id="u1", session_id="s1"
)
events = await runner.run_debug("hello", user_id="u1", session_id="s1")
print(events[-1].content.parts[0].text) # "Echo: hello"
asyncio.run(main())

How it works (from agents/langgraph_agent.py):

  • When graph.checkpointer is set the agent passes only the latest user messages — the graph owns its own memory via the checkpointer, keyed by ctx.session.id as the LangGraph thread_id.
  • When there is no checkpointer, the agent passes the full conversation (user ↔ this agent only) as HumanMessage / AIMessage so the graph has context.
  • The instruction is prepended as a SystemMessage only when the graph has no prior messages yet (initial turn).
  • LangGraphAgent emits a single Event per invocation — it does not stream partial responses.

Constructor fields:

FieldTypeDefaultPurpose
namestrrequiredAgent name
graphCompiledGraphrequiredThe compiled LangGraph graph
instructionstr""System instruction injected on first turn

Gotchas:

  • sub_agents= is not supported on LangGraphAgent — it does not participate in ADK’s agent-transfer routing.
  • If you need ADK tools inside the graph, call FunctionTool.run_async from your LangGraph nodes directly; LangGraphAgent itself holds no tools= list.
  • Multi-turn with a checkpointer requires that the runner’s session id is stable across calls (it is, by default).

The deprecated shells map to Workflow like this (full details in the workflows page):

from google.adk.agents import LlmAgent
from google.adk.workflow import JoinNode, START, Workflow
draft = LlmAgent(name="drafter", model="gemini-3.8-flash", instruction="Draft an essay on the input topic.")
polish = LlmAgent(name="polisher", model="gemini-3.8-flash", instruction="Polish the essay. Return only the final text.")
algo_a = LlmAgent(name="algo_a", model="gemini-3.8-flash", instruction="Answer using approach A.")
algo_b = LlmAgent(name="algo_b", model="gemini-3.8-flash", instruction="Answer using approach B.")
# SequentialAgent([draft, polish]): each node's output is the next node's input
pipeline = Workflow(name="pipeline", edges=[(START, draft, polish)])
# ParallelAgent([algo_a, algo_b]): fan out, then join the branch outputs
fanout = Workflow(name="fanout", edges=[(START, (algo_a, algo_b), JoinNode(name="both"))])
# LoopAgent: an edge back to an earlier node with a route that exits (see the workflows page)

Use fresh agent instances. An agent that already has a parent (a sub-agent of a SequentialAgent, say) defaults to mode='chat' when placed in a workflow, and a chat-mode agent cannot take its input from a preceding node: the Workflow constructor rejects it with a validation error.

Workflow is a BaseNode, not a BaseAgent. App(root_agent=workflow) is the recommended way to wire it to a Runner.

Set sub_agents=[a, b] on a parent LlmAgent to get transfer_to_agent routing. Leave disallow_transfer_to_peers at its default (False) on the specialists if they should be able to hand over to one another without going back through the root.

2 — Produce → Validate with output_schema

Section titled “2 — Produce → Validate with output_schema”

An LlmAgent with output_schema=MyPydanticModel emits a validated structured reply. tools can be used alongside output_schema: the model may call tools during the turn and the schema applies to the final answer (for models that cannot combine the two natively, ADK adds a set_model_response tool for the final answer). Wire structured-output agents downstream via Workflow or chain output_key → prompt template ({draft} placeholders).

BuiltInPlanner delegates planning entirely to Gemini’s native thinking feature. It injects a ThinkingConfig into every LlmRequest and adds no system-prompt text (build_planning_instruction returns None). With include_thoughts=True the model’s thought=True parts are not stripped (process_planning_response is a no-op): they appear in the yielded events, so filter on part.thought before showing text in a UI or logging it. Use it on thinking-capable Gemini models; PlanReActPlanner below is the alternative for others. In a multi-agent setup you can give only the orchestrator a planner.

Source: planners/built_in_planner.py.

from google.adk.planners import BuiltInPlanner
from google.adk.agents import LlmAgent
from google.adk.tools import google_search
from google.genai import types
# ── Minimal — return the model's thoughts ─────────────────────────────────────
agent = LlmAgent(
name="thoughtful",
model="gemini-4-argon",
planner=BuiltInPlanner(
thinking_config=types.ThinkingConfig(include_thoughts=True)
),
)
# ── Less thinking (reduces latency / cost) ────────────────────────────────────
agent_light = LlmAgent(
name="light_thinker",
model="gemini-3.8-flash",
instruction="Research and summarise the topic.",
planner=BuiltInPlanner(
thinking_config=types.ThinkingConfig(
include_thoughts=True,
thinking_level=types.ThinkingLevel.LOW, # Gemini 3; older models used thinking_budget
)
),
tools=[google_search],
)

How BuiltInPlanner works (verified source built_in_planner.py):

  1. apply_thinking_config(llm_request) is called before each model call — sets llm_request.config.thinking_config. If the request already has a thinking config it is overwritten (a warning is logged).
  2. build_planning_instruction(...) returns None — no extra system instruction is prepended.
  3. process_planning_response(...) returns None — no response post-processing needed (Gemini handles it natively).

Accessing thought parts in callbacks:

async def capture_thoughts(callback_context, llm_response):
"""Log thinking tokens for debugging."""
for part in (llm_response.content.parts or []):
if getattr(part, "thought", False) and part.text:
print("[THOUGHT]", part.text[:200])
return None # don't modify the response
agent = LlmAgent(
name="transparent",
model="gemini-4-argon",
planner=BuiltInPlanner(
thinking_config=types.ThinkingConfig(include_thoughts=True)
),
after_model_callback=capture_thoughts,
)

PlanReActPlanner (no thinking-model required)

Section titled “PlanReActPlanner (no thinking-model required)”

PlanReActPlanner works with any Gemini model — it does not require thinking_config support. Instead it injects a structured prompt that instructs the model to emit planning, reasoning, action, and final-answer blocks using XML-style tags. The planner strips all content except function calls and the final answer from what is sent back to the user.

Source: planners/plan_re_act_planner.py.

from google.adk.agents import LlmAgent
from google.adk.planners import PlanReActPlanner
from google.adk.tools import google_search
agent = LlmAgent(
name="planner_agent",
model="gemini-3.8-flash",
instruction="Answer research questions with web search.",
planner=PlanReActPlanner(),
tools=[google_search],
)

What the model produces internally (never shown to the user as-is):

/*PLANNING*/
1. Use get_stock_price to look up GOOG.
2. Report the price in the final answer.
/*REASONING*/
Executing step 1.
/*ACTION*/
<function_call>get_stock_price(ticker="GOOG")</function_call>
/*REASONING*/
The tool returned a price in USD.
/*FINAL_ANSWER*/
GOOG last traded at the price the tool returned.

Tag semantics (from planners/plan_re_act_planner.py):

TagConstantPurposeShown to user
/*PLANNING*/PLANNING_TAGInitial plan in natural languageNo — marked as thought=True
/*REPLANNING*/REPLANNING_TAGRevised plan when initial plan failsNo — marked as thought=True
/*REASONING*/REASONING_TAGInline reasoning between tool callsNo — marked as thought=True
/*ACTION*/ACTION_TAGFunction call blockThe function call is executed
/*FINAL_ANSWER*/FINAL_ANSWER_TAGThe response visible to the userYes

Processing pipeline (verified source):

  1. build_planning_instruction(...) — prepends a comprehensive NL instruction block to the system prompt covering: plan format, reasoning tags, action tags, tool-use rules, and the final-answer tag requirement.
  2. After the model responds, process_planning_response(...) splits the response parts:
    • Text before the first /*FINAL_ANSWER*/ tag → marked thought=True (never reaches the user).
    • Text after /*FINAL_ANSWER*/ → returned as the visible reply.
    • Function calls → preserved and executed normally.

Multi-tool research agent:

import asyncio
from google.adk.agents import LlmAgent
from google.adk.planners import PlanReActPlanner
from google.adk.runners import InMemoryRunner
from google.adk.apps import App
from google.adk.tools import google_search
from google.genai import types
async def get_stock_price(ticker: str) -> dict:
"""Get the latest price for a stock ticker.
Args:
ticker: Stock symbol, e.g. 'GOOG'.
Returns:
A dict with price and currency.
"""
# In production: call a real market data API
return {"ticker": ticker, "price": 175.32, "currency": "USD"}
async def get_company_news(company: str) -> dict:
"""Fetch recent news about a company.
Args:
company: Full company name.
Returns:
A dict with headlines list.
"""
return {"company": company, "headlines": ["Q1 earnings beat", "New product launch"]}
analyst = LlmAgent(
name="analyst",
model="gemini-3.8-flash",
instruction=(
"You are a financial analyst. Use the available tools to research "
"companies and produce a concise investment brief."
),
planner=PlanReActPlanner(),
tools=[get_stock_price, get_company_news, google_search],
)
async def main():
app = App(name="finance", root_agent=analyst)
runner = InMemoryRunner(app=app)
session = await runner.session_service.create_session(
app_name="finance", user_id="u1"
)
async for event in runner.run_async(
user_id="u1",
session_id=session.id,
new_message=types.Content(
role="user",
parts=[types.Part(text="Give me a brief on Alphabet Inc.")]
),
):
if event.is_final_response() and event.content:
print("Brief:", "".join(p.text or "" for p in event.content.parts))
asyncio.run(main())

When to use PlanReActPlanner vs BuiltInPlanner:

PlannerRequires thinking modelLatency overheadReasoning visible in tracesCost
BuiltInPlanner(thinking_config=...)Yes (thinking-capable Gemini models, 2.5 and later)Low (native)Yes (thought parts)Thinking tokens charged separately
PlanReActPlanner()No (any Gemini model)Higher (extra output tokens)Yes (thought parts)Normal output token rate

Use PlanReActPlanner when:

  • You need structured planning on a non-thinking model, or through LiteLlm to a non-Gemini model.
  • You want the plan/reasoning explicitly tagged and capturable via callbacks.
  • You need to debug multi-step tool chains — the /*REASONING*/ blocks reveal the model’s intent at each step.

Use BuiltInPlanner when:

  • You’re using a Gemini thinking model (supports ThinkingConfig).
  • Latency matters — native thinking is faster than generating reasoning tokens.
  • You want to control reasoning effort with thinking_level (or thinking_budget on older models).

LoopAgent (or the Workflow equivalent) with a single reflective LlmAgent that rewrites state['draft'] each turn and escalates when satisfied. Use include_contents="none" on the reflective agent to avoid feeding the full history back each iteration.

ParallelAgent (or Workflow fan-out) of N candidate agents, followed by a “judge” LlmAgent that reads state['candidate_1..N'] and picks the best. Pair each candidate’s output_key to a distinct state slot.

RemoteA2aAgent calls a remote A2A-compatible agent over HTTP, exposing it as a local BaseAgent. See also MCP & A2A.

from google.adk.agents.remote_a2a_agent import RemoteA2aAgent
from google.adk.agents import LlmAgent
remote = RemoteA2aAgent(
name="remote_specialist",
agent_card="https://specialist.internal/.well-known/agent-card.json",
timeout=30.0, # seconds per request; the default is 600
)
root = LlmAgent(
name="coordinator",
model="gemini-3.8-flash",
instruction="For specialist tasks, delegate to 'remote_specialist'.",
sub_agents=[remote],
)

Authentication, file-based cards, request interceptors and task mode are covered on MCP and A2A.

ManagedAgent wraps Google’s Managed Agents API so a server-hosted agent (identified by agent_id) runs without local inference. Available from google.adk.agents (defined in agents/_managed_agent.py; re-checked against 2.13.0).

Key constraints:

  • tools must be list[types.Tool | BaseTool | RemoteMcpServer] — passing a plain callable or FunctionTool raises at runtime.
  • Interactions always stream (background=True); polling is not implemented.
  • The API is served only from the global location — enterprise clients pinned to a specific region are rejected at construction.
import asyncio
from google.adk.agents import LlmAgent, ManagedAgent
from google.adk.runners import InMemoryRunner
from google.adk.apps import App
from google.genai import types
# Server-side search agent — no local model inference
managed_search = ManagedAgent(
name="web_researcher",
description="Answers questions that need live web search.",
agent_id="antigravity-preview-05-2026", # your Managed Agent ID
mode="single_turn", # run as an inline tool of the parent; None = a transfer target
tools=[types.Tool(google_search=types.GoogleSearch())],
)
# Chat coordinator — delegates to the managed agent
root = LlmAgent(
name="coordinator",
model="gemini-3.8-flash",
instruction=(
"For questions that need up-to-date information, "
"ask 'web_researcher'. Handle everything else yourself."
),
sub_agents=[managed_search],
)
async def main():
app = App(name="demo", root_agent=root)
runner = InMemoryRunner(app=app)
session = await runner.session_service.create_session(
app_name="demo", user_id="u1"
)
async for event in runner.run_async(
user_id="u1",
session_id=session.id,
new_message=types.Content(
role="user",
parts=[types.Part(text="What are the latest AI announcements this week?")]
),
):
if event.is_final_response() and event.content:
print(event.content.parts[0].text)
asyncio.run(main())

mode='single_turn' makes the managed agent an inline single-turn tool of its parent LlmAgent, with its internal events kept in the shared session; it is the only mode supported. Leave mode=None (the default) for a sub-agent the parent transfers the conversation to.

RemoteMcpServer — pass a RemoteMcpServer instance in tools= to connect the managed agent to an HTTP-streamable MCP server running server-side. Unlike client-side McpToolset, ADK forwards the server URL and auth headers to the Managed Agents API; the API connects and executes the MCP tools without local transport overhead.

from google.adk.agents import ManagedAgent
from google.adk.tools import RemoteMcpServer
maps_mcp = RemoteMcpServer(
url="https://maps.googleapis.com/mcp/v1",
headers={"X-Goog-Api-Key": "YOUR_MAPS_API_KEY"},
)
managed_maps = ManagedAgent(
name="maps_agent",
description="Geocodes addresses and fetches directions.",
agent_id="antigravity-preview-05-2026",
tools=[maps_mcp],
)

ManagedAgent requires a Managed Agents API project allowlist. Pass api_client= to reuse a google.genai.Client you have already configured.

  • output_schema and tools can be used together: tools run during the turn and the schema applies to the final reply only.
  • global_instruction is deprecated at the agent level; use GlobalInstructionPlugin at the App level.
  • A root LlmAgent must be in mode='chat' (set for you when mode is None) or mode='task'; a root in single_turn mode raises ValueError. single_turn agents belong in Workflows. See LlmAgent modes.
  • LoopAgent.run_live is not implemented — ParallelAgent.run_live also raises NotImplementedError.
  • When a sub-agent has no model, it inherits from the nearest ancestor LlmAgent. If the root also omits model, LlmAgent.DEFAULT_MODEL (gemini-3.5-flash in 2.13.0) is used, or whatever LlmAgent.set_default_model(...) set.
  • Callables passed to tools= are wrapped as FunctionTool(func=callable) automatically. Pass an explicit FunctionTool only when you need require_confirmation=.
  • LangGraphAgent requires langchain-core and langgraph installed separately — they are not ADK dependencies.
  • RemoteA2aAgent is @a2a_experimental — import paths and wire protocol may change in future minor releases.
  • ManagedAgent.tools only accepts types.Tool, BaseTool, or RemoteMcpServer — a plain callable or FunctionTool raises a NotImplementedError at runtime because client-side tools are not supported in server-hosted execution.
  • ManagedAgent is available from google.adk.agents since 2.4.0, and needs a project with access to the Managed Agents API.