<blocked> Feat: Adding Go examples to Express_mode docs

.github/workflows/go-fmt.yaml

@@ -0,0 +1,41 @@
+name: Go Fmt
+
+on:
+  pull_request:
+    paths:
+      - '**.go'
+
+jobs:
+  gofmt:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0 # Fetch all history for all tags and branches
+      - uses: actions/setup-go@v5
+        with:
+          go-version: '1.21'
+      - name: Run gofmt on changed files
+        run: |
+          # List changed Go files in the pull request.
+          # The `|| true` is to prevent the command from failing if no go files are found
+          changed_files=$(git diff --name-only --diff-filter=ACMRT ${{ github.event.pull_request.base.sha }}..${{ github.event.pull_request.head.sha }} | grep '\.go$' || true)
+
+          if [ -z "$changed_files" ]; then
+            echo "No Go files changed in this PR."
+            exit 0
+          fi
+
+          echo "Checking formatting for the following files:"
+          echo "$changed_files"
+
+          # Check formatting of changed files
+          unformatted_files=$(gofmt -l $changed_files)
+
+          if [ -n "$unformatted_files" ]; then
+            echo "Unformatted Go files found:"
+            echo "$unformatted_files"
+            exit 1
+          else
+            echo "All changed Go files are formatted correctly."
+          fi

docs/agents/custom-agents.md

@@ -53,6 +53,15 @@ The core of any custom agent is the method where you define its unique asynchron
     *   **Reactive Stream (`Flowable`):** It must return an `io.reactivex.rxjava3.core.Flowable<Event>`. This `Flowable` represents a stream of events that will be produced by the custom agent's logic, often by combining or transforming multiple `Flowable` from sub-agents.
     *   **`ctx` (InvocationContext):** Provides access to crucial runtime information, most importantly `ctx.session().state()`, which is a `java.util.concurrent.ConcurrentMap<String, Object>`. This is the primary way to share data between steps orchestrated by your custom agent.
 
+=== "Go"
+
+    In Go, you implement the `Run` method as part of a struct that satisfies the `agent.Agent` interface. The actual logic is typically a method on your custom agent struct.
+
+    *   **Signature:** `Run(ctx agent.InvocationContext) iter.Seq2[*session.Event, error]`
+    *   **Iterator:** The `Run` method returns an iterator (`iter.Seq2`) that yields events and errors. This is the standard way to handle streaming results from an agent's execution.
+    *   **`ctx` (InvocationContext):** The `agent.InvocationContext` provides access to the session, including state, and other crucial runtime information.
+    *   **Session State:** You can access the session state through `ctx.Session().State()`.
+
 **Key Capabilities within the Core Asynchronous Method:**
 
 === "Python"
@@ -127,6 +136,46 @@ The core of any custom agent is the method where you define its unique asynchron
           *   **Conditional:** `Flowable.defer()` to choose which `Flowable` to subscribe to based on a condition, or `filter()` if you're filtering events within a stream.
           *   **Iterative:** Operators like `repeat()`, `retry()`, or by structuring your `Flowable` chain to recursively call parts of itself based on conditions (often managed with `flatMapPublisher` or `concatMap`).
 
+=== "Go"
+
+    1. **Calling Sub-Agents:** You invoke sub-agents by calling their `Run` method.
+
+          ```go
+          // Example: Running one sub-agent and yielding its events
+          for event, err := range someSubAgent.Run(ctx) {
+              if err != nil {
+                  // Handle or propagate the error
+                  return
+              }
+              // Yield the event up to the caller
+              yield(event, nil)
+          }
+          ```
+
+    2. **Managing State:** Read from and write to the session state to pass data between sub-agent calls or make decisions.
+          ```go
+          // The `ctx` (`agent.InvocationContext`) is passed directly to your agent's `Run` function.
+          // Read data set by a previous agent
+          previousResult, err := ctx.Session().State().Get("some_key")
+          if err != nil {
+              // Handle cases where the key might not exist yet
+          }
+
+          // Make a decision based on state
+          if val, ok := previousResult.(string); ok && val == "some_value" {
+              // ... call a specific sub-agent ...
+          } else {
+              // ... call another sub-agent ...
+          }
+
+          // Store a result for a later step
+          if err := ctx.Session().State().Set("my_custom_result", "calculated_value"); err != nil {
+              // Handle error
+          }
+          ```
+
+    3. **Implementing Control Flow:** Use standard Go constructs (`if`/`else`, `for`/`switch` loops, goroutines, channels) to create sophisticated, conditional, or iterative workflows involving your sub-agents.
+
 ## Managing Sub-Agents and State
 
 Typically, a custom agent orchestrates other agents (like `LlmAgent`, `LoopAgent`, etc.).
