You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds Class Deep Dives Vol. 4 (google_adk_class_deep_dives_vol4.md) — 10 classes source-verified against google-adk 2.9.2, covering areas absent from or underrepresented in earlier guides.
Bumps "latest release" banners across five existing Python guide files from 2.9.0 → 2.9.2.
Updates the index Python card (v2.8.0 → v2.9.2) and adds a revision history entry.
- Replace result.best_agent / result.best_agent_with_scores with the
correct OptimizerResult.optimized_agents list access:
result.optimized_agents[0].optimized_agent (SimplePromptOptimizer)
max(result.optimized_agents, key=…).optimized_agent (GEPA)
The OptimizerResult model exposes a Pareto-front list, not a single
best_agent field (source-verified against data_types.py).
- Fix Sampler abstract interface and InMemorySampler: get_train_example_ids
and get_validation_example_ids are synchronous (not async); only
sample_and_score is async (source-verified against sampler.py).
Addresses Copilot review finding on PR #345.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGnEndeZKTPaUENwFn69fQ
This constructor and the examples below do not match the ADK sampler API documented elsewhere in this repository: LocalEvalSampler is configured with LocalEvalSamplerConfig (including eval_config, app_name, and train/validation eval-set names), not a single eval_set_file path. As written, both LocalEvalSampler(eval_set_file=...) calls will raise an unexpected-keyword TypeError; please show the actual config-based construction and eval-set layout.
Skill example uses an unsupported constructor shape
The Skill shape shown here is incompatible with the repository's documented ADK API: existing examples construct it with a required name and a SkillFrontmatter object (tools.md:1393-1412), rather than a dict frontmatter plus a resources list. Consequently the Skill(...) call at line 755 omits required data and will not construct the model. Please document the actual model and use Skill.from_directory(...) or the supported constructor.
This describes a skill as a standalone frontmatter Markdown file, but the documented ADK model uses a skill directory containing SKILL.md plus optional resource directories, and Skill.from_directory(...) handles that layout (tools.md:1385-1385, tools.md:1442-1450). As written, the file format and loader below do not represent the actual SkillToolset input and will mislead readers into creating unsupported skill objects.
Use an async SQLite URL for DatabaseSessionService
This end-to-end Runner example uses DatabaseSessionService(db_url="sqlite:///sessions.db"), but the ADK session service uses SQLAlchemy's async engine and requires an async driver; the repository's working SQLite examples use sqlite+aiosqlite:///... (runner-and-sessions.md:313-316). This snippet will fail during service initialization unless the URL is changed to an async SQLite URL (and the async dependency is installed).
PreloadMemoryTool behavior is described incorrectly
PreloadMemoryTool is not callable by the agent and does not inject memory only at session start: it runs automatically before each LLM call when explicitly added to the agent. The existing memory guide documents this behavior (memory-and-artifacts.md:65-80), so this comment is misleading about when and how memory is loaded.
…view
All fixes source-verified against google-adk 2.9.2:
LocalEvalSampler (§1, §2, §4):
- Constructor is LocalEvalSampler(config, eval_sets_manager), not a file path.
Updated all three call sites to use LocalEvalSamplerConfig + EvalConfig +
LocalEvalSetsManager(agents_dir=...). Added eval-set directory layout docs.
Skill / SkillRegistry (§7, §8):
- frontmatter: Frontmatter (typed model), not dict[str, Any].
- resources: Resources() (model with references/assets/scripts), not list.
- Fixed class structure snippet, load_skill_from_file example, and
InMemorySkillRegistry construction to use Frontmatter + Resources.
- Added Frontmatter, Resources to import lines.
SkillToolset (§9):
- Clarified: toolset exposes list_skills/load_skill/load_skill_resource/
run_skill_script/search_skills — not one tool per skill file.
- Replaced incorrect skills_folder-only example with correct skills=[...]
usage (skills_folder requires environment; without it use Skill objects).
- Fixed filtering and namespacing examples to use skills=[...].
- Noted skills_folder raises ValueError without environment.
VertexAiRagMemoryService (§10):
- Runner does not auto-call add_session_to_memory; fixed chat() to reload
the updated session and call it explicitly after runner.run().
- PreloadMemoryTool: marked as automatic (process_llm_request), not
model-callable; added after_agent_callback pattern as an alternative.
- Fixed troubleshooting row: remove "called after session ends" claim.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGnEndeZKTPaUENwFn69fQ
The reason will be displayed to describe this comment to others. Learn more.
Copilot review overview
🟡 Changes recommended
Several documentation examples contain incorrect schemas, API usage, async behavior, and database configuration, and Vol. 4 is not linked from the Python index.
Get a fresh assessment by requesting another Copilot review.
- SkillToolset §9: tool_filter predicate signature corrected from
(skill_name: str) to (tool: BaseTool, context: ReadonlyContext | None),
matching BaseToolset._is_tool_selected call site. Imports updated to
google.adk.tools.base_toolset.ReadonlyContext.
- VertexAiRagMemoryService troubleshooting: "increase vector_distance_threshold"
corrected to "lower vector_distance_threshold" — the field is a maximum
distance so lower = stricter (fewer results).
- Dismissed Codex finding that project/location were invalid params:
source-verified both are present in the constructor.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGnEndeZKTPaUENwFn69fQ
- LocalEvalSampler §4: correct eval set directory layout.
Files are flat <eval_set_id>.evalset.json under agents/<app_name>/,
not a per-case sub-directory tree. Updated both the layout diagram
and the example JSON to reflect the actual EvalSet Pydantic schema
(eval_set_id + eval_cases[]; conversation entries use final_response
not reference). Updated inline comments in the code example.
- VertexAiRagMemoryService §10: fix SQLite dialect in DatabaseSessionService
example. async SQLAlchemy requires sqlite+aiosqlite:// not sqlite://.
- SkillRegistry §8 GCS example: wrap blocking list_blobs/download_as_text
calls in asyncio.to_thread so they don't block the event loop.
Two Codex findings dismissed as incorrect after source verification:
- VertexAiRagMemoryService project/location params: both ARE present in
the constructor (__init__ params confirmed via inspect.signature).
- SkillToolset skills_folder/environment: both ARE valid constructor params;
skills_folder requires an absolute path and environment must be set
(raises ValueError otherwise). Skill.from_directory does not exist.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGnEndeZKTPaUENwFn69fQ
The eval sets live directly under agents/<app_name>/, not under an
eval/ sub-directory. The earlier layout fix updated the diagram and
the train/validation inline comments but missed the introductory
comment above LocalEvalSetsManager construction.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGnEndeZKTPaUENwFn69fQ
The tool_filter list is an inherited BaseToolset filter over generated tool names, not skill names. write-unit-test is a skill name and does not match tools such as list_skills/load_skill, so this example will not expose the intended skill-management tools (and cannot hide only review-pr). Please show a tool-name allowlist or explain that per-skill filtering is not provided here.
- SkillRegistry §8: search_skills return type corrected from list[Skill]
to list[Frontmatter] in the abstract interface, GCSSkillRegistry, and
InMemorySkillRegistry, matching the actual abstract method signature.
Returns s.frontmatter for each matching skill. Added Frontmatter to
GCS import.
- VertexAiRagMemoryService §10: add PreloadMemoryTool to the wiring
example agent so it actually retrieves stored memories before each LLM
call. Without this the memory_service stores conversations but the
agent can never recall them.
- Sampler §3: replace custom SimpleResult dataclass with the SDK's
UnstructuredSamplingResult (which has scores + data). Handle the
capture_full_eval_data flag by populating data["outputs"] when true;
this is required by GEPARootAgentOptimizer's reflection step.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGnEndeZKTPaUENwFn69fQ
…ns to 2.9.2
The Python card declared google-adk 2.9.2 as current while the Class &
API reference still showed 2.8.0 as latest and pinned examples to
>=2.8.0. Updated the header banner and both install pin examples
(pip install and requirements.txt) in google_adk_comprehensive_guide.md
to 2.9.2. Revised history entry in index.mdx updated to include this
file in the list of banner changes.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGnEndeZKTPaUENwFn69fQ
The comment 'available inside the skill's sub-agent' was incorrect:
there is no skill sub-agent, and tools in the additional_tools pool are
not exposed immediately. They only surface when a currently-activated
skill's frontmatter lists the tool name in metadata.adk_additional_tools.
Added prose explaining the activation-gated mechanism and a SKILL.md
frontmatter snippet showing the required adk_additional_tools field.
Source-verified against SkillToolset._resolve_additional_tools_from_state
in google-adk 2.9.2.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGnEndeZKTPaUENwFn69fQ
… example
Two issues in the SkillToolset additional_tools documentation:
1. Constructor table row still described additional_tools as tools for
"the skill's sub-agent" — corrected to describe the activation-gated
pool mechanic (unlocked per-skill via metadata.adk_additional_tools).
2. SKILL.md frontmatter example was missing the required description
field (Frontmatter.description: str is non-optional per source).
Added a description string to make the example loadable.
Both verified against google-adk 2.9.2 skills/models.py.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGnEndeZKTPaUENwFn69fQ
The tool_filter field description omits search_skills, even though the section below states that this management tool is exposed when registry is set and can be filtered. Readers following this table may not realize it is another valid allowlist entry; include search_skills in the listed management tool names (or explicitly qualify the list as conditional on a registry).
The constructor reference table listed only four management tool names
(list_skills, load_skill, load_skill_resource, run_skill_script) but
omitted search_skills, which is registered when registry is set and is
a valid allowlist entry. Added it with a parenthetical noting the
registry condition.
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGnEndeZKTPaUENwFn69fQ
Re-checked against an installed google-adk==2.9.2:
- Sampler/InMemorySampler: keep SDK defaults (batch=None, capture=False)
and handle batch=None, which SimplePromptOptimizer's final validation
relies on; use run_async in async examples
- SkillToolset: prefix "coding" yields coding_list_skills (BaseToolset
joins with "_"); skills_folder example no longer passes both
environment and code_executor (mutually exclusive); keyword-only
signature and real parameter types
- SkillRegistry: keyword-only get_skill/search_skills, get_skill raises
instead of returning None, search_tool_description defaults to None
- Point to load_skill_from_dir/load_skills_from_dir instead of a
hand-written SKILL.md parser
- TelemetryConfig: StrictBool and Literal field types
- UrlContextTool: describe the real model check instead of invented
source; mention the ready-made google.adk.tools.url_context instance
- GEPA: Genetic-Pareto; skills' instructions are optimized too; static
instruction required; example sets validation_eval_set
- VertexAiRagMemoryService: ingest once at session end (every call
uploads the full transcript), drop per-turn callback advice; install
via google-adk[gcp] (+ greenlet for async SQLAlchemy 2.1); create the
corpus with agentplatform's client.rag.create_corpus
- Release banners now dated ("as of 2026-09-21") since 2.10.0 shipped;
comprehensive guide Updated date aligned
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01UbuuyLymfkxVYM5kGzDV53
…(Copilot findings)
- comprehensive_guide.md: remove VertexAiRagMemoryService from
add_events_to_memory support row; it raises NotImplementedError
(source-verified against google-adk 2.9.2)
- class_deep_dives_vol4.md: fix rag_corpus troubleshooting row —
remove reference to internal rag_resource param; only rag_corpus
is a constructor argument
- memory-and-artifacts.md: replace "agents never mutate the corpus"
with accurate description of add_session_to_memory write path and
add_events_to_memory NotImplementedError
- index.mdx: change "new optimization module" to "optimization module
(newly deepened in this volume)" — the module existed in 2.7.1
Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01YGnEndeZKTPaUENwFn69fQ
The reason will be displayed to describe this comment to others. Learn more.
Isolate the RAG corpus before accepting arbitrary users
In this full-wiring example, chat() accepts arbitrary user_id values while every request shares RAG_CORPUS; VertexAiRagMemoryService searches the corpus without applying its app_name or user_id arguments as retrieval filters, and PreloadMemoryTool automatically injects the resulting matches. In a multi-user deployment, one user's request can therefore receive another user's ingested transcript. Use a separate corpus per trust boundary or a memory backend that enforces user scoping, and document this limitation.
The reason will be displayed to describe this comment to others. Learn more.
Source-verified against google-adk 2.9.2 — this finding does not hold.
VertexAiRagMemoryService encodes app_name, user_id, and session_id into each uploaded file's display_name via _build_source_display_name (line 70-76 of vertex_ai_rag_memory_service.py). search_memory then parses that display name from every retrieved chunk and drops any chunk whose source_app_name != app_name or source_user_id != user_id (lines 355-359). Cross-user retrieval is filtered at the application layer regardless of corpus sharing. The example code is correct as written.
This description implies the ten classes were new or deepened in the 2.9.2 package, but the existing comprehensive guide already documents SimplePromptOptimizer and GEPARootAgentOptimizer as present in 2.7.1 (google_adk_comprehensive_guide.md:6371-6390) and UrlContextTool as verified in 2.7.1 (google_adk_comprehensive_guide.md:4716-4737). Reword this as classes newly covered or deepened in this volume, consistent with the revision entry.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
Summary
google_adk_class_deep_dives_vol4.md) — 10 classes source-verified against google-adk 2.9.2, covering areas absent from or underrepresented in earlier guides.Classes covered in Vol. 4
SimplePromptOptimizer+ configgoogle.adk.optimizationGEPARootAgentOptimizer+ configgoogle.adk.optimizationrun_dirSamplergoogle.adk.optimizationLocalEvalSamplergoogle.adk.optimizationTelemetryConfiggoogle.adk.telemetry.contextUrlContextToolgoogle.adk.toolsSkillgoogle.adk.skills.modelsSkillRegistrygoogle.adk.skills.skill_registrySkillToolsetgoogle.adk.tools.skill_toolsetVertexAiRagMemoryServicegoogle.adk.memoryFiles changed
src/content/docs/google-adk-guide/python/google_adk_class_deep_dives_vol4.md— new file (~1 100 lines)src/content/docs/google-adk-guide/index.mdx— Python card version + revision historysrc/content/docs/google-adk-guide/python/agents.md— latest release bannersrc/content/docs/google-adk-guide/python/runner-and-sessions.md— latest release bannersrc/content/docs/google-adk-guide/python/tools.md— latest release bannersrc/content/docs/google-adk-guide/python/workflows.md— latest release bannersrc/content/docs/google-adk-guide/python/callbacks-and-plugins.md— latest release banner🤖 Generated with Claude Code
https://claude.ai/code/session_01YGnEndeZKTPaUENwFn69fQ
Generated by Claude Code