Fix code samples that do not compile against the shipped SDKs (#2194)

* Fix code samples that do not compile against the shipped SDKs

Checked the code samples against the real published libraries and corrected
what does not compile or resolve. Verified against google-adk 2.8.0 for
Python, @google/adk 2.0.0 for TypeScript, google-adk 1.6.0 for Java,
adk-kotlin 0.8.0 for Kotlin, and adk/v2 2.3.0 for Go.

Go: tool.Context does not exist in the v2 line and never has. The type is
agent.Context, which this repository's own Go examples already use. Nine
sites. Four import blocks also omitted the fmt they call.

Java: two imports naming packages that do not exist, com.google.adk.agent
(the package is agents) and com.google.adk.agents.Content (it is a genai
type). Four wrong types, each confirmed against the jar with javap:
EventActions.stateDelta returns Map not ConcurrentMap, artifactDelta returns
Map<String, Integer> rather than ConcurrentMap<String, Part>,
FunctionResponse.response yields Map<String, Object>, and loadArtifact takes
the version as an int so the Optional argument matched no overload.

Python: four coroutines used without await, which also masked a
SearchMemoryResponse.results field that does not exist. The field is
memories, holding MemoryEntry objects; the TypeScript and Java tabs of the
same example had the same mistake. Also CodeExecutionInput imported from the
wrong module, a calendar_tool_set object that does not exist in place of
CalendarToolset, two positional Part.from_text calls against a keyword-only
signature, five LlmAgent samples missing the required name, and an external
access token sample built on an enum member and a field that the package does
not define.

Also corrects samples that could not parse at all: an unindented plugin class
body, bracket and text block typos, a truncated call, an await in a non-async
function, an await dedented out of the condition meant to guard it, a mid-file
Java import, and a fence that opened at six spaces and closed at eight, which
made a page render a literal code fence as body text.

* Yield the workflow node's result instead of returning it

code_workflow yields, which makes it an async generator, and returning a
value from one is a syntax error. A generator node conveys its result by
yielding an event whose output the runner copies to the context, which is the
form the data handling page already uses.

* docs(tools): simplify the toolset headings per review

Drop the parenthetical class lists from the two toolset headings in the
authentication page. Nothing links to either anchor.

---------

Co-authored-by: Joe Fernandez <931947+joefernandez@users.noreply.github.com>

Author: GWeale

docs/agents/custom-agents.md

@@ -1234,13 +1234,13 @@ Finally, you instantiate your `StoryFlowAgent` and use the `Runner` as usual.
     === "Go"
 
         ```go
-        # Full runnable code for the StoryFlowAgent example
+        // Full runnable code for the StoryFlowAgent example
         --8<-- "examples/go/snippets/agents/custom-agent/storyflow_agent.go:full_code"
         ```
 
     === "Java"
 
         ```java
-        # Full runnable code for the StoryFlowAgent example
+        // Full runnable code for the StoryFlowAgent example
         --8<-- "examples/java/snippets/src/main/java/agents/StoryFlowAgentExample.java:full_code"
         ```

docs/agents/llm-agents.md

@@ -716,6 +716,7 @@ reasoning and planning before execution. There are two main planners:
     from google.genai import types
 
     my_agent = Agent(
+        name="my_agent",
         model="gemini-flash-latest",
         planner=BuiltInPlanner(
             thinking_config=types.ThinkingConfig(
@@ -737,6 +738,7 @@ reasoning and planning before execution. There are two main planners:
     from google.adk.planners import PlanReActPlanner
 
     my_agent = Agent(
+        name="my_agent",
         model="gemini-flash-latest",
         planner=PlanReActPlanner(),
         # ... your tools here

docs/agents/models/google-gemma.md

@@ -61,7 +61,7 @@ Create an API key in [Google AI Studio](https://aistudio.google.com/app/apikey).
         .instruction("""
             You are a helpful assistant that can provide current weather.
         """)
-        .tools(FunctionTool.create(this, "getWeather")]    
+        .tools(FunctionTool.create(this, "getWeather"))
         .build();
 
     @Schema(name = "getWeather", 
@@ -210,7 +210,7 @@ The following example shows how to use a Gemma 4 vLLM endpoint with ADK agents.
         .instruction("""
             You are a helpful assistant that can provide the current weather.
         """)
-        .tools(FunctionTool.create(this, "getWeather")]    
+        .tools(FunctionTool.create(this, "getWeather"))
         .build();
 
     @Schema(name = "getWeather", 

docs/apps/index.md

@@ -135,7 +135,7 @@ You can use the ***Runner*** class to run your agent workflow using the
 === "Java"
 
     ```java title="AppMain.java"
-    import com.google.adk.agents.Content;
+    import com.google.genai.types.Content;
     import com.google.adk.runner.Runner;
 
     public class AppMain {

docs/artifacts/index.md

@@ -785,7 +785,7 @@ The artifact interaction methods are available directly on instances of `Callbac
             public void processLatestReportJava(String userId, String sessionId, String filename) {
                 // Load the latest version by passing Optional.empty() for the version
                 artifactService
-                        .loadArtifact(appName, userId, sessionId, filename, Optional.empty())
+                        .loadArtifact(appName, userId, sessionId, filename)
                         .subscribe(
                                 new MaybeObserver<Part>() {
                                     @Override
@@ -828,7 +828,7 @@ The artifact interaction methods are available directly on instances of `Callbac
 
                 // Example: Load a specific version (e.g., version 0)
                 /*
-                artifactService.loadArtifact(appName, userId, sessionId, filename, Optional.of(0))
+                artifactService.loadArtifact(appName, userId, sessionId, filename, 0)
                     .subscribe(part -> {
                         System.out.println("Loaded version 0 of Java artifact '" + filename + "'.");
                     }, throwable -> {

docs/context/caching.md

@@ -29,6 +29,7 @@ these settings, as shown in the following code sample:
     from google.adk.agents.context_cache_config import ContextCacheConfig
 
     root_agent = Agent(
+      name='my_caching_agent',
       # configure an agent using Gemini 2.0 or higher
     )
 

docs/context/compaction.md

@@ -74,7 +74,8 @@ specific number of workflow events, or invocations, with the current Session.
 # (Optional) Event-based, sliding window as supplementary setting
 compaction_config = EventsCompactionConfig(
     compaction_interval=10,   # Number of turns between standard compactions
-    overlap_size=2,           # Number of events to retain as overlapping context
+    overlap_size=2            # Number of events to retain as overlapping context
+)
 ```
 
 ## Configure context compaction

docs/context/index.md

@@ -172,6 +172,8 @@ Here are the primary context flavors you will encounter:
 
         ```go
         import (
+        	"fmt"
+
         	"google.golang.org/adk/v2/agent"
         	"google.golang.org/adk/v2/session"
         )
@@ -239,7 +241,11 @@ Here are the primary context flavors you will encounter:
     === "Go"
 
         ```go
-        import "google.golang.org/adk/v2/agent"
+        import (
+        	"fmt"
+
+        	"google.golang.org/adk/v2/agent"
+        )
 
         --8<-- "examples/go/snippets/context/main.go:readonly_context_instruction"
         ```
@@ -314,6 +320,8 @@ Here are the primary context flavors you will encounter:
 
         ```go
         import (
+        	"fmt"
+
         	"google.golang.org/adk/v2/agent"
         	"google.golang.org/adk/v2/model"
         )
@@ -532,9 +540,10 @@ You'll frequently need to read information stored within the context.
     === "Java"
 
         ```java
-        // Example: In a Tool function
+        import com.google.adk.agents.CallbackContext;
         import com.google.adk.tools.ToolContext;
 
+        // Example: In a Tool function
         public void myTool(ToolContext toolContext) {
             String userPref = (String) toolContext.state().getOrDefault("user_display_preference", "default_mode");
             String apiEndpoint = (String) toolContext.state().get("app:api_endpoint"); // Read app-level state
@@ -547,8 +556,6 @@ You'll frequently need to read information stored within the context.
         }
 
         // Example: In a Callback function
-        import com.google.adk.agents.CallbackContext;
-
         public void myCallback(CallbackContext callbackContext) {
             String lastToolResult = (String) callbackContext.state().get("temp:last_api_result"); // Read temporary state
 
@@ -656,6 +663,8 @@ You'll frequently need to read information stored within the context.
 
         ```go
         import (
+        	"fmt"
+
         	"google.golang.org/adk/v2/agent"
         	"google.golang.org/genai"
         )
@@ -847,12 +856,12 @@ Use artifacts to handle files or large data blobs associated with the session. C
                from google.adk.agents.context import Context # Or ToolContext
                from google.genai import types
 
-               def save_document_reference(context: Context, file_path: str) -> None:
+               async def save_document_reference(context: Context, file_path: str) -> None:
                    # Assume file_path is something like "gs://my-bucket/docs/report.pdf" or "/local/path/to/report.pdf"
                    try:
                        # Create a Part containing the path/URI text
-                       artifact_part = types.Part.from_text(file_path)
-                       version = context.save_artifact("document_to_summarize.txt", artifact_part)
+                       artifact_part = types.Part.from_text(text=file_path)
+                       version = await context.save_artifact("document_to_summarize.txt", artifact_part)
                        print(f"Saved document reference '{file_path}' as artifact version {version}")
                        # Store the filename in state if needed by other tools
                        context.state["temp:doc_artifact_name"] = "document_to_summarize.txt"
@@ -940,14 +949,14 @@ Use artifacts to handle files or large data blobs associated with the session. C
             # Assume a 'summarize_text' function exists
             # from my_summarizer_lib import summarize_text
 
-            def summarize_document_tool(tool_context: ToolContext) -> dict:
+            async def summarize_document_tool(tool_context: ToolContext) -> dict:
                 artifact_name = tool_context.state.get("temp:doc_artifact_name")
                 if not artifact_name:
                     return {"error": "Document artifact name not found in state."}
 
                 try:
                     # 1. Load the artifact part containing the path/URI
-                    artifact_part = tool_context.load_artifact(artifact_name)
+                    artifact_part = await tool_context.load_artifact(artifact_name)
                     if not artifact_part or not artifact_part.text:
                         return {"error": f"Could not load artifact or artifact has no text path: {artifact_name}"}
 
@@ -1105,9 +1114,9 @@ Use artifacts to handle files or large data blobs associated with the session. C
         # Example: In a tool function
         from google.adk.tools import ToolContext
 
-        def check_available_docs(tool_context: ToolContext) -> dict:
+        async def check_available_docs(tool_context: ToolContext) -> dict:
             try:
-                artifact_keys = tool_context.list_artifacts()
+                artifact_keys = await tool_context.list_artifacts()
                 print(f"Available artifacts: {artifact_keys}")
                 return {"available_docs": artifact_keys}
             except ValueError as e:
@@ -1351,13 +1360,17 @@ Access relevant information from the past or external sources.
     # Example: Tool using memory search
     from google.adk.tools import ToolContext
 
-    def find_related_info(tool_context: ToolContext, topic: str) -> dict:
+    async def find_related_info(tool_context: ToolContext, topic: str) -> dict:
         try:
-            search_results = tool_context.search_memory(f"Information about {topic}")
-            if search_results.results:
-                print(f"Found {len(search_results.results)} memory results for '{topic}'")
-                # Process search_results.results (which are SearchMemoryResponseEntry)
-                top_result_text = search_results.results[0].text
+            search_results = await tool_context.search_memory(f"Information about {topic}")
+            if search_results.memories:
+                print(f"Found {len(search_results.memories)} memory results for '{topic}'")
+                # Process search_results.memories (which are MemoryEntry objects)
+                top_entry = search_results.memories[0]
+                top_result_text = next(
+                    (part.text for part in (top_entry.content.parts or []) if part.text),
+                    "",
+                )
                 return {"memory_snippet": top_result_text}
             else:
                 return {"message": "No relevant memories found."}
@@ -1376,10 +1389,11 @@ Access relevant information from the past or external sources.
     async function findRelatedInfo(context: Context, topic: string): Promise<Record<string, string>> {
       try {
         const searchResults = await context.searchMemory(`Information about ${topic}`);
-        if (searchResults.results?.length) {
-          console.log(`Found ${searchResults.results.length} memory results for '${topic}'`);
-          // Process searchResults.results
-          const topResultText = searchResults.results[0].text;
+        if (searchResults.memories.length) {
+          console.log(`Found ${searchResults.memories.length} memory results for '${topic}'`);
+          // Process searchResults.memories
+          const topResultText =
+              searchResults.memories[0].content.parts?.[0]?.text ?? '';
           return { memory_snippet: topResultText };
         } else {
           return { message: 'No relevant memories found.' };
@@ -1403,10 +1417,11 @@ Access relevant information from the past or external sources.
       public Single<Map<String, String>> findRelatedInfo(ToolContext context, String topic) {
         return context.searchMemory("Information about " + topic)
             .map(searchResults -> {
-              if (searchResults != null && searchResults.results() != null && !searchResults.results().isEmpty()) {
-                System.out.println("Found " + searchResults.results().size() + " memory results for '" + topic + "'");
-                // Process searchResults.results
-                String topResultText = searchResults.results().get(0).text();
+              if (searchResults != null && !searchResults.memories().isEmpty()) {
+                System.out.println("Found " + searchResults.memories().size() + " memory results for '" + topic + "'");
+                // Process searchResults.memories
+                String topResultText =
+                    searchResults.memories().get(0).content().text();
                 return Map.of("memory_snippet", topResultText);
               } else {
                 return Map.of("message", "No relevant memories found.");
@@ -1432,6 +1447,7 @@ While most interactions happen via `CallbackContext` or `ToolContext`, sometimes
     from google.adk.agents import BaseAgent
     from google.adk.agents.invocation_context import InvocationContext
     from google.adk.events import Event
+    from google.genai import types
     from typing import AsyncGenerator
 
     class MyControllingAgent(BaseAgent):
@@ -1445,7 +1461,14 @@ While most interactions happen via `CallbackContext` or `ToolContext`, sometimes
             if ctx.session.state.get("critical_error_flag"):
                 print("Critical error detected, ending invocation.")
                 ctx.end_invocation = True # Signal framework to stop processing
-                yield Event(author=self.name, invocation_id=ctx.invocation_id, content="Stopping due to critical error.")
+                yield Event(
+                author=self.name,
+                invocation_id=ctx.invocation_id,
+                content=types.Content(
+                    role="model",
+                    parts=[types.Part(text="Stopping due to critical error.")],
+                ),
+            )
                 return # Stop this agent's execution
 
             # ... Normal agent processing ...

docs/deploy/gke.md

@@ -288,7 +288,7 @@ Use the `capital_agent` example defined on the [LLM agents](../agents/llm-agents
             Country string `json:"country" jsonschema:"The country to look up."`
         }
 
-        func getCapitalCity(_ tool.Context, args getCapitalCityArgs) (string, error) {
+        func getCapitalCity(_ agent.Context, args getCapitalCityArgs) (string, error) {
             capitals := map[string]string{
                 "france":  "Paris",
                 "japan":   "Tokyo",

docs/events/index.md

@@ -517,7 +517,7 @@ Once you know the event type, access the relevant data:
         if (!responses.isEmpty()) {
             for (FunctionResponse response : responses) {
                 String toolName = response.name().get();
-                Map<String, String> result= response.response().get(); // Check before getting the response
+                Map<String, Object> result = response.response().get(); // Check before getting the response
                 System.out.println("  Tool Result: " + toolName + " -> " + result);
             }
         }
@@ -569,15 +569,15 @@ The `event.actions` object signals changes that occurred or should occur. Always
         ```
 
     === "Java"
-        `ConcurrentMap<String, Object> delta = event.actions().stateDelta();`
+        `Map<String, Object> delta = event.actions().stateDelta();`
 
         ```java
-        import java.util.concurrent.ConcurrentMap;
+        import java.util.Map;
         import com.google.adk.events.EventActions;
 
         EventActions actions = event.actions(); // Assuming event.actions() is not null
         if (actions != null && actions.stateDelta() != null && !actions.stateDelta().isEmpty()) {
-            ConcurrentMap<String, Object> stateChanges = actions.stateDelta();
+            Map<String, Object> stateChanges = actions.stateDelta();
             System.out.println("  State changes: " + stateChanges);
             // Update local UI or application state if necessary
         }
@@ -626,19 +626,18 @@ The `event.actions` object signals changes that occurred or should occur. Always
         ```
 
     === "Java"
-        `ConcurrentMap<String, Part> artifactChanges = event.actions().artifactDelta();`
+        `Map<String, Integer> artifactChanges = event.actions().artifactDelta();`
 
         ```java
-        import java.util.concurrent.ConcurrentMap;
-        import com.google.genai.types.Part;
+        import java.util.Map;
         import com.google.adk.events.EventActions;
 
         EventActions actions = event.actions(); // Assuming event.actions() is not null
         if (actions != null && actions.artifactDelta() != null && !actions.artifactDelta().isEmpty()) {
-            ConcurrentMap<String, Part> artifactChanges = actions.artifactDelta();
+            Map<String, Integer> artifactChanges = actions.artifactDelta();
             System.out.println("  Artifacts saved: " + artifactChanges);
             // UI might refresh an artifact list
-            // Iterate through artifactChanges.entrySet() to get filename and Part details
+            // Iterate through artifactChanges.entrySet() to get filename and version
         }
         ```