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.
Minimal example
Section titled “Minimal example”import asynciofrom google.adk.agents import LlmAgentfrom 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.
Agent types at a glance
Section titled “Agent types at a glance”| Class | Module | Purpose | Status |
|---|---|---|---|
LlmAgent | google.adk.agents | LLM-backed; uses tools= + sub_agents= for orchestration | Stable |
SequentialAgent | google.adk.agents | Runs sub-agents in sequence | Deprecated → Workflow |
ParallelAgent | google.adk.agents | Runs sub-agents concurrently | Deprecated → Workflow |
LoopAgent | google.adk.agents | Runs sub-agents in a loop until escalate or max_iterations | Deprecated → Workflow |
LangGraphAgent | google.adk.agents.langgraph_agent | Wraps a compiled LangGraph graph as a BaseAgent | Stable (concept) |
RemoteA2aAgent | google.adk.agents.remote_a2a_agent | Calls 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.
LlmAgent
Section titled “LlmAgent”Pydantic model. Constructor accepts every field as a kwarg.
from google.adk.agents import LlmAgentfrom google.adk.tools import google_searchfrom 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):
| Field | Type | Default | Notes |
|---|---|---|---|
name | str | required | Identifier; used for agent-transfer routing |
model | str | BaseLlm | "" | Empty inherits; built-in default is gemini-3.5-flash (DEFAULT_MODEL) |
instruction | str | InstructionProvider | "" | Supports {state_key} placeholders resolved from session state |
global_instruction | same | "" | Deprecated → use GlobalInstructionPlugin |
static_instruction | types.ContentUnion | None | For context-cache friendly prefixes |
tools | list[Callable | BaseTool | BaseToolset] | [] | Callables are auto-wrapped as FunctionTool |
generate_content_config | types.GenerateContentConfig | None | Temperature, safety, thinking, etc. |
mode | 'chat' | 'task' | 'single_turn' | None | None | A root LlmAgent must be 'chat' (the default) or 'task' |
input_schema / output_schema | Pydantic model / schema | None | output_schema and tools can be used together |
output_key | str | None | Writes final text to session.state[key] |
include_contents | 'default' | 'none' | 'default' | 'none' → stateless single-turn |
planner | BasePlanner | None | BuiltInPlanner forwards thinking_config to the model |
code_executor | BaseCodeExecutor | None | See code executors |
disallow_transfer_to_parent / disallow_transfer_to_peers | bool | False | Governs agent-transfer reachability |
before_model_callback / after_model_callback / on_model_error_callback | fn or list | None | See callbacks-and-plugins |
before_tool_callback / after_tool_callback / on_tool_error_callback | fn or list | None | Same |
before_agent_callback / after_agent_callback | fn or list | None | Inherited 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 LlmAgentfrom 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, ) ),)Model resolution
Section titled “Model resolution”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 goagent = 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 processLlmAgent.set_default_model("gemini-4-argon")Dynamic instructions
Section titled “Dynamic instructions”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 LlmAgentfrom 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_instructiondoes not automatically create an explicit cache entry. Explicit cache management requiresContextCacheConfigat theApplevel.static_instructionsimply optimises the prompt layout so Gemini’s implicit (automatic) cache can recognise the fixed prefix as a stable cache key.
LlmAgent modes
Section titled “LlmAgent modes”The mode field controls dispatch behaviour, agent-transfer eligibility, and how content history is handled. It matters most when placing agents inside a Workflow.
| Mode | Dispatch style | Transfer tools | include_contents default | Valid placement |
|---|---|---|---|---|
'chat' | Continuous conversation loop | Injected (if sub_agents set) | 'default' (full history) | Root LlmAgent; first node after START in a Workflow |
None | Resolved by context | — | — | Root LlmAgent (runner → 'chat'); Workflow node (build_node() → 'single_turn') |
'single_turn' | One LLM call, then exit | Not injected | 'none' (stateless) | Any Workflow node; build_node() default |
'task' | Multi-round work that ends with a finish_task call | Not 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 rootLlmAgent, butbuild_node()resolves it to'single_turn'when the agent is placed inside aWorkflow. Amode='task'agent works as a staticWorkflownode: it is offered afinish_tasktool, keeps going until it calls it, and the validated arguments become the node’s output. ARemoteA2aAgentin task mode is the exception: it is only supported in tool-delegation mode, not as a standalone node.
mode='chat' — conversational root agent
Section titled “mode='chat' — conversational root agent”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 asynciofrom google.adk.agents import LlmAgentfrom google.adk.runners import InMemoryRunnerfrom google.adk.apps import Appfrom 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 asynciofrom google.adk.agents import LlmAgentfrom google.adk.workflow import Workflow, STARTfrom google.adk.runners import InMemoryRunnerfrom 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), staticWorkflownodes, or dispatched withctx.run_node().
import asynciofrom pydantic import BaseModel, Fieldfrom google.adk.agents import LlmAgentfrom google.adk.runners import InMemoryRunnerfrom google.adk.apps import Appfrom 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 asynciofrom google.adk.agents import LlmAgentfrom google.adk.workflow import Workflow, node, STARTfrom google.adk.apps import Appfrom google.adk.runners import InMemoryRunnerfrom 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 ────────────────────────────@nodedef 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 ───────────────────────────────────@nodedef 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.
Transfer and routing
Section titled “Transfer and routing”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).
Code executors
Section titled “Code executors”Set code_executor= on an LlmAgent to let the model run code:
| Executor | Where it runs | Extra install |
|---|---|---|
BuiltInCodeExecutor | Gemini-side (safe, sandboxed) | none |
UnsafeLocalCodeExecutor | current Python process | none — unsafe |
AgentEngineSandboxCodeExecutor | Vertex AI Agent Engine code sandbox | none beyond Google Cloud credentials |
ContainerCodeExecutor | Local Docker container | google-adk[extensions] |
GkeCodeExecutor | GKE pod | google-adk[extensions] |
CloudRunSandboxCodeExecutor | Cloud Run sandbox (google.adk.integrations.cloud_run) | Google Cloud credentials |
VertexAiCodeExecutor | Vertex AI Code Interpreter extension | Deprecated; 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:
| Field | Default | Purpose |
|---|---|---|
optimize_data_file | False | Pull CSV files out of the request and hand them to the executor |
stateful | False | Keep interpreter state across code blocks |
error_retry_attempts | 2 | Consecutive code errors tolerated before giving up |
code_block_delimiters | ```tool_code and ```python fences | How code blocks are found in model output |
execution_result_delimiters | ```tool_output fence | How results are fed back to the model |
timeout_seconds | None | Wall-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 subprocessfrom google.adk.code_executors import BaseCodeExecutorfrom 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 BuiltInCodeExecutorfrom 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 LlmAgentfrom 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 — deprecated
Section titled “VertexAiCodeExecutor — deprecated”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 VertexAiCodeExecutorfrom 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.
Deprecated shell agents (still supported)
Section titled “Deprecated shell agents (still supported)”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.
SequentialAgent
Section titled “SequentialAgent”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.
ParallelAgent
Section titled “ParallelAgent”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).
LoopAgent
Section titled “LoopAgent”from google.adk.agents import LoopAgent, LlmAgentfrom 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
Section titled “LangGraphAgent”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 asynciofrom langgraph.graph import StateGraph, MessagesState, START, ENDfrom langgraph.checkpoint.memory import MemorySaverfrom langchain_core.messages import AIMessagefrom google.adk.agents.langgraph_agent import LangGraphAgent # not re-exported from google.adk.agentsfrom 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.checkpointeris set the agent passes only the latest user messages — the graph owns its own memory via the checkpointer, keyed byctx.session.idas the LangGraphthread_id. - When there is no checkpointer, the agent passes the full conversation (user ↔ this agent only) as
HumanMessage/AIMessageso the graph has context. - The
instructionis prepended as aSystemMessageonly when the graph has no prior messages yet (initial turn). LangGraphAgentemits a singleEventper invocation — it does not stream partial responses.
Constructor fields:
| Field | Type | Default | Purpose |
|---|---|---|---|
name | str | required | Agent name |
graph | CompiledGraph | required | The compiled LangGraph graph |
instruction | str | "" | System instruction injected on first turn |
Gotchas:
sub_agents=is not supported onLangGraphAgent— it does not participate in ADK’s agent-transfer routing.- If you need ADK tools inside the graph, call
FunctionTool.run_asyncfrom your LangGraph nodes directly;LangGraphAgentitself holds notools=list. - Multi-turn with a checkpointer requires that the runner’s session id is stable across calls (it is, by default).
Migration to Workflow
Section titled “Migration to Workflow”The deprecated shells map to Workflow like this (full details in the workflows page):
from google.adk.agents import LlmAgentfrom 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 inputpipeline = Workflow(name="pipeline", edges=[(START, draft, polish)])
# ParallelAgent([algo_a, algo_b]): fan out, then join the branch outputsfanout = 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.
Patterns
Section titled “Patterns”1 — Specialists with a triage parent
Section titled “1 — Specialists with a triage parent”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).
3 — ReAct via BuiltInPlanner
Section titled “3 — ReAct via BuiltInPlanner”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 BuiltInPlannerfrom google.adk.agents import LlmAgentfrom google.adk.tools import google_searchfrom 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):
apply_thinking_config(llm_request)is called before each model call — setsllm_request.config.thinking_config. If the request already has a thinking config it is overwritten (a warning is logged).build_planning_instruction(...)returnsNone— no extra system instruction is prepended.process_planning_response(...)returnsNone— 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 LlmAgentfrom google.adk.planners import PlanReActPlannerfrom 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):
| Tag | Constant | Purpose | Shown to user |
|---|---|---|---|
/*PLANNING*/ | PLANNING_TAG | Initial plan in natural language | No — marked as thought=True |
/*REPLANNING*/ | REPLANNING_TAG | Revised plan when initial plan fails | No — marked as thought=True |
/*REASONING*/ | REASONING_TAG | Inline reasoning between tool calls | No — marked as thought=True |
/*ACTION*/ | ACTION_TAG | Function call block | The function call is executed |
/*FINAL_ANSWER*/ | FINAL_ANSWER_TAG | The response visible to the user | Yes |
Processing pipeline (verified source):
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.- After the model responds,
process_planning_response(...)splits the response parts:- Text before the first
/*FINAL_ANSWER*/tag → markedthought=True(never reaches the user). - Text after
/*FINAL_ANSWER*/→ returned as the visible reply. - Function calls → preserved and executed normally.
- Text before the first
Multi-tool research agent:
import asynciofrom google.adk.agents import LlmAgentfrom google.adk.planners import PlanReActPlannerfrom google.adk.runners import InMemoryRunnerfrom google.adk.apps import Appfrom google.adk.tools import google_searchfrom 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:
| Planner | Requires thinking model | Latency overhead | Reasoning visible in traces | Cost |
|---|---|---|---|---|
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
LiteLlmto 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(orthinking_budgeton older models).
4 — Reflection loop
Section titled “4 — Reflection loop”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.
5 — Parallel multi-try with a judge
Section titled “5 — Parallel multi-try with a judge”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
Section titled “RemoteA2aAgent”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 RemoteA2aAgentfrom 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
Section titled “ManagedAgent”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:
toolsmust belist[types.Tool | BaseTool | RemoteMcpServer]— passing a plain callable orFunctionToolraises at runtime.- Interactions always stream (
background=True); polling is not implemented. - The API is served only from the
globallocation — enterprise clients pinned to a specific region are rejected at construction.
import asynciofrom google.adk.agents import LlmAgent, ManagedAgentfrom google.adk.runners import InMemoryRunnerfrom google.adk.apps import Appfrom google.genai import types
# Server-side search agent — no local model inferencemanaged_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 agentroot = 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 ManagedAgentfrom 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],)
ManagedAgentrequires a Managed Agents API project allowlist. Passapi_client=to reuse agoogle.genai.Clientyou have already configured.
Gotchas
Section titled “Gotchas”output_schemaandtoolscan be used together: tools run during the turn and the schema applies to the final reply only.global_instructionis deprecated at the agent level; useGlobalInstructionPluginat theApplevel.- A root
LlmAgentmust be inmode='chat'(set for you whenmodeisNone) ormode='task'; a root insingle_turnmode raisesValueError.single_turnagents belong inWorkflows. See LlmAgent modes. LoopAgent.run_liveis not implemented —ParallelAgent.run_livealso raisesNotImplementedError.- When a sub-agent has no
model, it inherits from the nearest ancestorLlmAgent. If the root also omitsmodel,LlmAgent.DEFAULT_MODEL(gemini-3.5-flashin 2.13.0) is used, or whateverLlmAgent.set_default_model(...)set. - Callables passed to
tools=are wrapped asFunctionTool(func=callable)automatically. Pass an explicitFunctionToolonly when you needrequire_confirmation=. LangGraphAgentrequireslangchain-coreandlanggraphinstalled separately — they are not ADK dependencies.RemoteA2aAgentis@a2a_experimental— import paths and wire protocol may change in future minor releases.ManagedAgent.toolsonly acceptstypes.Tool,BaseTool, orRemoteMcpServer— a plain callable orFunctionToolraises aNotImplementedErrorat runtime because client-side tools are not supported in server-hosted execution.ManagedAgentis available fromgoogle.adk.agentssince 2.4.0, and needs a project with access to the Managed Agents API.