@@ -162,6 +211,14 @@ Let's illustrate the power of custom agents with an example pattern: a multi-sta
     ```java
     --8<-- "examples/java/snippets/src/main/java/agents/StoryFlowAgentExample.java:init"
     ```
+
+=== "Go"
+
+    We define the `StoryFlowAgent` struct and a constructor. In the constructor, we store the necessary sub-agents and tell the `BaseAgent` framework about the top-level agents this custom agent will directly orchestrate.
+
+    ```go
+    --8<-- "examples/go/snippets/agents/custom-agent/storyflow_agent.go:init"
+    ```
 ---
 
 ### Part 2: Defining the Custom Execution Logic { #part-2-defining-the-custom-execution-logic }
@@ -195,6 +252,20 @@ Let's illustrate the power of custom agents with an example pattern: a multi-sta
     3. Then, the `sequentialAgent's` Flowable executes. It calls the `grammar_check` then `tone_check`, reading `current_story` and writing `grammar_suggestions` and `tone_check_result` to the state.
     4. **Custom Part:** After the sequentialAgent completes, logic within a `Flowable.defer` checks the "tone_check_result" from `invocationContext.session().state()`. If it's "negative", the `storyGenerator` Flowable is *conditionally concatenated* and executed again, overwriting "current_story". Otherwise, an empty Flowable is used, and the overall workflow proceeds to completion.
 
+=== "Go"
+
+    The `Run` method orchestrates the sub-agents by calling their respective `Run` methods in a loop and yielding their events.
+
+    ```go
+    --8<-- "examples/go/snippets/agents/custom-agent/storyflow_agent.go:executionlogic"
+    ```
+    **Explanation of Logic:**
+
+    1. The initial `storyGenerator` runs. Its output is expected to be in the session state under the key `"current_story"`.
+    2. The `revisionLoopAgent` runs, which internally calls the `critic` and `reviser` sequentially for `max_iterations` times. They read/write `current_story` and `criticism` from/to the state.
+    3. The `postProcessorAgent` runs, calling `grammar_check` then `tone_check`, reading `current_story` and writing `grammar_suggestions` and `tone_check_result` to the state.
+    4. **Custom Part:** The code checks the `tone_check_result` from the state. If it's "negative", the `story_generator` is called *again*, overwriting the `current_story` in the state. Otherwise, the flow ends.
+
 ---
 
 ### Part 3: Defining the LLM Sub-Agents { #part-3-defining-the-llm-sub-agents }
@@ -216,6 +287,12 @@ These are standard `LlmAgent` definitions, responsible for specific tasks. Their
     --8<-- "examples/java/snippets/src/main/java/agents/StoryFlowAgentExample.java:llmagents"
     ```
 
+=== "Go"
+
+    ```go
+    --8<-- "examples/go/snippets/agents/custom-agent/storyflow_agent.go:llmagents"
+    ```
+
 ---
 
 ### Part 4: Instantiating and Running the custom agent { #part-4-instantiating-and-running-the-custom-agent }
@@ -234,6 +311,12 @@ Finally, you instantiate your `StoryFlowAgent` and use the `Runner` as usual.
     --8<-- "examples/java/snippets/src/main/java/agents/StoryFlowAgentExample.java:story_flow_agent"
     ```
 
+=== "Go"
+
+    ```go
+    --8<-- "examples/go/snippets/agents/custom-agent/storyflow_agent.go:story_flow_agent"
+    ```
+
 *(Note: The full runnable code, including imports and execution logic, can be found linked below.)*
 
 ---
@@ -255,3 +338,10 @@ Finally, you instantiate your `StoryFlowAgent` and use the `Runner` as usual.
         # Full runnable code for the StoryFlowAgent example
         --8<-- "examples/java/snippets/src/main/java/agents/StoryFlowAgentExample.java:full_code"
         ```
+
+    === "Go"
+
+        ```go
+        # Full runnable code for the StoryFlowAgent example
+        --8<-- "examples/go/snippets/agents/custom-agent/storyflow_agent.go:full_code"
+        ```

docs/agents/llm-agents.md

@@ -66,6 +66,13 @@ First, you need to establish what the agent *is* and what it's *for*.
             .build();
     ```
 
