Install
pip install google-adkGoogle ADK (Python)
Google’s Agent Development Kit. Build agents on Gemini (and any LLM via google-genai / LiteLlm) with graph-based Workflow orchestration, MCP client + server, A2A protocol, and native GCP services (Vertex AI, Cloud Run, Agent Engine).
Version
v2.3.0 · June 2026 · Python 3.10+
Best for
GCP-native workloads, Gemini-first agents, Vertex AI Agent Engine.
Zero → Hero
Section titled “Zero → Hero” 1 · Introduction What ADK is, why Google built it · 10 min
2 · Core fundamentals Install, auth, first agent · 25 min
3 · Agents LlmAgent, Parallel, Loop, Sequential · 25 min
4 · Workflows Graph orchestration with @node · 30 min
5 · Tools FunctionTool, AgentTool, built-ins · 30 min
6 · Callbacks & plugins Interception points · 20 min
7 · Runner & sessions App, Runner, session services · 25 min
8 · Memory & artifacts Long-term memory + file storage · 20 min
9 · MCP & A2A Tool servers + agent handoff · 20 min
10 · Structured output Pydantic validation · 15 min
11 · Advanced Python Planners, custom tools, auth, deployment · 30 min
12 · Evaluation AgentEvaluator, EvalCase, EvalSet, metrics · 25 min
13 · IAM & security IAM roles, workload identity · 20 min
14 · Production Deployment, scaling, monitoring · 30 min
15 · Class deep dives 10 source-verified class deep dives · 40 min
16 · Class deep dives — vol. 2 6 more source-verified deep dives: RemoteA2aAgent, LangGraphAgent, AuthCredential, GcsArtifactService, PubSubToolset, SpannerToolset · 35 min
17 · Class deep dives — vol. 3 10 more source-verified deep dives: AgentTool, BuiltInPlanner, PlanReActPlanner, InMemorySessionService, VertexAiRagMemoryService, UnsafeLocalCodeExecutor, BuiltInCodeExecutor, LiteLlm, AgentEvaluator, shell agents · 45 min
18 · Class deep dives — vol. 4 10 more source-verified deep dives: LongRunningFunctionTool, LiveRequestQueue, AnthropicLlm/Claude, SqliteSessionService, ExecuteBashTool, TransferToAgentTool, VertexAiMemoryBankService, SimplePromptOptimizer, SkillRegistry/SkillToolset, ToolConfirmation · 50 min
19 · Class deep dives — vol. 5 10 more source-verified deep dives: VertexAiSessionService, VertexAiSearchTool, VertexAiCodeExecutor, APIHubToolset, ToolboxToolset, ConversationScenario, TrajectoryEvaluator, AuthConfig/AuthHandler, PreloadMemoryTool, CodeExecutorContext · 55 min
20 · Class deep dives — vol. 6 10 more source-verified deep dives: ComputerUseTool/BaseComputer (browser automation), OpenAPIToolset/RestApiTool (REST API integration), LlmEventSummarizer (context compaction), Session/State (state primitives), Event/EventActions (event system), ExampleTool (few-shot injection), GoogleSearchTool/UrlContextTool (Gemini-native search), LlmBackedUserSimulator/UserPersona (eval simulation), GEPARootAgentPromptOptimizer (GEPA prompt optimisation), EnvironmentSimulationPlugin (mock tool testing) · 60 min
21 · Class deep dives — vol. 7 10 more source-verified deep dives: InvocationContext (invocation lifecycle backbone), SetModelResponseTool (output_schema + tools pattern), DynamicNodeScheduler/ctx.run_node() (dynamic workflow scheduling), retrieval tool chain (BaseRetrievalTool/LlamaIndexRetrieval/FilesRetrieval/VertexAiRagRetrieval), FirestoreSessionService/FirestoreMemoryService, BigQueryToolset/WriteMode, LangchainTool, CrewaiTool, SlackRunner, FileArtifactService · 65 min
22 · Class deep dives — vol. 8 10 more source-verified deep dives: ReadonlyContext (dynamic instruction callables + role-based tool filtering), FunctionNode (Python functions as workflow nodes; state/node_input binding; auth gate), JoinNode/Trigger (fork/join synchronisation; edge payload), ContainerCodeExecutor (Docker sandbox), GkeCodeExecutor (GKE + gVisor; job/sandbox modes; RBAC), AgentEngineSandboxCodeExecutor (managed Vertex AI sandbox; file I/O; session reuse), ApplicationIntegrationToolset (Cloud Application Integration + Connectors; user auth), BigtableToolset/BigtableToolSettings (GoogleSQL queries; experimental), OpenAILlm (GPT-4o/o1/o3 in ADK; labs; multi-model teams) · 70 min
23 · Class deep dives — vol. 9 10 more source-verified deep dives: Gemma/Gemma3Ollama (local Gemma models via Gemini API + Ollama; GemmaFunctionCallingMixin), ContextCacheConfig/GeminiContextCacheManager (cost-reducing context cache; cache_intervals/ttl/min_tokens), DataAgentToolset (Gemini Data Analytics Agent; list/get/ask tools), DiscoveryEngineSearchTool/SearchResultMode (Vertex AI Search; CHUNKS/DOCUMENTS auto-detect; multi-datastore), GoogleMapsGroundingTool (Gemini 2.x native Maps grounding; Vertex AI only), EnterpriseWebSearchTool (enterprise-compliant web grounding; Vertex AI only), LoadMemoryTool (model-controlled on-demand memory retrieval), LoadArtifactsTool (lazy artifact injection; MIME conversion; user-scoped artifacts), exit_loop/get_user_choice_tool (LoopAgent termination + HITL option selection), multi-turn eval suite (MultiTurnTaskSuccess/ToolUseQuality/TrajectoryQuality/Safety V1 + LlmAsJudge ABC) · 75 min
24 · Class deep dives — vol. 10 10 more source-verified deep dives: Graph/Edge (workflow graph internals; routing; validate_graph), NodeRunner (per-node executor; retry backoff; HITL resume), NodeState/NodeStatus (7-state lifecycle; interrupts; run_counter), _ParallelWorker (fan-out parallel execution for list inputs; max_concurrency), ActiveStreamingTool/TranscriptionEntry (live audio agent internals; asyncio Task + LiveRequestQueue), CachePerformanceAnalyzer (13-metric cache hit-rate report; @experimental), StreamingResponseAggregator (SSE/BIDI chunk aggregation; partial FC args; thought signatures), AgentRefConfig/ArgumentConfig/CodeConfig (YAML agent config DSL; config_path vs code; @experimental), BaseAuthProvider/AuthProviderRegistry (pluggable auth extension; custom credential retrieval; @experimental), FinishTaskTool/TaskRequest/TaskResult/_DefaultTaskOutput (task delegation protocol; typed output validation; retry feedback) · 80 min
25 · Class deep dives — vol. 11 10 more source-verified deep dives: GoogleApiToolset/GmailToolset/CalendarToolset/SheetsToolset/DocsToolset/SlidesToolset/YoutubeToolset (Google API Discovery integration; OAuth2 + SA auth; tool_filter predicate), load_web_page (SSRF-protected web browsing; IP pinning; redirect-disabled; proxy-aware), UiWidget (MCP iframe rendering metadata; provider/payload schema; attaching to events from tools), _ToolNode (wrapping any BaseTool as a retryable workflow node; dict input contract; state_delta propagation), SqliteSpanExporter (local OTEL trace persistence; schema; get_all_spans_for_session; integration test pattern), RougeEvaluator / FinalResponseMatchV1 (ROUGE-1 F-measure; threshold; EvalStatus), FinalResponseMatchV2Evaluator (@experimental; LLM-as-judge; majority voting; tie → invalid), HallucinationsV1Evaluator (@experimental; two-stage segmentation + grounding; no golden required), function calling pipeline (handle_function_calls_async parallel gather; client ID adk- prefix; populate/remove helpers; auth request events; deep_merge_dicts), _ContentLlmRequestProcessor + _InstructionsLlmRequestProcessor (conversation history filtering; isolation scope; compaction; other-agent attribution; dynamic instruction injection; bypass_state_injection) · 85 min
26 · Class deep dives — vol. 12 10 more source-verified deep dives: BasePlugin/PluginManager (12-callback lifecycle + early-exit chain), ContextFilterPlugin (sliding-window context pruning), ReflectAndRetryToolPlugin (self-healing tool retry), GlobalInstructionPlugin (app-level system instructions), SaveFilesAsArtifactsPlugin (auto-upload to artifact service), MultimodalToolResultsPlugin (raw Part tool returns), DebugLoggingPlugin (YAML trace capture), RunConfig/StreamingMode/ToolThreadPoolConfig (complete runtime config + SSE patterns), AuthenticatedFunctionTool (transparent per-tool auth), FeatureName/override_feature_enabled/temporary_feature_override (feature flag system) · 88 min
27 · Class deep dives — vol. 13 10 more source-verified deep dives (2.2.0): ApigeeLlm/ApiType (enterprise Apigee proxy routing; genai + chat_completions modes; model string format), AudioCacheManager/AudioCacheConfig (live bidirectional audio buffering; flush to ArtifactService; artifact URI convention), AudioTranscriber (Cloud Speech-to-Text for live sessions; speaker merging), TranscriptionManager (input/output transcription event lifecycle; session persistence), AgentEngineSandboxComputer/VMaaS (Vertex AI Agent Engine sandbox computer; auto-provision + BYOS; snapshot restore; session-state token sharing), ParameterManagerClient (GCP Parameter Manager config retrieval; SA + ADC + token auth; regional endpoint), SecretManagerClient (GCP Secret Manager secret retrieval; same auth patterns), GcpAuthProvider/GcpAuthProviderScheme (Agent Identity IAM Connector Credentials; API key / 2-legged / 3-legged OAuth; consent polling), AgentRegistry/AgentRegistrySingleMcpToolset (Google Cloud Agent Registry; dynamic A2A + MCP discovery; telemetry destination ID), OAuth2CredentialRefresher/BaseCredentialRefresher/InMemoryCredentialService/BaseCredentialService (pluggable token refresh + storage pipeline; Redis example; custom introspection refresher) · 90 min
28 · Class deep dives — vol. 14 10 more source-verified deep dives (2.2.0): A2aAgentExecutor/A2aAgentExecutorConfig/ExecuteInterceptor (server-side A2A bridge; before/after-agent + after-event hooks; lazy runner factory), Context/ToolContext advanced API (save_artifact with custom_metadata; user: namespace; add_memory with MemoryEntry; add_session_to_memory; get_artifact_version), GcsArtifactService deep-dive (user-namespaced files; versioned history; ArtifactVersion model; custom_metadata), LlmEventSummarizer/BaseEventsSummarizer (custom prompt_template; tool-content truncation; implement-your-own compactor), EventsCompactionConfig advanced (token-threshold vs sliding-window combination; HITL safety guards), SpannerVectorStoreSettings/VectorSearchIndexSettings ANN deep-dive (APPROXIMATE_NEAREST_NEIGHBORS; tree_depth/num_leaves; additional_filter), LangGraphAgent + InMemorySaver checkpointer (multi-turn LangGraph state; custom graph state schema; sub-agent composition), Trigger use_sub_branch/isolation_scope (parallel fan-out with isolated sub-branches; state partitioning), ResumabilityConfig + rerun_on_resume (pause/resume long-running tools; idempotency table), PubSubToolset advanced (ordering_key; tool predicate filter; event-driven pipeline pattern) · 95 min
29 · Class deep dives — vol. 15 10 more source-verified deep dives (2.2.0): ReflectAndRetryToolPlugin (self-healing tool errors; configurable TrackingScope; custom extract_error_from_result), OpenAPIToolset/RestApiTool (REST API generation from OpenAPI specs; auth schemes; ssl_verify; header_provider; tool_name_prefix), ExampleTool/BaseExampleProvider (few-shot example injection via list or dynamic provider; VertexAiExampleStore), EnvironmentSimulationConfig/ToolSimulationConfig/InjectionConfig (tool environment simulation; probability-based injection; error/latency/response injection), LlmBackedUserSimulator/LlmBackedUserSimulatorConfig/UserPersona (LLM-backed user simulation; custom personas; conversation scenarios), BaseCodeExecutor/VertexAiCodeExecutor/UnsafeLocalCodeExecutor (code execution backends; stateful sessions; error retry; output files), ComputerUseTool/BaseComputer/ComputerUseToolset (computer use GUI automation; custom computer implementation; prepare hook), GEPARootAgentPromptOptimizer/SimplePromptOptimizer (GEPA/iterative prompt optimization; Sampler interface; OptimizerResult), SkillToolset/Skill/Frontmatter (skills system; dynamic tool loading; adk_additional_tools; SkillRegistry; RunSkillScriptTool), AutoTracingPlugin/DebugLoggingPlugin (OTel auto-instrumentation; YAML debug dump; ContextFilterPlugin) · 98 min
30 · Class deep dives — vol. 16 10 more source-verified deep dives (2.2.0): MCPSessionManager + StdioConnectionParams/SseConnectionParams/StreamableHTTPConnectionParams (session pooling; auto-reconnect; header providers; sampling callbacks; graceful error handling), EventsCompactionConfig (token-threshold + sliding-window strategies; pending function call / HITL safety guards; custom BaseEventsSummarizer), App advanced (events_compaction_config; resumability_config; context_cache_config; plugins; validate_app_name), BaseLlmFlow/SingleFlow/AutoFlow (LLM pipeline internals; custom request + response processors; agent-transfer mechanics), SpannerToolset full details (all 8 tools; SpannerToolSettings; SpannerVectorStoreSettings; VectorSearchIndexSettings ANN), LlamaIndexRetrieval + custom BaseRetrievalTool (multi-result override; REST-backed retrieval), A2A part converters (convert_genai_part_to_a2a_part; convert_a2a_part_to_genai_part; AdkEventToA2AEventsConverter; custom converter), GoogleTool/BaseGoogleCredentialsConfig (OAuth2/ADC/token-from-state credential patterns; @experimental), Workflow rehydration/InterceptionResult/check_interception/_ChildScanState (cross-turn replay; HITL resume; fast-forward vs re-run), AgentLoader/AgentConfig (all 4 loading patterns; single-agent mode; YAML discriminated union; name validation) · 100 min
31 · Class deep dives — vol. 17 2.2.0-verified expanded examples: LongRunningFunctionTool (async polling + terminal state), OpenAPIToolset/RestApiTool (spec-from-file; header_provider; ssl_verify), PubSubToolset (publish/pull/acknowledge; ordering_key; tool_filter), VertexAiRagRetrieval (model-native Gemini 2 path; function-call fallback), RetryConfig/workflow retry (exponential backoff + jitter formula), RemoteA2aAgent (lazy AgentCard resolution; A2A streaming), LiveRequest/LiveRequestQueue (bidirectional audio/video; send_realtime turn-taking), AuthHandler/AuthSchemes (OAuth2/OIDC consent; type hierarchy), SkillToolset/Skill/Frontmatter (correct 2.2.0 API; adk_additional_tools), GoogleSearchTool/UrlContextTool/GoogleMapsGroundingTool (Gemini 1 vs 2 injection; bypass_multi_tools_limit) · 90 min
32 · Class deep dives — vol. 18 10 source-verified deep dives (2.2.0 new classes): Context (unified ToolContext/CallbackContext; state/artifacts/memory/auth/workflow routing), AgentCardBuilder (A2A card from any agent or Workflow; skill extraction; tool/planner/code-executor skills; @a2a_experimental), to_a2a() (one-call Starlette A2A server; custom AgentCard; lifespan; agent_executor_factory; @a2a_experimental), ToolConfirmation (HITL confirmation model; hint/confirmed/payload; @experimental; request_confirmation flow), SessionContext (MCP background-task session; AnyIO CancelScope compliance; sampling callbacks; _run_guarded transport-crash detection), McpInstructionProvider (MCP Prompt → LlmAgent.instruction; state-based argument forwarding; SSE + Stdio), UiWidget (provider/payload schema; mcp iframe; custom providers; render_ui_widget), EnvironmentToolset (Execute/ReadFile/EditFile/WriteFile @experimental toolset; EnvironmentSimulationConfig; error + latency injection), LoadMcpResourceTool (lazy MCP resource injection; list_resources on every LLM call; read_resource on demand), App deep-dive (token-threshold + sliding-window compaction; ResumabilityConfig; ContextCacheConfig; plugins; validate_app_name) · 105 min
33 · Class deep dives — vol. 19 10 source-verified deep dives (2.2.0): TransferToAgentTool (enum constraint on agent_name; hallucination prevention; dynamic construction from sub-agent list), SetModelResponseTool (output_schema + tools workaround; three schema branches: BaseModel/list[BaseModel]/primitives; set_model_response action), PreloadMemoryTool (automatic memory retrieval injection; process_llm_request pattern; after_agent_callback pairing), VertexAiSearchTool (single datastore vs engine; data_store_specs multi-datastore; dynamic filter via _build_vertex_ai_search_config subclassing; bypass_multi_tools_limit), FilesRetrieval (LlamaIndex VectorStoreIndex + SimpleDirectoryReader; custom embedding model; top-K override pattern), ToolboxToolset (MCP Toolbox delegate; toolset_name + tool_names union; bound_params secrets; auth_token_getters), JoinNode (fan-in _requires_all_predecessors; dict aggregation; input_schema validation; three-way fan-out), @node decorator + FunctionNode (all 5 usage forms; retry_config; timeout; auth_config gate; rerun_on_resume), _ParallelWorker (fan-out map over list; single-item auto-wrap; max_concurrency semaphore; LlmAgent fan-out), Workflow.max_concurrency (static-node throttling; dynamic ctx.run_node() excluded; nested workflows; rerun_on_resume) · 110 min
34 · Class deep dives — vol. 20 10 source-verified deep dives (2.2.0): compaction pipeline internals (token-threshold rolling-summary seed; sliding-window worked example; HITL FC/auth guards; _safe_token_compaction_split_index; subsumption detection), inject_session_state (async template substitution; {var?} optional; {artifact.file_name} load; {artifact.file_name?} optional artifact; scope prefixes; _is_valid_state_name guard), run_llm_agent_as_node (single_turn/task/chat modes; chat dispatch loop; task-delegation FC idempotency via run_id=fc.id; FinishTaskTool FR handshake), ToolConfig+BaseToolConfig+ToolArgsConfig (5 YAML tool reference patterns; factory function contract; custom BaseToolConfig extension), RequestInput (HITL interrupt model; camelCase aliases; response_schema accepts Pydantic/generic alias/dict; stable interrupt_id for retry cycles), HITL workflow utilities (adk_request_input FC name; create_request_input_event/response; process_auth_resume 3-format dispatch), TaskResultAggregator (A2A priority state machine: failed>auth_required>input_required>working; intermediate re-write to working), retry internals (_should_retry_node attempt_count gate + exception name filter; _get_retry_delay exponential backoff formula with jitter), GoogleLLMVariant+model-name utilities+can_use_output_schema_with_tools (GOOGLE_GENAI_USE_VERTEXAI switch; extract_model_name from path strings; EAP regex + semver gating; SetModelResponseTool injection decision), SpannerAdminToolset (7 management-plane tools; tool_filter list/predicate; GoogleTool credential injection; pairs with SpannerToolset for data plane) · 115 min
35 · Class deep dives — vol. 21 10 source-verified deep dives (2.2.0): RecordingsPlugin/ReplayPlugin (YAML conformance test recording + replay; 7-callback capture; invocation_id isolation; ReplayVerificationError), StaticUserSimulator/UserSimulator/Status/NextUserMessage (scripted multi-turn eval replay; STOP_SIGNAL_DETECTED exhaustion; model_validator exclusive pairing), UserPersona/UserBehavior/UserPersonaRegistry/PreBuiltBehaviors (behavioral simulation profiles; instruction/violation-rubric text generation; enum of pre-built atomic behaviors), EvalConfig/CustomMetricConfig/_CustomMetricEvaluator (eval config DSL; _DEFAULT_EVAL_CONFIG; importlib metric loading; sync/async detection), Rubric/RubricContent/RubricScore/RubricBasedEvaluator (LLM-as-judge evaluation; DefaultAutoRaterResponseParser regex; MajorityVotePerInvocationResultsAggregator; rubric_type filtering), InteractionsRequestProcessor (Gemini Interactions API stateful chaining; reverse event scan; branch filtering; module-level singleton), _RequestConfirmationLlmRequestProcessor (4-step tool confirmation resume pipeline; two payload formats; deduplication guard), GoogleApiToOpenApiConverter (Discovery → OpenAPI 3.0.0; 4-phase convert; flatPath preference; $ref rewriting; custom discovery_url), LocalEvalService (___eval___session___ prefix; rubric propagation; duplicate rubric guard; telemetry tagging), EvaluationGenerator/_LiveSession (repeat_num sampling; BIDI audio RunConfig; 30s shutdown grace; audio transcription synthesis for text metrics) · 120 min
36 · Class deep dives — vol. 22 10 source-verified deep dives (2.3.0): GoogleSearchAgentTool/create_google_search_agent (google_search + other tools workaround; propagate_grounding_metadata=True; AgentTool sub-agent pattern), BaseCredentialExchanger/ExchangeResult/CredentialExchangeError (pluggable exchange interface; NamedTuple was_exchanged; @experimental), CredentialExchangerRegistry (dict[AuthCredentialTypes, BaseCredentialExchanger]; register/get_exchanger; @experimental), OAuth2CredentialExchanger (client credentials + auth code + PKCE code_verifier; trailing-# strip; authlib guard; short-circuit on existing token; @experimental), SessionStateCredentialService (session-state backed credential persistence; credential_key state key; security caveat; @experimental), NodeInterruptedError/NodeTimeoutError/DynamicNodeFailError (workflow error taxonomy: BaseException vs Exception; retryable timeouts; child failure wrapping), ReplaySequenceBarrier (asyncio.Event chain; first key pre-set; silent-node fast-forward; 15s timeout; RuntimeError 'Replay divergence detected'), TestSpec/UserMessage/TestCase (conformance test YAML DSL; extra=forbid; oneof text/content; state_delta per turn; category/name from folder path), AdkWebServerClient (conformance HTTP client; create_session/run_agent/update_session; SSE Event stream; _adk_recordings_config/_adk_replay_config injection; async context manager), ToolConnectionAnalyzer/ToolConnectionMap/StatefulParameter (LLM-driven tool dependency analysis; creating vs consuming tools; state_store mutation; @experimental ENVIRONMENT_SIMULATION) · 125 min
37 · Class deep dives — vol. 23 10 source-verified deep dives (2.3.0): GcsEvalSetsManager/GcsEvalSetResultsManager (GCS-backed eval set + result storage; {app}/evals/eval_sets/{id}.evalset.json path convention; bucket existence check on init; _validate_id ^[a-zA-Z0-9_]+ regex), LocalEvalSetsManager/LocalEvalSetResultsManager/convert_eval_set_to_pydantic_schema (disk-based eval storage at {agents_dir}/{app}/{id}.evalset.json; .adk/eval_history/ results; double-parse Pydantic/JSON migration strategy), MetricEvaluatorRegistry/DEFAULT_METRIC_EVALUATOR_REGISTRY (type-keyed registry of 13 built-in metrics; get_evaluator() returns fresh instance; last register_evaluator() wins), MetricInfoProvider/MetricInfo/MetricValueInfo/Interval/PrebuiltMetrics (metric metadata API; 13-member PrebuiltMetrics enum; ResponseEvaluatorMetricInfoProvider two-metric constructor arg), RubricBasedFinalResponseQualityV1Evaluator (@experimental; RUBRIC_TYPE=FINAL_RESPONSE_QUALITY; evidence-first two-pass; trusted procedurally-sound tool calls only), RubricBasedToolUseV1Evaluator (@experimental; RUBRIC_TYPE=TOOL_USE_QUALITY; STEP1-5/Property/Rationale/Verdict 5-step format; not-applicable=yes), RubricBasedMultiTurnTrajectoryEvaluator (RUBRIC_TYPE=TRAJECTORY_QUALITY; _assemble_dialogue_history USER/AGENT TURN N strings; first N-1 invocations NOT_EVALUATED; single LLM call on full context at last turn), PerTurnUserSimulatorQualityV1 (@experimental; Turn 1 exact string match vs starting_prompt; LLM judge majority vote with num_samples; ties go negative; score=fraction of valid turns), InterceptionResult/check_interception/create_mock_context (5-case workflow replay decision tree: same-turn COMPLETED fast-forward; same-turn WAITING bubble interrupts; cross-turn output/route fast-forward; cross-turn all-resolved extract responses; cross-turn no-events rerun Workflow), StreamingResponseAggregator 2.3.0 deep-dive (PROGRESSIVE_SSE_STREAMING feature flag; _parts_sequence ordered accumulation; _flush_text_buffer + _flush_function_call dual-buffer; partial_args/will_continue FC detection; JSONPath arg reconstruction; close() final aggregation) · 130 min
38 · Class deep dives — vol. 24 10 source-verified deep dives (2.3.0): LlmAgent mode system (chat/task/single_turn delegation; coordinator+task sub-agent pattern; output_schema+output_key; include_contents; model callbacks), ContextCacheConfig (@experimental; cache_intervals/ttl_seconds/min_tokens; 4096-token floor; second-turn start; create_http_options), State+StateSchemaError (delta-aware dict; app:/user:/temp: prefixes; setdefault; has_delta; Pydantic schema validation; prefixed-key bypass), DatabaseSessionService (SQLAlchemy 2.x async; SQLite/Postgres/MySQL; StaticPool for :memory:; pool_pre_ping; PRAGMA foreign_keys; stale-session error), VertexAiSessionService (Vertex AI Agent Engine; short vs full engine ID; session_id regex ^[A-Za-z0-9_-]+; Express Mode), VertexAiMemoryBankService (ingest_events vs generate_memories path selection via custom_metadata; search_memory; fire-and-forget background tasks), Event+NodeInfo (LlmResponse subclass; is_final_response(); get_function_calls(); partial; output; node_info.path/run_id/name; message/state/route convenience kwargs), EventActions+EventCompaction (state_delta; artifact_delta; transfer_to_agent; escalate; requested_auth_configs; route; render_ui_widgets; compaction start/end/content), ReadonlyContext (MappingProxyType state; user_id; agent_name; run_config; get_credential; plugin hook usage), InvocationContext (services registry: artifact/session/memory/credential; context_cache_config; invocation_id; user_content; LLM cost manager; new_invocation_context_id()) · 135 min
39 · Class deep dives — vol. 25 10 source-verified deep dives (2.3.0): FunctionTool (Pydantic arg coercion; require_confirmation bool/callable; _get_mandatory_args guard; live streaming _call_live; ignore_params contract), BaseToolset+ToolPredicate (@runtime_checkable Protocol; invocation-scoped tool cache; tool_name_prefix closure injection; _is_tool_selected list/predicate; process_llm_request hook; from_config() factory), LlmRequest (append_instructions list[str]/Content; append_tools single-Tool merge; set_output_schema BaseModel/list/dict; tools_dict exclude=True; cache_metadata threading), LlmResponse (extra=forbid+camelCase aliases; create() 4-branch factory; get_function_calls/responses; go_away GoAway signal; interaction_id chaining; model_version), GEPARootAgentOptimizer+Sampler+OptimizerResult (GEPA adapter; reflection_minibatch_size; run_dir checkpoint; Pareto-front optimized_agents; UnstructuredSamplingResult data capture; @experimental), TelemetryContext+start_as_current_node_span (frozen dataclass; add_event(); BaseAgent no-span bypass; invoke_workflow semconv 1.41; invoke_node proposed; associated_event_ids attribute), CacheMetadata (frozen=True; active vs fingerprint-only two-state invariant; expire_soon 120s buffer; __str__ summary; SHA-256[:16] fingerprint), GCSToolset+GCSAdminToolset+GCSToolSettings (Capabilities.READ_ONLY/READ_WRITE; gcs_ prefix; 6 storage + 4 admin tools; GoogleTool credential injection; @experimental), BaseAuthenticatedTool (CredentialManager.get_auth_credential(); abstract _run_async_impl(credential); response_for_auth_required; vs AuthenticatedFunctionTool; @experimental), BaseLlm (model: str; abstract generate_content_async streaming contract; 5 partial-chunk patterns; _maybe_append_user_content; connect() for BIDI; supported_models() regex for LLMRegistry) · 140 min
Jump to a topic
Section titled “Jump to a topic”Reference
Section titled “Reference” Agents LlmAgent, Parallel, Loop, Sequential (deprecated).
Workflows Workflow, @node, Edge, JoinNode.
Tools FunctionTool, AgentTool, BaseTool, BaseToolset, MCP.
Callbacks & plugins All 13 plugin hooks + agent callbacks.
Runner & sessions Runner, App, session services, RunConfig.
Memory & artifacts MemoryService + ArtifactService implementations.
MCP & A2A McpToolset, RemoteA2aAgent, to_a2a().
Evaluation AgentEvaluator, EvalCase, EvalSet, PrebuiltMetrics.
Comprehensive guide Single-page technical reference.
Advanced Python Planners, custom tools, auth, deployment.
Class deep dives 10 source-verified deep dives: LlmAgent, RunConfig, Context, BasePlugin, App, Workflow, BaseNode, FunctionTool, RetryConfig, BaseTool.
Class deep dives — vol. 2 6 more: RemoteA2aAgent, LangGraphAgent, AuthCredential, GcsArtifactService, PubSubToolset, SpannerToolset.
Class deep dives — vol. 3 10 more: AgentTool, BuiltInPlanner, PlanReActPlanner, InMemorySessionService, VertexAiRagMemoryService, UnsafeLocalCodeExecutor, BuiltInCodeExecutor, LiteLlm, AgentEvaluator, shell agents.
Class deep dives — vol. 4 10 more: LongRunningFunctionTool, LiveRequestQueue, AnthropicLlm/Claude, SqliteSessionService, ExecuteBashTool, TransferToAgentTool, VertexAiMemoryBankService, SimplePromptOptimizer, SkillRegistry/SkillToolset, ToolConfirmation.
Class deep dives — vol. 5 10 more: VertexAiSessionService, VertexAiSearchTool, VertexAiCodeExecutor, APIHubToolset, ToolboxToolset, ConversationScenario/ConversationScenarios, TrajectoryEvaluator, AuthConfig/AuthHandler, PreloadMemoryTool, CodeExecutorContext.
Class deep dives — vol. 6 10 more: ComputerUseTool/BaseComputer, OpenAPIToolset/RestApiTool, LlmEventSummarizer, Session/State, Event/EventActions/EventCompaction, ExampleTool/VertexAiExampleStore, GoogleSearchTool/UrlContextTool, LlmBackedUserSimulator/UserPersona, GEPARootAgentPromptOptimizer, EnvironmentSimulationPlugin.
Class deep dives — vol. 7 10 more: InvocationContext, SetModelResponseTool, DynamicNodeScheduler/ctx.run_node(), BaseRetrievalTool/LlamaIndexRetrieval/FilesRetrieval/VertexAiRagRetrieval, FirestoreSessionService/FirestoreMemoryService, BigQueryToolset/WriteMode, LangchainTool, CrewaiTool, SlackRunner, FileArtifactService.
Class deep dives — vol. 8 10 more: ReadonlyContext, FunctionNode, JoinNode/Trigger, ContainerCodeExecutor, GkeCodeExecutor, AgentEngineSandboxCodeExecutor, ApplicationIntegrationToolset, BigtableToolset/BigtableToolSettings, OpenAILlm (labs).
Class deep dives — vol. 9 10 more: Gemma/Gemma3Ollama, ContextCacheConfig/GeminiContextCacheManager, DataAgentToolset, DiscoveryEngineSearchTool, GoogleMapsGroundingTool, EnterpriseWebSearchTool, LoadMemoryTool, LoadArtifactsTool, exit_loop/get_user_choice_tool, multi-turn eval suite.
Class deep dives — vol. 10 10 more: Graph/Edge (workflow graph internals), NodeRunner (per-node executor), NodeState/NodeStatus (execution lifecycle), _ParallelWorker (fan-out parallel), ActiveStreamingTool/TranscriptionEntry (live audio), CachePerformanceAnalyzer (cache analytics), StreamingResponseAggregator (SSE/BIDI engine), AgentRefConfig/CodeConfig (YAML config DSL), BaseAuthProvider/AuthProviderRegistry (pluggable auth), FinishTaskTool/TaskRequest/TaskResult (task delegation protocol).
Class deep dives — vol. 11 10 more: GoogleApiToolset/GmailToolset/CalendarToolset/SheetsToolset (Google API Discovery toolsets; OAuth2 + SA auth; tool_filter), load_web_page (SSRF-protected browsing; IP pinning), UiWidget (MCP iframe rendering metadata), _ToolNode (tool-as-workflow-node; retry + timeout), SqliteSpanExporter (local OTEL tracing to SQLite; dev traces), RougeEvaluator (ROUGE-1 response match), FinalResponseMatchV2Evaluator (LLM-as-judge; majority vote), HallucinationsV1Evaluator (two-stage segmentation + grounding; no golden), function calling pipeline (parallel gather; adk- client IDs; auth events; deep_merge), _ContentLlmRequestProcessor/_InstructionsLlmRequestProcessor (history filtering; compaction; dynamic instructions).
Class deep dives — vol. 12 10 more: BasePlugin/PluginManager (12-callback lifecycle + early-exit chain), ContextFilterPlugin, ReflectAndRetryToolPlugin, GlobalInstructionPlugin, SaveFilesAsArtifactsPlugin, MultimodalToolResultsPlugin, DebugLoggingPlugin, RunConfig/StreamingMode/ToolThreadPoolConfig, AuthenticatedFunctionTool, FeatureName/feature-flag system.
Class deep dives — vol. 13 10 more (2.2.0): ApigeeLlm/ApiType (Apigee proxy; enterprise API governance), AudioCacheManager/AudioCacheConfig (live audio I/O buffering + ArtifactService flush), AudioTranscriber (Cloud Speech-to-Text; speaker merging), TranscriptionManager (transcription event lifecycle), AgentEngineSandboxComputer (VMaaS; auto-provision + BYOS; snapshot restore), ParameterManagerClient (GCP Parameter Manager), SecretManagerClient (GCP Secret Manager), GcpAuthProvider/GcpAuthProviderScheme (Agent Identity IAM Connector Credentials), AgentRegistry/AgentRegistrySingleMcpToolset (Google Cloud Agent Registry; A2A + MCP discovery), OAuth2CredentialRefresher/BaseCredentialRefresher/InMemoryCredentialService/BaseCredentialService (pluggable credential refresh + storage).
Class deep dives — vol. 14 10 more (2.2.0): A2aAgentExecutor/Config/ExecuteInterceptor (server-side A2A bridge), Context/ToolContext advanced API (save_artifact; user: namespace; add_memory; get_artifact_version), GcsArtifactService (versioned history; ArtifactVersion; custom_metadata), LlmEventSummarizer/BaseEventsSummarizer (custom prompt; tool truncation; custom compactor), EventsCompactionConfig advanced (token-threshold + sliding-window; HITL guards), SpannerVectorStoreSettings/VectorSearchIndexSettings ANN (APPROXIMATE_NEAREST_NEIGHBORS; tree_depth/num_leaves), LangGraphAgent + InMemorySaver (multi-turn checkpointer; custom state schema), Trigger use_sub_branch/isolation_scope (parallel fan-out; state partitioning), ResumabilityConfig + rerun_on_resume (pause/resume; idempotency table), PubSubToolset advanced (ordering_key; predicate filter; event-driven pipeline).
Class deep dives — vol. 15 10 more (2.2.0): ReflectAndRetryToolPlugin, OpenAPIToolset/RestApiTool, ExampleTool/BaseExampleProvider, EnvironmentSimulationConfig/ToolSimulationConfig/InjectionConfig, LlmBackedUserSimulator/UserPersona, BaseCodeExecutor/VertexAiCodeExecutor/UnsafeLocalCodeExecutor, ComputerUseTool/BaseComputer, GEPARootAgentPromptOptimizer/SimplePromptOptimizer, SkillToolset/Skill/Frontmatter, AutoTracingPlugin/DebugLoggingPlugin.
Class deep dives — vol. 16 10 more (2.2.0): MCPSessionManager + connection params (session pooling; auto-reconnect; sampling callbacks), EventsCompactionConfig (HITL safety guards; custom summariser), App advanced (all config knobs), BaseLlmFlow/SingleFlow/AutoFlow (LLM pipeline internals), SpannerToolset (all 8 tools; vector search ANN), LlamaIndexRetrieval + custom BaseRetrievalTool, A2A part converters, GoogleTool/BaseGoogleCredentialsConfig, Workflow rehydration/HITL resume, AgentLoader/AgentConfig (all 4 loading patterns).
Class deep dives — vol. 17 2.2.0-verified expanded examples: LongRunningFunctionTool, OpenAPIToolset/RestApiTool, PubSubToolset, VertexAiRagRetrieval, RetryConfig/workflow retry, RemoteA2aAgent, LiveRequest/LiveRequestQueue, AuthHandler/AuthSchemes, SkillToolset/Skill/Frontmatter, GoogleSearchTool/UrlContextTool/GoogleMapsGroundingTool.
Class deep dives — vol. 18 10 source-verified new classes (2.2.0): Context (unified ToolContext/CallbackContext; all write methods), AgentCardBuilder (A2A card; skill extraction from tools/planners/sub-agents; @a2a_experimental), to_a2a() (one-call Starlette A2A server; custom card; lifespan; @a2a_experimental), ToolConfirmation (HITL model; hint/payload; request_confirmation keyword args; @experimental), SessionContext (MCP background-task session; AnyIO compliance; sampling callbacks; _run_guarded), McpInstructionProvider (MCP Prompt → instruction; state arg forwarding), UiWidget (mcp iframe provider; render_ui_widgets; custom providers), EnvironmentToolset (Execute/ReadFile/EditFile/WriteFile @experimental toolset; EnvironmentSimulationConfig error+latency injection), LoadMcpResourceTool (lazy MCP resource injection; list + read on demand), App deep-dive (all 4 config knobs; validate_app_name; required compaction_interval+overlap_size).
Class deep dives — vol. 19 10 source-verified deep dives (2.2.0): TransferToAgentTool (enum constraint; hallucination prevention), SetModelResponseTool (output_schema + tools workaround; three schema branches), PreloadMemoryTool (automatic memory injection; process_llm_request pattern), VertexAiSearchTool (single datastore; engine + data_store_specs; dynamic filter subclassing; bypass_multi_tools_limit), FilesRetrieval (LlamaIndex local RAG; custom embedding; top-K override), ToolboxToolset (MCP Toolbox delegate; bound_params; auth_token_getters), JoinNode (fan-in; _requires_all_predecessors; three-way fan-out), @node decorator + FunctionNode (5 usage forms; retry_config; timeout; auth_config gate), _ParallelWorker (fan-out map; max_concurrency semaphore; LlmAgent fan-out), Workflow.max_concurrency (static throttling; dynamic exclusion; nested workflows).
Class deep dives — vol. 20 10 source-verified deep dives (2.2.0): compaction pipeline internals (token-threshold rolling-summary seed; sliding-window algorithm; HITL FC/auth guards; split-index orphan prevention), inject_session_state (async template substitution; {var?} optional; {artifact.file_name} load; {artifact.file_name?} optional artifact; scope prefixes), run_llm_agent_as_node (single_turn/task/chat modes; chat dispatch loop; task-delegation FC idempotency; FinishTaskTool FR handshake), ToolConfig+BaseToolConfig+ToolArgsConfig (5 YAML tool reference patterns; factory function contract), RequestInput (HITL interrupt model; camelCase aliases; response_schema polymorphism; stable interrupt_id for retry), HITL workflow utilities (adk_request_input FC constant; create_request_input_event/response; process_auth_resume 3-format dispatch), TaskResultAggregator (A2A priority state machine: failed>auth_required>input_required>working), retry internals (_should_retry_node 1-based attempt_count; _get_retry_delay exponential backoff + jitter formula), GoogleLLMVariant+model-name utilities+can_use_output_schema_with_tools (GOOGLE_GENAI_USE_VERTEXAI; extract_model_name path parsing; EAP + semver gating; SetModelResponseTool injection decision), SpannerAdminToolset (7 management-plane tools; tool_filter; GoogleTool credential injection).
Class deep dives — vol. 21 10 source-verified deep dives (2.2.0): RecordingsPlugin/ReplayPlugin (YAML conformance recording + replay; 7 callbacks; invocation_id isolation; ReplayVerificationError), StaticUserSimulator/UserSimulator/Status/NextUserMessage (scripted multi-turn replay; exclusive pairing validator), UserPersona/UserBehavior/UserPersonaRegistry/PreBuiltBehaviors (simulation profiles; atomic behaviors; violation rubrics), EvalConfig/CustomMetricConfig/_CustomMetricEvaluator (eval config DSL; importlib metric loading; sync/async support), Rubric/RubricContent/RubricScore/RubricBasedEvaluator (LLM-as-judge; regex parser; majority vote; rubric_type filtering), InteractionsRequestProcessor (Interactions API stateful chaining; reverse event scan; branch scope), _RequestConfirmationLlmRequestProcessor (4-step tool confirmation resume; two payload formats; dedup guard), GoogleApiToOpenApiConverter (Discovery → OpenAPI 3.0.0; 4-phase convert; flatPath; $ref rewriting; custom discovery_url), LocalEvalService (___eval___session___ ID prefix; rubric propagation; duplicate guard; telemetry tagging), EvaluationGenerator/_LiveSession (repeat_num sampling; BIDI audio RunConfig; 30s shutdown grace; audio transcription synthesis).
Class deep dives — vol. 22 10 source-verified deep dives (2.3.0): GoogleSearchAgentTool/create_google_search_agent (google_search + other tools workaround; sub-agent delegation; grounding metadata propagation), BaseCredentialExchanger/ExchangeResult/CredentialExchangeError (pluggable exchange interface; NamedTuple result; @experimental), CredentialExchangerRegistry (type-keyed exchanger registry; @experimental), OAuth2CredentialExchanger (client credentials + auth code + PKCE; authlib guard; @experimental), SessionStateCredentialService (session-state credential store; security caveat; @experimental), NodeInterruptedError/NodeTimeoutError/DynamicNodeFailError (workflow error taxonomy: BaseException HITL signal; retryable timeout; child failure wrapper), ReplaySequenceBarrier (asyncio.Event chain; first key pre-set; silent-node fast-forward; 15s divergence timeout), TestSpec/UserMessage/TestCase (conformance test YAML DSL; extra=forbid; per-turn state_delta), AdkWebServerClient (conformance HTTP client; SSE Event stream; record/replay config injection; async context manager), ToolConnectionAnalyzer/ToolConnectionMap/StatefulParameter (LLM-driven creating/consuming tool analysis; state_store mutation; @experimental).
Class deep dives — vol. 23 10 source-verified deep dives (2.3.0): GcsEvalSetsManager/GcsEvalSetResultsManager (GCS eval storage; bucket check on init; path conventions; _validate_id regex), LocalEvalSetsManager/LocalEvalSetResultsManager/convert_eval_set_to_pydantic_schema (disk eval storage; double-parse Pydantic/JSON migration), MetricEvaluatorRegistry/DEFAULT_METRIC_EVALUATOR_REGISTRY (13 built-in metrics; type-keyed; last-register-wins; get_evaluator() fresh instance), MetricInfo/MetricValueInfo/Interval/PrebuiltMetrics (metric metadata API; 13-member enum; ResponseEvaluatorMetricInfoProvider two-metric arg), RubricBasedFinalResponseQualityV1Evaluator (@experimental; FINAL_RESPONSE_QUALITY; evidence-first two-pass; trusted tool calls), RubricBasedToolUseV1Evaluator (@experimental; TOOL_USE_QUALITY; STEP1-5/Property/Rationale/Verdict; not-applicable=yes), RubricBasedMultiTurnTrajectoryEvaluator (TRAJECTORY_QUALITY; assembled USER/AGENT TURN N dialogue; first N-1 NOT_EVALUATED; single LLM call), PerTurnUserSimulatorQualityV1 (@experimental; Turn 1 exact match vs starting_prompt; LLM judge majority vote; ties negative; score=fraction valid turns), InterceptionResult/check_interception/create_mock_context (5-case workflow replay decision tree; same-turn vs cross-turn; fast-forward/HITL resume/rerun), StreamingResponseAggregator 2.3.0 (PROGRESSIVE_SSE_STREAMING; _parts_sequence; partial_args JSONPath FC reconstruction; close() final aggregation).
What’s new in v2.3.0 (June 2026)
Section titled “What’s new in v2.3.0 (June 2026)”- v2.3.0 (June 2026) — minor feature release. Install with
pip install google-adk. New in this release:GoogleSearchAgentTool+create_google_search_agent(google.adk.tools.google_search_agent_tool) — workaroundAgentToolsubclass that wrapsgoogle_searchin a sub-agent to allow combining native search with other custom tools in a single agent;propagate_grounding_metadata=Truepreserves search attribution in the parent’s event stream.- Credential exchange pipeline (
google.adk.auth.exchanger.*) —@experimentalpluggable exchange system:BaseCredentialExchangerABC,ExchangeResultNamedTuple,CredentialExchangerRegistry(type-keyed), andOAuth2CredentialExchangerhandling client credentials and auth code (+ PKCE) grants viaauthlib. SessionStateCredentialService(google.adk.auth.credential_service.session_state_credential_service) —@experimentalBaseCredentialServicethat persists credentials directly in session state viacallback_context.state[auth_config.credential_key]; simplest backend, not recommended for sensitive data.- Workflow error taxonomy (
google.adk.workflow._errors) —NodeInterruptedError(extendsBaseException, uncatchable by user code),NodeTimeoutError(retryable),DynamicNodeFailError(child node failure wrapper witherroranderror_node_path). ReplaySequenceBarrier(google.adk.workflow.utils._replay_sequence_barrier) — asyncio chronological ordering primitive for deterministic workflow replay; chain-unlock pattern with 15s divergence timeout.- Conformance testing infrastructure (
google.adk.cli.conformance.*) —TestSpec/UserMessage/TestCaseYAML-driven test DSL;AdkWebServerClientasync HTTP client with SSE event streaming andrecord/replaymode injection;ConformanceTestRunnerorchestrating test discovery and execution. ToolConnectionAnalyzer+ToolConnectionMap+StatefulParameter—@experimental(ENVIRONMENT_SIMULATION)LLM-driven analysis of creating vs consuming tool relationships; drivesToolSpecMockStrategyto generate realistic stateful mock responses.
What’s new in v2.2.0 (June 2026)
Section titled “What’s new in v2.2.0 (June 2026)”- v2.2.0 (June 2026) — minor feature release. Install with
pip install google-adk. New in this release:AgentEngineSandboxComputer(google.adk.integrations.vmaas) —@experimentalBaseComputerbacked by Vertex AI Agent Engine Computer Use Sandbox; auto-provision agent engines + sandboxes or bring your own; session-state resource sharing across turns and instances; snapshot + template support.AgentRegistry(google.adk.integrations.agent_registry) —@experimentalclient for Google Cloud Agent Registry; discover registered A2A agents and MCP servers;get_mcp_toolset()/get_remote_a2a_agent()helpers; telemetry destination-ID stamping viaAgentRegistrySingleMcpToolset.GcpAuthProvider+GcpAuthProviderScheme(google.adk.integrations.agent_identity) —@experimentalBaseAuthProviderbacked by IAM Connector Credentials Service; API key / 2-legged / 3-legged OAuth flows; consent polling;continue_urifor 3LO redirect.ApigeeLlm— enterprise Apigee API proxy support for Gemini and OpenAI-compatible backends;apigee/<provider>/<version>/<model>model string format;ApiType.GENAI/CHAT_COMPLETIONSauto-detection.- Core modules for live audio sessions stabilised:
AudioCacheManager,AudioTranscriber,TranscriptionManager. ParameterManagerClientandSecretManagerClientadded togoogle.adk.integrationsfor first-class GCP config/secret retrieval.
What’s new in v2.1.0 (May 2026)
Section titled “What’s new in v2.1.0 (May 2026)”- v2.1.0 (May 2026) — minor feature release. Install with
pip install google-adk. New in this release:RunConfig.tool_thread_pool_config(ToolThreadPoolConfig) — offloads tool execution to a thread pool in live/bidirectional sessions so blocking I/O doesn’t freeze the event loop.RunConfig.context_window_compression— Gemini-side sliding-window context compression (types.ContextWindowCompressionConfig).RunConfig.get_session_config— limits which events are loaded from the session store on each invocation; combine withEventsCompactionConfigfor efficient large sessions.RunConfig.enable_affective_dialog,proactivity,session_resumption— new live-mode controls.BaseNode.state_schema/input_schema/output_schema— first-class fields onBaseNode(previously only surfaced onWorkflow).Context.add_memory(memories=[...])— add explicitMemoryEntryitems directly (alongside the existingadd_session_to_memory()).BasePlugin.on_model_error_callback— formally documented as a first-class hook.- Core symbols (
Agent,LlmAgent,Runner,InMemorySessionService,FunctionTool,ToolContext,InMemoryMemoryService,InMemoryArtifactService,Workflow,BaseNode,RunConfig) verified against installedgoogle-adk==2.1.0(.routine-envs/check-0523-google-adk) with-W error::DeprecationWarning; all PASS. 27 top-level exports confirmed.
What’s new in v2.0.0 GA (May 2026)
Section titled “What’s new in v2.0.0 GA (May 2026)”- v2.0.0 (May 2026) — GA stable release.
google-adk 2.0.0is now the latest stable release on PyPI;pip install google-adk --preis no longer needed. Install withpip install google-adk. All guide content and verified snippets continue to apply unchanged. Core symbols verified against installedgoogle-adk==2.0.0(.routine-envs/check-0520-adk) with-W error::DeprecationWarning; all PASS.
What’s new in v2.0 beta (April 2026)
Section titled “What’s new in v2.0 beta (April 2026)”Workflowgraph orchestration —SequentialAgent/ParallelAgent/LoopAgentare now@deprecatedin favour ofWorkflowwith edges, routing maps, and@node.- Plugins — runner-wide interception via
BasePluginwith 11 hooks.GlobalInstructionPluginreplaces the deprecatedLlmAgent.global_instruction. - MCP client + server — full MCP support including sampling, resources, and auth schemes.
- A2A protocol —
to_a2a(agent)to publish;RemoteA2aAgentto consume. - Vertex AI Memory Bank + RAG —
VertexAiMemoryBankService,VertexAiRagMemoryService. - Built-in code executors —
BuiltInCodeExecutor,VertexAiCodeExecutor,ContainerCodeExecutor,GkeCodeExecutor,AgentEngineSandboxCodeExecutor.
Install, minimal example
Section titled “Install, minimal example”import asynciofrom google.adk.agents import LlmAgentfrom google.adk.runners import InMemoryRunner
agent = LlmAgent( name="assistant", model="gemini-2.5-flash", instruction="You are a helpful assistant.",)
async def main(): runner = InMemoryRunner(agent=agent, 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())Ready? Start Zero → Hero Step 1 →
Revision history
Section titled “Revision history”| Date | Framework version (installed) | Summary of changes | Reviewer |
|---|---|---|---|
| 2026-06-23 | google-adk 2.3.0 | Added Class deep dives — vol. 25 page (10 source-verified deep dives against google-adk==2.3.0): FunctionTool (google.adk.tools.function_tool; require_confirmation bool/callable; _preprocess_args() Pydantic/Optional/list[BaseModel] coercion; _get_mandatory_args() guard before confirmation; _call_live() for live streaming; _ignore_params = [context_param, 'input_stream']; 4 examples); BaseToolset + ToolPredicate (google.adk.tools.base_toolset; @runtime_checkable Protocol; invocation-scoped _cached_prefixed_tools; @final get_tools_with_prefix() with closure-based prefix injection; _is_tool_selected() list vs predicate dual-mode; process_llm_request() hook; from_config() factory; 4 examples); LlmRequest (google.adk.models.llm_request; tools_dict exclude=True; append_instructions() list[str] / Content paths; append_tools() single-Tool merge; set_output_schema() BaseModel/list/dict/Schema; cache_metadata + cacheable_contents_token_count fields; 4 examples); LlmResponse (google.adk.models.llm_response; extra='forbid' + camelCase alias_generator; create() 4-branch static factory; get_function_calls() / get_function_responses(); go_away LiveServerGoAway; interaction_id Interactions API chaining; model_version; 4 examples); GEPARootAgentOptimizer + Sampler + OptimizerResult (google.adk.optimization; @experimental; GEPARootAgentOptimizerConfig: optimizer_model, max_metric_calls=100, reflection_minibatch_size=3, run_dir checkpoint; Sampler ABC: sample_and_score(candidate, example_set, batch, capture_full_eval_data); UnstructuredSamplingResult.data dict; OptimizerResult.optimized_agents Pareto front; 4 examples); TelemetryContext + start_as_current_node_span (google.adk.telemetry.node_tracing; frozen dataclass; add_event() accumulates IDs; BaseAgent → no new span; Workflow → semconv 1.41 invoke_workflow; other nodes → invoke_node; gcp.vertex.agent.associated_event_ids on exit; 3 examples); CacheMetadata (google.adk.models.cache_metadata; frozen=True; active vs fingerprint-only two-state invariant _enforce_active_state_invariant; expire_soon 120s buffer; __str__ summary; SHA-256[:16] fingerprint; 3 examples); GCSToolset + GCSAdminToolset + GCSToolSettings (google.adk.integrations.gcs; @experimental; Capabilities.READ_ONLY/READ_WRITE enum; DEFAULT_GCS_TOOL_NAME_PREFIX = "gcs"; 6 storage tools + 4 admin tools; GoogleTool credential injection; 4 examples); BaseAuthenticatedTool (google.adk.tools.base_authenticated_tool; @experimental; CredentialManager.get_auth_credential() flow; abstract _run_async_impl(args, tool_context, credential); response_for_auth_required customisation; vs AuthenticatedFunctionTool; 4 examples); BaseLlm (google.adk.models.base_llm; abstract generate_content_async() streaming contract: 5 partial-chunk patterns; partial=True intermediates → partial=False final; connect() for BIDI; _maybe_append_user_content() guard; supported_models() regex for LLMRegistry; 4 examples). Index updated with Zero → Hero step 39. Library source inspected directly from installed google-adk==2.3.0. | Claude |
| 2026-06-20 | google-adk 2.3.0 | Added Class deep dives — vol. 23 page (10 source-verified deep dives against google-adk==2.3.0): GcsEvalSetsManager + GcsEvalSetResultsManager (google.adk.evaluation.gcs_eval_sets_manager; GCS-backed eval set + result storage; {app}/evals/eval_sets/{id}.evalset.json and {app}/evals/eval_history/{id}.evalset_result.json path conventions; bucket existence check on __init__; _validate_id() enforces ^[a-zA-Z0-9_]+$; 3 examples); LocalEvalSetsManager + LocalEvalSetResultsManager + convert_eval_set_to_pydantic_schema (google.adk.evaluation.local_eval_sets_manager; disk paths at {agents_dir}/{app}/{id}.evalset.json and .adk/eval_history/; double-parse Pydantic/JSON migration strategy; convert_eval_set_to_pydantic_schema handles legacy JSON → EvalSet; 3 examples); MetricEvaluatorRegistry + DEFAULT_METRIC_EVALUATOR_REGISTRY (google.adk.evaluation.metric_evaluator_registry; _registry: dict[str, tuple[type[Evaluator], MetricInfo]]; 13 built-in registered metrics; get_evaluator() returns fresh instance each call; last register_evaluator() wins; 3 examples); MetricInfoProvider + MetricInfo + MetricValueInfo + Interval + PrebuiltMetrics (google.adk.evaluation.eval_metrics; MetricInfoProvider ABC with get_metric_info(); MetricInfo name/description/metric_value_info; MetricValueInfo Interval min/max + output_type; full 13-member PrebuiltMetrics enum table; ResponseEvaluatorMetricInfoProvider takes metric_name constructor arg for two-metric support; 3 examples); RubricBasedFinalResponseQualityV1Evaluator (google.adk.evaluation.rubric_based_final_response_quality_v1; @experimental; RUBRIC_TYPE="FINAL_RESPONSE_QUALITY"; evidence-first two-pass protocol — collects evidence across full invocation then judges; trusted evidence only from procedurally sound tool calls with non-empty results; 3 examples); RubricBasedToolUseV1Evaluator (google.adk.evaluation.rubric_based_tool_use_v1; @experimental; RUBRIC_TYPE="TOOL_USE_QUALITY"; 5-step STEP1/STEP2/STEP3/STEP4/STEP5 + Property/Rationale/Verdict structured format; “not applicable” maps to “yes”; 3 examples); RubricBasedMultiTurnTrajectoryEvaluator (google.adk.evaluation.rubric_based_multi_turn_trajectory_evaluator; RUBRIC_TYPE="TRAJECTORY_QUALITY"; _assemble_dialogue_history() builds USER TURN N: / AGENT (name) TURN N: string from invocations; first N-1 invocations marked NOT_EVALUATED; single LLM call on full assembled context at last turn only; 3 examples); PerTurnUserSimulatorQualityV1 (google.adk.evaluation.simulation.per_turn_user_simulator_quality_v1; @experimental; Turn 1 exact string match vs conversation_scenario.starting_prompt; intermediate turns use LLM judge with majority vote (num_samples); "is_valid":\s*\[*[\n\s]*"*([^"\]]*)"* label regex; ties (len(negative) >= len(positive)) go negative; overall score = fraction of valid turns; 3 examples); InterceptionResult + check_interception + create_mock_context (google.adk.workflow.utils._replay_interceptor; 5-case decision tree: Case 1 same-turn COMPLETED fast-forward / same-turn WAITING bubble interrupts; Case 2 cross-turn unresolved interrupts — rerun if rerun_on_resume and progress made; Case 3 cross-turn has output/route fast-forward; Case 4 cross-turn all interrupts resolved no output — extract response or rerun; Case 5 cross-turn no events — rerun Workflow if wait_for_output, else static fast-forward; create_mock_context() builds mock Context with cached _output_value/_interrupt_ids/route; 3 examples); StreamingResponseAggregator 2.3.0 deep-dive (google.adk.utils.streaming_utils; PROGRESSIVE_SSE_STREAMING feature flag gate; _parts_sequence: list[types.Part] ordered accumulation; _flush_text_buffer_to_sequence() merges consecutive same-type text parts; _flush_function_call_to_sequence() emits completed FC part; partial_args + will_continue streaming FC detection; _get_value_from_partial_arg() + _set_value_by_json_path() JSONPath dot-notation reconstruction; _current_thought_signature preservation; all intermediate chunks marked partial=True; close() finalises _parts_sequence into non-partial LlmResponse; 3 examples). Index updated with Zero → Hero step 37, Jump-to-topic card (vol. 23), Reference card (vol. 23). Library source inspected directly from installed google-adk==2.3.0. | Claude |
| 2026-06-18 | google-adk 2.2.0 | Added Class deep dives — vol. 21 page (10 source-verified deep dives against google-adk==2.2.0): RecordingsPlugin + ReplayPlugin (google.adk.cli.plugins; 7-callback conformance recording — before_run, before_model, after_model, before_tool, after_tool, on_tool_error, after_run; _adk_recordings_config / _adk_replay_config session state keys; dual pending structures pending_llm_recordings + pending_tool_recordings; pending_recordings_order chronological list; NONE → generated-recordings.yaml / SSE → generated-recordings-sse.yaml; ReplayPlugin.before_tool_callback returns stored response directly; AgentTool bypass; per-agent agent_tool_replay_indices dict; invocation_id keyed _InvocationRecordingState/_InvocationReplayState for concurrent-run isolation; ReplayVerificationError on mismatch; 3 examples); StaticUserSimulator + UserSimulator + Status + NextUserMessage (google.adk.evaluation.simulation; @experimental; Status enum: SUCCESS / TURN_LIMIT_REACHED / STOP_SIGNAL_DETECTED / NO_MESSAGE_GENERATED; NextUserMessage model_validator exclusive pairing — user_message present iff Status.SUCCESS; StaticUserSimulator.invocation_idx integer walk + STOP_SIGNAL_DETECTED on exhaustion; UserSimulator.__init__ eager re-validation via config_type.model_validate; BaseUserSimulatorConfig camelCase + extra="allow"; get_simulation_evaluator() returns None for static; 3 examples); UserPersona + UserBehavior + UserPersonaRegistry + PreBuiltBehaviors (@experimental; UserBehavior.get_behavior_instructions_str() formats as " * {instruction}\n" per item; get_violation_rubrics_str() same format; UserPersonaRegistry.get_persona() raises NotFoundError (not KeyError); get_default_persona_registry() used by string persona auto-resolution; key PreBuiltBehaviors members: ADVANCE_DETAIL_ORIENTED, ADVANCE_GOAL_ORIENTED, ANSWER_RELEVANT_ONLY, ANSWER_ALL, CORRECT_AGENT, DO_NOT_CORRECT_AGENT, TROUBLESHOOT_ONCE, END_LIMITED_TROUBLESHOOTING; 3 examples); EvalConfig + CustomMetricConfig + _CustomMetricEvaluator (google.adk.evaluation.eval_config; _DEFAULT_EVAL_CONFIG = EvalConfig(criteria={"tool_trajectory_avg_score": 1.0, "response_match_score": 0.8}); get_evaluation_criteria_or_default(path) file-or-default loader; CustomMetricConfig.code_config.name split on last . for importlib; inspect.iscoroutinefunction sync/async dispatch; camelCase alias_generator + populate_by_name=True; user_simulator_config field; 3 examples); Rubric + RubricContent + RubricScore + RubricBasedEvaluator (google.adk.evaluation; @experimental; DefaultAutoRaterResponseParser — 3 regex patterns: (?<=Property: )(.*), (?<=Rationale: )(.*), (?<=Verdict: )(.*); "yes" → 1.0 / "no" → 0.0 / else → None; MajorityVotePerInvocationResultsAggregator reduces noise; MeanInvocationResultsSummarizer final score; rubric_type field filtering; _normalized_rubric_to_id_map lowercase+strip; create_effective_rubrics_list + get_effective_rubrics_list; 3 examples); InteractionsRequestProcessor (google.adk.flows.llm_flows.interactions_processor; activation guard: isinstance(model, Gemini) and model.use_interactions_api; reverse event scan for most recent event.author == agent_name with event.interaction_id; branch filtering _is_event_in_branch; sets llm_request.previous_interaction_id; module-level singleton request_processor; pure preprocessing — no events yielded; 3 examples); _RequestConfirmationLlmRequestProcessor (google.adk.flows.llm_flows.request_confirmation; step 1 — scan for last user event and parse adk_request_confirmation FC responses; step 2 — _resolve_confirmation_targets extracts originalFunctionCall arg; two payload formats: direct dict and {"response": json_string}; step 3 — dedup already-executed FCs after confirmation event; step 4 — handle_function_call_list_async with agent.canonical_tools(); module-level singleton; REQUEST_CONFIRMATION_FUNCTION_CALL_NAME = "adk_request_confirmation"; 3 examples); GoogleApiToOpenApiConverter (google.adk.tools.google_api_tool.googleapi_to_openapi_converter; __init__(api_name, api_version, *, discovery_url=None); fetch_google_api_spec() populates _google_api_resource._rootDesc; convert() orchestrates _convert_info, _convert_servers (rootUrl+servicePath), _convert_security_schemes (OAuth2 + API key), _convert_schemas; _convert_methods uses flatPath with path fallback; any type → oneOf primitives; # fragment refs rewritten to #/components/schemas/; consumed by GoogleApiToolset; 3 examples); LocalEvalService (google.adk.evaluation.local_eval_service; @experimental; EVAL_SESSION_ID_PREFIX = "___eval___session___" + UUID4; default InMemorySessionService + InMemoryArtifactService; _copy_eval_case_rubrics_to_actual_invocations + _copy_invocation_rubrics_to_actual_invocations; _add_rubrics_to_invocation raises ValueError on duplicate rubric_id; EVAL_CLIENT_LABEL telemetry tagging; eval_set_results_manager optional persistence; semaphore-bounded concurrent inference; 3 examples); EvaluationGenerator + _LiveSession (google.adk.evaluation.evaluation_generator; EvalCaseResponses.responses: list[list[Invocation]] — outer=repeat_num, inner=turns; _LiveSession async context manager: live_request_queue, event_queue: asyncio.Queue, turn_complete_event: asyncio.Event, live_finished: asyncio.Event, consume_task; live RunConfig uses StreamingMode.BIDI, response_modalities=["AUDIO"], AudioTranscriptionConfig for input+output; __aexit__ 30s grace period; ConnectionClosedOK + APIError code 1000 swallowed; audio transcriptions synthesised as text Content events for text-based metrics; EvaluationGenerator static-only class; 3 examples). Index updated with Zero → Hero step 35, Jump-to-topic card (vol. 21), Reference card (vol. 21). Library source inspected directly from installed google-adk==2.2.0. | Claude |
| 2026-06-17 | google-adk 2.2.0 | Added Class deep dives — vol. 20 page (10 source-verified deep dives against google-adk==2.2.0): compaction pipeline internals (apps.compaction; _run_compaction_for_token_threshold_config — rolling-summary seed event; _safe_token_compaction_split_index orphan-prevention backward scan; _pending_function_call_ids call−response set diff; _is_compaction_subsumed identical-range dedup; _run_compaction_for_sliding_window worked example with compaction_interval=2/overlap_size=1; both strategies run simultaneously; token-threshold fires first; 3 examples including dry-run inspector + custom BulletSummarizer); inject_session_state (utils.instructions_utils; async regex substitution via _async_sub; {var} required vs {var?} optional; {artifact.file_name} async load; scope-prefixed keys; _is_valid_state_name guard — non-identifier patterns returned verbatim; 3 examples including per-language instruction and state-name validation demo); run_llm_agent_as_node (workflow._llm_agent_wrapper; 4-way mode dispatch table; _node_input_to_content type dispatch; chat mode outer dispatch loop with step-1 pre-LLM FC scan + step-2 while-True re-entry; _dispatch_task_fc with run_id=fc.id idempotency + override_isolation_scope=fc.id; task mode finish_task FR handshake; 3 examples covering single_turn, task, and chat modes); ToolConfig + BaseToolConfig + ToolArgsConfig (tools.tool_configs; 5 YAML reference patterns from source docstring: built-in, instance, class, factory function, function tool; extra="allow" on ToolArgsConfig vs extra="forbid" on BaseToolConfig; factory function signature (args: ToolArgsConfig) → BaseTool; custom DatabaseToolConfig extension; 3 examples with YAML snippets); RequestInput (events.request_input; interrupt_id UUID default; payload custom UI context; message display string; response_schema accepts type[BaseModel]/generic alias/raw dict; camelCase aliases via alias_generator; stable interrupt_id for rejection/retry cycles; 3 examples including typed list schema and retry-cycle pattern); HITL workflow utilities (workflow.utils._workflow_hitl_utils; REQUEST_INPUT_FUNCTION_CALL_NAME='adk_request_input' constant; 8-function table; create_request_input_event / create_request_input_response builder pair; process_auth_resume 3-format fallback chain: AuthConfig dict → AuthCredential dict → plain value; _build_auth_message auth-type dispatch; has_auth_credential state probe; 3 examples); TaskResultAggregator (a2a.executor.task_result_aggregator; @a2a_experimental; 4-level priority machine: failed > auth_required > input_required > working; intermediate events re-written to working to prevent premature A2A stream termination; process_event state machine; 3 examples including state-machine simulation and failed-is-terminal demo); retry internals (workflow.utils._retry_utils; _should_retry_node: attempt_count is 1-based, >= max_attempts gate, exception name list filter; _get_retry_delay formula: initial_delay × backoff_factor^(attempt_count−1), min(delay, max_delay), random.uniform(-jitter×delay, +jitter×delay); delay table for defaults; 3 examples including delay simulation with seed=42); GoogleLLMVariant + model-name utilities + can_use_output_schema_with_tools (utils.variant_utils / model_name_utils / output_schema_utils; GOOGLE_GENAI_USE_VERTEXAI env switch; extract_model_name Vertex AI path / Apigee path / models/ prefix patterns; is_gemini_eap_or_2_or_above EAP regex + packaging.version.Version semver check; can_use_output_schema_with_tools — LiteLlm always True; Vertex AI + Gemini 2+ True; else False → SetModelResponseTool injected; 3 examples including runtime backend check + agent construction pattern); SpannerAdminToolset (tools.spanner.admin_toolset; @experimental(FeatureName.SPANNER_ADMIN_TOOLSET); 7 management-plane tools table; tool_filter list or ToolPredicate; GoogleTool wrapping for ADC credential injection; all tools return {"status": "SUCCESS"/"ERROR"}; complements SpannerToolset for data plane; 3 examples including read-only filter and combined admin+data agent). Index updated with Zero → Hero step 34, Jump-to-topic card (vol. 20), Reference card (vol. 20). Library source inspected directly from installed google-adk==2.2.0 in /tmp/adk-env. | Claude |
| 2026-06-07 | google-adk 2.2.0 | Added Class deep dives — vol. 14 page (10 source-verified deep dives against google-adk==2.2.0): A2aAgentExecutor + A2aAgentExecutorConfig + ExecuteInterceptor (@a2a_experimental server-side bridge; exposes any ADK Runner as an A2A endpoint; lazy async runner factory; before_agent request auth gate; after_event event filtering + mutation; after_agent terminal-status stamping; 5 full examples); Context / ToolContext advanced API (save_artifact with custom_metadata; load_artifact(version=N) pinned-version load; list_artifacts; get_artifact_version returning ArtifactVersion; user: namespace cross-session persistence; add_memory(memories=[MemoryEntry(...)]) explicit memory injection; add_session_to_memory() LLM-extracted session memory; 3 full examples); GcsArtifactService deep-dive (blob naming scheme {app}/{user}/{session}/{file}/{version} vs {app}/{user}/user/{file}/{version}; user-namespace user: prefix; list_versions; get_artifact_version with canonical_uri/create_time/custom_metadata; ArtifactVersion dataclass; stringified metadata caveat; 3 full examples); LlmEventSummarizer + BaseEventsSummarizer (default prompt template source; _MAX_TOOL_CONTENT_CHARS=2000 truncation; _format_events_for_prompt thought + tool-call rendering; custom KeyPointSummarizer with no LLM; custom prompt template; EventCompaction construction in maybe_summarize_events; wiring via EventsCompactionConfig.summarizer; 2 full examples); EventsCompactionConfig advanced (sliding-window vs token-threshold trigger comparison table; dual-mode simultaneous activation; token count estimation from usage_metadata + chars÷4 fallback; _truncate_events_before_pending_function_call + _truncate_events_before_hitl_signal safety guards; event_retention_size=0 collapse-all mode; 2 full examples with persistence); SpannerVectorStoreSettings + VectorSearchIndexSettings (complete 15-field table; EXACT_NEAREST_NEIGHBORS vs APPROXIMATE_NEAREST_NEIGHBORS; VectorSearchIndexSettings: tree_depth 2 vs 3; num_leaves=rows÷1000; num_branches for 3-level tree; additional_key_columns + additional_storing_columns for pre-filtering; additional_filter SQL WHERE fragment; ANN vs exact comparison table; 3 full examples including 3-level tree for 200M rows); LangGraphAgent + LangGraph InMemorySaver checkpointer (_get_messages branching: checkpointer set → send only last user messages; checkpointer None → full conversation; ADK session.id as LangGraph thread_id; instruction injection only on first turn; CompiledGraph non-Pydantic arbitrary_types_allowed; multi-turn memory example; custom AgentState TypedDict with search_count; sub-agent composition pattern; gotchas: blocking invoke(), instruction reappear on state clear; 3 full examples); Trigger — use_sub_branch + isolation_scope (field reference: input, use_sub_branch, branch, isolation_scope; ser_json_bytes='base64'; fan-out with sub-branches isolation; isolation_scope for per-branch temp: state partitioning; aggregate sub-branch results; 3 full examples); ResumabilityConfig + rerun_on_resume (is_resumable=True; DatabaseSessionService requirement; LongRunningFunctionTool pausing; rerun_on_resume=True on workflow nodes restarts node from scratch vs saved output; idempotency decision table; workflow node integration; 2 full examples); PubSubToolset advanced (ordering_key + enable_message_ordering=bool(ordering_key) publisher option from source; tool predicate ToolPredicate for dynamic tool exposure; producer/consumer agent pair; full pull-process-acknowledge loop; pull_messages return schema; ordering key for regional ordering; Gotchas: sync pull limitation; subscription ordering requirement). Index updated with Zero → Hero step 28, Jump-to-topic cards (vol 12 + 14), Reference cards (vol 12 + 14). Vol. 12 also added to navigation (previously missing). Library source inspected directly from installed google-adk==2.2.0. | Claude |
| 2026-06-05 | google-adk 2.2.0 | Added Class deep dives — vol. 13 page (10 source-verified deep dives against google-adk==2.2.0): ApigeeLlm + ApiType (enterprise Apigee proxy routing; apigee/<provider>/<version>/<model> string format; GENAI vs CHAT_COMPLETIONS auto-detection; custom_headers; custom credentials scope; multi-model failover pattern); AudioCacheManager + AudioCacheConfig (live bidirectional audio buffering on InvocationContext; cache_audio(cache_type='input'/'output'); flush_caches() combines chunks → ArtifactService → Event with FileData ref; artifact://…/_adk_live/… URI convention; get_cache_stats(); max_cache_size_bytes/auto_flush_threshold); AudioTranscriber (Cloud Speech-to-Text wrapper; init_client lazy vs eager; transcribe_file() merges same-speaker blobs; handles mixed Blob + Content cache entries); TranscriptionManager (converts types.Transcription to session Event; handle_input_transcription / handle_output_transcription; comparison table vs AudioTranscriber); AgentEngineSandboxComputer (@experimental BaseComputer backed by Vertex AI Agent Engine Sandbox; auto-provision + BYOS modes; session-state resource sharing via _STATE_KEY_* constants; sandbox_template_name / sandbox_snapshot_name for fast boot; IAM role table); ParameterManagerClient (GCP Parameter Manager; SA JSON / auth token / ADC auth; get_parameter() with render_parameter_version; regional endpoint; vs SecretManagerClient comparison table); SecretManagerClient (GCP Secret Manager; same three auth patterns; get_secret(); regional endpoint; caching wrapper pattern); GcpAuthProvider + GcpAuthProviderScheme (@experimental; BaseAuthProvider backed by IAM Connector Credentials Service; type_='gcpAuthProviderScheme'; scopes + continue_uri; API key / 2-legged / 3-legged OAuth flows; NON_INTERACTIVE_TOKEN_POLL_TIMEOUT_SEC; _construct_auth_credential Bearer vs custom-header; IAM_CONNECTOR_CREDENTIALS_TARGET_HOST env override); AgentRegistry + AgentRegistrySingleMcpToolset (@experimental; AGENT_REGISTRY_BASE_URL; list_mcp_servers / get_mcp_toolset with IAM-binding auto-resolution + GcpAuthProviderScheme; list_agents / get_remote_a2a_agent with transport-binding filter; list_endpoints / get_model_name; AgentRegistrySingleMcpToolset stamps GCP_MCP_SERVER_DESTINATION_ID on tools for OTel tracing); OAuth2CredentialRefresher + BaseCredentialRefresher + InMemoryCredentialService + BaseCredentialService (@experimental pluggable credential refresh + storage; is_refresh_needed() via authlib.OAuth2Token.is_expired(); refresh() ABC; InMemoryCredentialService._credentials[app_name][user_id][key] bucket structure; save_credential / load_credential; CredentialRefresherRegistry; Redis-backed service example; custom introspection refresher example; architecture diagram). Index updated with Zero → Hero step 26, Jump-to-topic card, Reference card, version bump to 2.2.0, and “What’s new in v2.2.0” section. Library source inspected directly from PyPI google-adk==2.2.0. | Claude |
| 2026-06-03 | google-adk 2.1.0 | Added Class deep dives — vol. 11 page (10 source-verified deep dives): GoogleApiToolset + GmailToolset/CalendarToolset/SheetsToolset/DocsToolset/SlidesToolset/YoutubeToolset (Google API Discovery integration; api_name/api_version constructor; OAuth2 + ServiceAccount auth; tool_filter list or predicate; set_tool_filter(); tool_name_prefix for collision avoidance; configure_auth() / configure_sa_auth() post-init reconfiguration; arbitrary-API pattern via GoogleApiToolset directly); load_web_page (SSRF-protected web browsing; scheme allowlist; _is_blocked_hostname + _is_blocked_address; _PinnedAddressAdapter IP-pinning with TLS SNI preservation; allow_redirects=False; proxy-aware path; BeautifulSoup text extraction; 3-word line filter); UiWidget (camelCase Pydantic model; id/provider/payload fields; MCP iframe 'mcp' provider payload schema; attaching widgets from tools via tool_context.actions.ui_widgets; reading from event stream; JSON round-trip with by_alias=True); _ToolNode (wrapping any BaseTool as a workflow node; name=tool.name default; retry_config/timeout; rerun_on_resume=False; dict-or-None input contract; state_delta propagation; multi-ToolNode pipeline example); SqliteSpanExporter (OTEL SpanExporter backed by SQLite; db_path lazy init; CREATE TABLE IF NOT EXISTS schema with session_id/invocation_id columns; export() batch insert; get_all_spans_for_session() trace-tree query; threading.Lock safety; integration test pattern); RougeEvaluator / FinalResponseMatchV1 (ROUGE-1 F-measure; unigram overlap; stemming; threshold → EvalStatus.PASSED/FAILED; aggregation by mean; when-to-use table vs v2); FinalResponseMatchV2Evaluator (@experimental; LLM-as-judge; structured prompt with user/agent/golden; valid/invalid label; majority voting — ties → invalid; num_samples config); HallucinationsV1Evaluator (@experimental; two-stage segmentation + validation pipeline; context construction from tool definitions + history; supported/not_applicable/not_supported classification; accuracy = grounded sentences / total; no golden required; comparison table); function calling pipeline (AF_FUNCTION_CALL_ID_PREFIX = 'adk-'; generate_client_function_call_id(); populate_client_function_call_id(); remove_client_function_call_id() strips IDs before LLM; handle_function_calls_async parallel asyncio.gather + cancel-on-failure; sync tool thread pool via _call_tool_in_thread_pool; build_auth_request_event for adk_request_credential HITL flow; deep_merge_dicts + merge_parallel_function_response_events); _ContentLlmRequestProcessor + _InstructionsLlmRequestProcessor (include_contents full vs none; isolation scope + branch + empty content + compaction + invisible-part filter pipeline; other-agent attribution "[agent_name] said:"; async function response reordering; static + callable instructions; state variable injection {var}; bypass_state_injection flag; dynamic instruction → user Content before last user message). Index updated with Zero → Hero step 25, Jump-to-topic card, and Reference card. Library source inspected directly from PyPI google-adk==2.1.0. | Claude |
| 2026-06-02 | google-adk 2.1.0 | Added Class deep dives — vol. 10 page (10 source-verified deep dives): Graph/Edge (from_edge_items() compilation; RouteValue/DEFAULT_ROUTE routing semantics; 7-check validate_graph() pipeline — duplicate names, START presence, reachability, duplicate edges, default-route constraints, unconditional-cycle detection, static schema mismatch; _terminal_node_names computation; get_next_pending_nodes() runtime routing); NodeRunner (per-node executor lifecycle; _create_child_context branch + isolation-scope setup; _attempt_retry exponential backoff gate; use_as_output/prior_output/prior_interrupt_ids HITL resume; OTel span wrapping); NodeState + NodeStatus (7-state enum lifecycle: INACTIVE → RUNNING → COMPLETED/WAITING/FAILED/CANCELLED; attempt_count/interrupts/resume_inputs/run_counter/run_id/parent_run_id; exclude_if minimal serialisation); _ParallelWorker (fan-out: wraps any BaseNode; max_concurrency slot-filling loop; FIRST_COMPLETED wait; index-ordered results; any-task-failure → cancel-all); ActiveStreamingTool + TranscriptionEntry (live audio agent state: asyncio.Task + LiveRequestQueue per streaming tool call; TranscriptionEntry.role = user/model/None; Blob vs Content data; custom streaming tool pattern); CachePerformanceAnalyzer (@experimental; 13-metric report: cache_hit_ratio_percent, cache_utilization_ratio_percent, avg_cached_tokens_per_request, cache_refreshes; reads event.cache_metadata/usage_metadata; agent_name=None global view); StreamingResponseAggregator (SSE/BIDI chunk aggregation engine; _current_text_buffer text-type merging before flush; _current_fc_args JSONPath accumulation via _set_value_by_json_path; will_continue=False FC flush; _current_thought_signature preservation; avoiding duplicate text in SSE display); AgentRefConfig + ArgumentConfig + CodeConfig (@experimental YAML agent config DSL; config_path vs code mutual exclusion; CodeConfig.name runtime importlib resolution; tool/callback YAML patterns with args; load_agent_from_config()); BaseAuthProvider + AuthProviderRegistry (@experimental pluggable auth; get_auth_credential() ABC; supported_auth_schemes for 1-param registration; registry.get_provider() scheme-type or instance lookup; GCP Secret Manager custom provider example); FinishTaskTool + TaskRequest + TaskResult + _DefaultTaskOutput (task delegation protocol; _wrapper_key object/primitive schema branching; $defs hoisting; “Do NOT call finish_task prematurely” injected instruction; TypeAdapter validation with retry feedback; _DefaultTaskInput goal/background; camelCase aliases). Index updated with Zero → Hero step 24, Jump-to-topic card, and Reference card. Library source inspected directly from PyPI google-adk==2.1.0. | Claude |
| 2026-06-01 | google-adk 2.1.0 | Added Class deep dives — vol. 9 page (10 source-verified deep dives): Gemma/Gemma3Ollama/GemmaFunctionCallingMixin (local Gemma model support via Gemini API or Ollama; function-calling workarounds via system-instruction injection + JSON extraction); ContextCacheConfig/GeminiContextCacheManager (context caching on App; cache_intervals/ttl_seconds/min_tokens; 4096-token minimum; hash-based invalidation); DataAgentToolset/DataAgentToolConfig/DataAgentCredentialsConfig (Gemini Data Analytics Agent integration; list_accessible_data_agents/get_data_agent_info/ask_data_agent; max_query_result_rows); DiscoveryEngineSearchTool/SearchResultMode (Vertex AI Search; CHUNKS/DOCUMENTS auto-detection; single-datastore and multi-engine patterns); GoogleMapsGroundingTool (Gemini 2.x native Maps grounding; Vertex AI only; model built-in); EnterpriseWebSearchTool (enterprise-compliant grounded web search; Vertex AI only; Gemini 2.x); LoadMemoryTool (model-controlled on-demand memory retrieval; instruction injection; PreloadMemoryTool vs LoadMemoryTool comparison); LoadArtifactsTool (lazy artifact injection into LLM context; MIME-type handling table; user-scoped user: prefix artifacts); exit_loop/get_user_choice_tool (exit_loop sets escalate=True + skip_summarization=True; get_user_choice_tool is a LongRunningFunctionTool HITL gate); multi-turn eval suite (MultiTurnTaskSuccessV1Evaluator/MultiTurnToolUseQualityV1Evaluator/MultiTurnTrajectoryQualityV1Evaluator/SafetyEvaluatorV1 — all Vertex Gen AI Eval SDK backed; LlmAsJudge ABC for custom judges). Index updated with Zero → Hero step 23, Jump-to-topic card, and Reference card. Library source inspected directly from PyPI google-adk==2.1.0. | Claude |
| 2026-05-31 | google-adk 2.1.0 | Added Class deep dives — vol. 8 page (10 source-verified deep dives): ReadonlyContext (dynamic instruction callables; role-based BaseToolset.get_tools() filtering; MappingProxyType state; get_credential()); FunctionNode (Python function/generator as workflow node; parameter_binding='state'/'node_input'; Pydantic type coercion; auth_config HITL gate; schema inference); JoinNode + Trigger (fork/join synchronisation barrier; _requires_all_predecessors; aggregated node_input passthrough; Trigger edge payload with use_sub_branch/isolation_scope); ContainerCodeExecutor (Docker container execution; image or docker_path; stateless frozen fields; exec_run with demux=True; atexit cleanup); GkeCodeExecutor (GKE gVisor-sandboxed Jobs; job/sandbox executor_type; resource limits/security context; RBAC table; TTL garbage collection; Watch API); AgentEngineSandboxCodeExecutor (Vertex AI Agent Engine managed sandbox; 3 init paths; session state sandbox_name reuse; file I/O; STATE_RUNNING health check); ApplicationIntegrationToolset (Application Integration triggers + Integration Connector entity/action tools; SA/ADC auth; authOverrideEnabled user auth; entity_operations dict; tool_name_prefix); BigtableToolset + BigtableToolSettings (7 built-in tools; experimental decorator; max_query_result_rows; GoogleSQL via execute_sql; tool filter patterns); OpenAILlm labs (gpt-.*/o1-.*/o3-.* model patterns; LLMRegistry.register; tool call accumulation; structured output via json_schema strict=True; multi-model Gemini+GPT team example). Index updated with Zero → Hero step 22, Jump-to-topic card, and Reference card. Library source inspected directly from PyPI google-adk==2.1.0. | Claude |
| 2026-05-30 | google-adk 2.1.0 | Added Class deep dives — vol. 7 page (10 source-verified deep dives): InvocationContext (lifecycle backbone: invocation → agent_call → step; 30+ fields; end_invocation, branch, isolation_scope, event queue, LLM call cost manager); SetModelResponseTool (output_schema + tools workaround; dynamic function declaration from schema; BaseModel / list[BaseModel] / primitive support); DynamicNodeScheduler/ctx.run_node() (fresh/cached/waiting three-path scheduler; DynamicNodeRun / DynamicNodeState dataclasses; ReplaySequenceBarrier for chronological replay); retrieval tool chain (BaseRetrievalTool → LlamaIndexRetrieval → FilesRetrieval/VertexAiRagRetrieval; Gemini 2.x native RAG path; gemini-embedding-2-preview default); FirestoreSessionService + FirestoreMemoryService (Firestore document hierarchy; per-session asyncio locking; keyword extraction pipeline; add_session_to_memory batch writes); BigQueryToolset/BigQueryToolConfig/WriteMode (11 BQ tools; BLOCKED/PROTECTED/ALLOWED write modes; maximum_bytes_billed, job_labels); LangchainTool (StructuredTool vs BaseTool dispatch; run_manager ignored; args_schema → accurate declaration); CrewaiTool (**kwargs dispatch; name sanitisation spaces→underscore; mandatory arg error string pattern); SlackRunner (AsyncApp integration; channel_id-thread_ts session strategy; Thinking… → chat_update pattern); FileArtifactService (directory hierarchy; ArtifactVersion model; _file_uri_to_path; per-file asyncio lock; user-scoped vs session-scoped). Index updated with Zero → Hero step 21, Jump-to-topic card, and Reference card. Library source inspected directly from PyPI google-adk==2.1.0. | Claude |
| 2026-05-29 | google-adk 2.1.0 | Added Class deep dives — vol. 6 page (10 source-verified deep dives): ComputerUseTool/ComputerUseToolset/BaseComputer (coordinate normalisation, safety confirmation, adapt_computer_use_tool); OpenAPIToolset/RestApiTool (full constructor params, multi-spec prefixing, OAuth2 + header_provider, SSL config); LlmEventSummarizer/BaseEventsSummarizer (EventsCompactionConfig integration, custom prompt, custom summariser implementation); Session/State (scope prefixes app: / user: / temp:, delta tracking, schema validation, StateSchemaError); Event/EventActions/EventCompaction (full field tables, convenience constructor kwargs, streaming pattern, state-delta event); ExampleTool/Example/BaseExampleProvider/VertexAiExampleStore (static few-shot, custom provider, Vertex AI semantic retrieval); GoogleSearchTool/UrlContextTool/GoogleSearchAgentTool (Gemini 1.x vs 2.x behaviour, search + custom tools pattern via GoogleSearchAgentTool); LlmBackedUserSimulator/UserPersona/UserBehavior (persona + behavior config, custom template); GEPARootAgentPromptOptimizer (GEPA algorithm walkthrough, run_dir resumability, comparison with SimplePromptOptimizer); EnvironmentSimulationPlugin/EnvironmentSimulationConfig/ToolSimulationConfig (mock strategies, error injection, historical trace seeding). Index updated with Zero → Hero step 20 and new reference card. Library source inspected directly from PyPI google-adk==2.1.0. | Claude |
| 2026-05-28 | google-adk 2.1.0 | Added Class deep dives — vol. 5 page (10 source-verified deep dives): VertexAiSessionService (full method table, 3 patterns: numeric ID / full resource name / Express Mode); VertexAiSearchTool (data store, search engine + multi-spec, dynamic filter via subclass override); VertexAiCodeExecutor (new + existing extension resource, comparison table vs other executors); APIHubToolset (all-ops load, name filter, OAuth2 credential); ToolboxToolset (PostgreSQL, bound params, AlloyDB with Identity token); ConversationScenario + ConversationScenarios + ConversationGenerationConfig (manual construction, AgentEvaluator integration, LLM-generated scenarios); TrajectoryEvaluator + ToolTrajectoryCriterion (EXACT / IN_ORDER / ANY_ORDER with examples + string coercion); AuthConfig + AuthHandler (all 5 AuthCredentialTypes, API key / OAuth2 client-credentials / bearer / service account examples, OAuth2 flow summary diagram); PreloadMemoryTool (cross-session memory injection, InMemoryMemoryService + VertexAiMemoryBankService, prompt injection format); CodeExecutorContext (all 10 methods, callback inspector, input file injection, custom RetryingCodeExecutor). Index updated with Zero → Hero step 19 and new reference card. Library installed and source inspected directly from PyPI google-adk==2.1.0. | Claude |
| 2026-05-27 | google-adk 2.1.0 | Source-verified source deep-dives for 10 classes added directly to the core guide files (not a new page). IAM & Auth guide rewritten from stub (23 lines) to comprehensive 594-line reference: full IAM role table, service account setup, Workload Identity, AuthenticatedFunctionTool with API-key / OAuth2 / bearer / client-credentials patterns, Secret Manager integration. Runner & Sessions expanded (+359 lines): DatabaseSessionService deep dive with all 4 supported backends (SQLite, PostgreSQL, MySQL, Spanner), connection pool tuning, concurrent write / stale-session handling, schema version migration; SqliteSessionService standalone section with schema, CRUD examples, state scope survival table. Tools expanded (+368 lines): AuthenticatedFunctionTool (source-verified constructor + 4 auth patterns) and ExecuteBashTool/BashToolPolicy (constructor, fields, validation order, security notes). Agents expanded (+130 lines): BuiltInPlanner source walkthrough + capture_thoughts callback example; PlanReActPlanner tag constants from source + multi-tool research agent example + when-to-use table. Evaluation expanded (+133 lines): AgentEvaluator internal flow description, find_config_for_test_file, end-to-end multi-turn example with result capture. Callbacks & Plugins expanded (+153 lines): all 7 built-in plugins documented with source-verified constructors — LoggingPlugin, DebugLoggingPlugin, ReflectAndRetryToolPlugin (with custom failure detection), GlobalInstructionPlugin (dynamic instruction), SaveFilesAsArtifactsPlugin, ContextFilterPlugin, MultimodalToolResultsPlugin, BigQueryAgentAnalyticsPlugin; combined multi-plugin example showing recommended ordering. Library installed and source inspected directly from PyPI google-adk==2.1.0. | Claude |
| 2026-05-26 | google-adk 2.1.0 | Added Class deep dives — vol. 4 page (10 source-verified deep dives: LongRunningFunctionTool, LiveRequestQueue/LiveRequest with 3 patterns, AnthropicLlm/Claude with ThinkingConfig mapping + multi-model team, SqliteSessionService with all 4 state scopes, ExecuteBashTool with BashToolPolicy, TransferToAgentTool with routing comparison table, VertexAiMemoryBankService with direct memory search, SimplePromptOptimizer with config guide, SkillRegistry/Skill/SkillToolset with custom registry pattern, ToolConfirmation with HITL approval gate). Library installed and source inspected directly from PyPI. Index updated with Zero → Hero step 18 and new reference cards. | Claude |
| 2026-05-25 | google-adk 2.1.0 | Added Class deep dives — vol. 3 page (10 source-verified deep dives: AgentTool with 4 patterns, BuiltInPlanner, PlanReActPlanner with comparison table, InMemorySessionService with state scoping, VertexAiRagMemoryService, UnsafeLocalCodeExecutor, BuiltInCodeExecutor with comparison table, LiteLlm with 6 provider examples, AgentEvaluator with pytest integration, LoopAgent/ParallelAgent/SequentialAgent with Workflow migration). Library installed and source inspected directly from PyPI. Index updated with Zero → Hero step 17 and new reference card. | Claude |
| 2026-05-24 | google-adk 2.1.0 | Added Class deep dives — vol. 2 page (6 source-verified deep dives: RemoteA2aAgent, LangGraphAgent, AuthCredential with all 5 auth types, GcsArtifactService, PubSubToolset, SpannerToolset). Library installed and source inspected directly from PyPI. Index updated with Zero → Hero step 16 and new reference card. | Claude |
| 2026-05-23 | google-adk 2.1.0 | Version bump to 2.1.0; added Class deep dives page (10 source-verified deep dives: LlmAgent, RunConfig/StreamingMode/ToolThreadPoolConfig, Context/ToolContext, BasePlugin, App/EventsCompactionConfig/ResumabilityConfig, Workflow, BaseNode/Node, FunctionTool, RetryConfig, BaseTool); updated “What’s new” section with 2.1.0 features; index version card, Aside, and deep dives navigation updated. Core symbols verified against installed google-adk==2.1.0 (.routine-envs/check-0523-google-adk); all PASS. | Claude |
| 2026-05-20 | google-adk 2.0.0 | GA stable release. Install command updated pip install google-adk --pre → pip install google-adk; version card updated v2.0.0b1 → v2.0.0; Aside tip updated to note stable status; “What’s new in v2.0.0 GA” section added. Core symbols verified against installed google-adk==2.0.0 (.routine-envs/check-0520-adk) with -W error::DeprecationWarning; Agent, LlmAgent, Runner, InMemorySessionService, FunctionTool, ToolContext, InMemoryMemoryService, InMemoryArtifactService all PASS. | Claude routine |
| 2026-05-20 | google-adk 2.0.0 | Added Evaluation page (AgentEvaluator, EvalCase, EvalSet, PrebuiltMetrics, rubric eval, custom metrics, pytest integration). Rewrote Advanced Python page (BuiltInPlanner, PlanReActPlanner, custom BasePlanner, BaseTool, BaseToolset, authenticated tools, HITL, Cloud Run deploy, OTEL). Expanded Tools page with BaseTool, BaseToolset, and ToolContext API sections. Updated index navigation. | Claude routine |
| 2026-04-22 | google-adk 2.0.0b1 | Added 7 topic pages: Agents, Workflows, Tools, Callbacks & Plugins, Runner & Sessions, Memory & Artifacts, MCP & A2A. Verified against installed source. Fixed errata in Advanced Python quickstart. Index rewired with new Zero → Hero and Reference grid. | Claude routine |
| 2026-04-21 | google-adk 1.31.0 | Index redesigned with Zero → Hero + Jump-to-topic grid. | — |
| April 17, 2026 | google-adk 1.31.0 | A2A; MCP; expanded tools; Workload Identity. | — |
| November 2025 | google-adk 1.18.0 | Initial documented version. | — |
Note: Other languages: Go · TypeScript.