+=== "Golang"
+
+    ```go
+    // Example: Defining the basic identity
+    --8<-- "examples/go/snippets/agents/llm-agents/snippets/main.go:identity"
+    ```
+
 
 ## Guiding the Agent: Instructions (`instruction`)
 
@@ -136,6 +143,13 @@ tells the agent:
             .build();
     ```
 
+=== "Golang"
+
+    ```go
+    // Example: Adding instructions
+    --8<-- "examples/go/snippets/agents/llm-agents/snippets/main.go:instruction"
+    ```
+
 *(Note: For instructions that apply to *all* agents in a system, consider using
 `global_instruction` on the root agent, detailed further in the
 [Multi-Agents](multi-agents.md) section.)*
@@ -208,6 +222,12 @@ on the conversation and its instructions.
             .build();
     ```
 
+=== "Golang"
+
+    ```go
+    --8<-- "examples/go/snippets/agents/llm-agents/snippets/main.go:tool_example"
+    ```
+
 Learn more about Tools in the [Tools](../tools/index.md) section.
 
 ## Advanced Configuration & Control
@@ -255,6 +275,14 @@ You can adjust how the underlying LLM generates responses using `generate_conten
             .build();
     ```
 
+=== "Golang"
+
+    ```go
+    import "google.golang.org/genai"
+
+    --8<-- "examples/go/snippets/agents/llm-agents/snippets/main.go:gen_config"
+    ```
+
 ### Structuring Data (`input_schema`, `output_schema`, `output_key`)
 
 For scenarios requiring structured data exchange with an `LLM Agent`, the ADK provides mechanisms to define expected input and desired output formats using schema definitions.
@@ -266,6 +294,7 @@ For scenarios requiring structured data exchange with an `LLM Agent`, the ADK pr
 * **`output_key` (Optional):** Provide a string key. If set, the text content of the agent's *final* response will be automatically saved to the session's state dictionary under this key. This is useful for passing results between agents or steps in a workflow.
     * In Python, this might look like: `session.state[output_key] = agent_response_text`
     * In Java: `session.state().put(outputKey, agentResponseText)`
+    * In Golang, within a callback handler: `ctx.State().Set(output_key, agentResponseText)`
 
 === "Python"
 
@@ -315,6 +344,14 @@ For scenarios requiring structured data exchange with an `LLM Agent`, the ADK pr
             .build();
     ```
 
+=== "Golang"
+
+    The input and output schema is a `google.genai.types.Schema` object.
+
+    ```go
+    --8<-- "examples/go/snippets/agents/llm-agents/snippets/main.go:schema_example"
+    ```
+
 ### Managing Context (`include_contents`)
 
 Control whether the agent receives the prior conversation history.
@@ -344,6 +381,14 @@ Control whether the agent receives the prior conversation history.
             .build();
     ```
 
+=== "Golang"
+
+    ```go
+    import "google.golang.org/adk/agent/llmagent"
+
+    --8<-- "examples/go/snippets/agents/llm-agents/snippets/main.go:include_contents"
+    ```
+
 ### Planner
 
 <div class="language-support-tag" title="">
@@ -551,6 +596,12 @@ call_agent("If it's raining in New York right now, what is the current temperatu
         --8<-- "examples/java/snippets/src/main/java/agents/LlmAgentExample.java:full_code"
         ```
 
+    === "Golang"
+
+        ```go
+        --8<-- "examples/go/snippets/agents/llm-agents/main.go:full_code"
+        ```
+
 _(This example demonstrates the core concepts. More complex agents might incorporate schemas, context control, planning, etc.)_
 
 ## Related Concepts (Deferred Topics)

docs/agents/models.md

@@ -184,6 +184,18 @@ For deployed applications, a service account is the standard method.
     // different availability or quota limitations.
     ```
 
+=== "Go"
+
+    ```go
+    import (
+    	"google.golang.org/adk/agent/llmagent"
+    	"google.golang.org/adk/model/gemini"
+    	"google.golang.org/genai"
+    )
+
+    --8<-- "examples/go/snippets/agents/models/models.go:gemini-example"
+    ```
+
 !!!warning "Secure Your Credentials"
     Service account credentials or API keys are powerful credentials. Never expose them publicly. Use a secret manager like [Google Secret Manager](https://cloud.google.com/secret-manager) to store and access them securely in production.