Initial TODOs - DO NOT MERGE :)

.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/a2a/quickstart-consuming.md

@@ -2,6 +2,8 @@
 
 This quickstart covers the most common starting point for any developer: **"There is a remote agent, how do I let my ADK agent use it via A2A?"**. This is crucial for building complex multi-agent systems where different agents need to collaborate and interact.
 
+<!-- TODO: Golang version -->
+
 ## Overview
 
 This sample demonstrates the **Agent-to-Agent (A2A)** architecture in the Agent Development Kit (ADK), showcasing how multiple agents can work together to handle complex tasks. The sample implements an agent that can roll dice and check if numbers are prime.

docs/a2a/quickstart-exposing.md

@@ -2,6 +2,9 @@
 
 This quickstart covers the most common starting point for any developer: **"I have an agent. How do I expose it so that other agents can use my agent via A2A?"**. This is crucial for building complex multi-agent systems where different agents need to collaborate and interact.
 
+<!-- TODO: Golang version -->
+
+
 ## Overview
 
 This sample demonstrates how you can easily expose an ADK agent so that it can be then consumed by another agent using the A2A Protocol.

docs/agents/custom-agents.md

@@ -49,6 +49,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"
@@ -123,6 +132,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.).
@@ -158,6 +207,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 }
@@ -191,6 +248,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 }
@@ -212,6 +283,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 }
@@ -230,6 +307,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.)*
 
 ---
@@ -251,3 +334,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/index.md

@@ -19,6 +19,7 @@ ADK provides distinct agent categories to build sophisticated applications:
 ## Choosing the Right Agent Type
 
 The following table provides a high-level comparison to help distinguish between the agent types. As you explore each type in more detail in the subsequent sections, these distinctions will become clearer.
+<!-- TODO: subclass is not valid in Golang   -->
 
 | Feature              | LLM Agent (`LlmAgent`)              | Workflow Agent                              | Custom Agent (`BaseAgent` subclass)      |
 | :------------------- | :---------------------------------- | :------------------------------------------ |:-----------------------------------------|

docs/agents/llm-agents.md

@@ -62,6 +62,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`)
 
@@ -132,6 +139,14 @@ tells the agent:
             .build();
     ```
 
+=== "Go"
+
+    ```go
+    // Example: Adding instructions
+    --8<-- "examples/go/snippets/agents/llm-agents/snippets/main.go:instruction"
+    ```
+
+<!-- TODO: Golang version: global_instruction are not supported -->
 *(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.)*
@@ -144,6 +159,9 @@ calculations, fetch real-time data, or execute specific actions.
 
 * **`tools` (Optional):** Provide a list of tools the agent can use. Each item in the list can be:
     * A native function or method (wrapped as a `FunctionTool`). Python ADK automatically wraps the native function into a `FuntionTool` whereas, you must explicitly wrap your Java methods using `FunctionTool.create(...)`
+<!-- TODO: Golang version, to be described,  -->
+<!-- TODO: Golang version - no class inheritance -->
+
     * An instance of a class inheriting from `BaseTool`.
     * An instance of another agent (`AgentTool`, enabling agent-to-agent delegation - see [Multi-Agents](multi-agents.md)).
 
@@ -204,6 +222,13 @@ on the conversation and its instructions.
             .build();
     ```
 
+=== "Go"
+<!-- TODO: Golang version -->
+
+    ```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
@@ -251,6 +276,14 @@ You can adjust how the underlying LLM generates responses using `generate_conten
             .build();
     ```
 
+=== "Go"
+
+    ```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.
@@ -262,6 +295,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"
 
@@ -311,6 +345,14 @@ For scenarios requiring structured data exchange with an `LLM Agent`, the ADK pr
             .build();
     ```
 
+=== "Go"
+
+    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.
@@ -340,6 +382,14 @@ Control whether the agent receives the prior conversation history.
             .build();
     ```
 
+=== "Go"
+
+    ```go
+    import "google.golang.org/adk/agent/llmagent"
+
+    --8<-- "examples/go/snippets/agents/llm-agents/snippets/main.go:include_contents"
+    ```
+
 ### Planner
 
 ![python_only](https://img.shields.io/badge/Currently_supported_in-Python-blue){ title="This feature is currently available for Python. Java support is planned/ coming soon."}
@@ -543,6 +593,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

@@ -2,6 +2,7 @@
 
 !!! Note
     Java ADK currently supports Gemini and Anthropic models. More model support coming soon.
+<!-- TODO: Golang version -->
 
 The Agent Development Kit (ADK) is designed for flexibility, allowing you to
 integrate various Large Language Models (LLMs) into your agents. While the setup
@@ -23,6 +24,7 @@ ADK primarily uses two mechanisms for model integration:
    configurations (like models accessed via LiteLLM). You instantiate a specific
    wrapper class (e.g., `LiteLlm`) and pass this object as the `model` parameter
    to your `LlmAgent`.
+<!-- TODO: Golang version -->
 
 The following sections guide you through using these methods based on your needs.
 
@@ -50,6 +52,9 @@ This section covers authenticating with Google's Gemini models, either through G
 
 ### Google AI Studio
 
+<!-- TODO: Golang version: check what's applicable, GOOGLE_APPLICATION_CREDENTIALS etc  -->
+
+
 This is the simplest method and is recommended for getting started quickly.
 
 *   **Authentication Method:** API Key
@@ -183,11 +188,23 @@ 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.
 
 ## Using Anthropic models
-
+<!-- TODO: Golang version: comment needed -->
 ![java_only](https://img.shields.io/badge/Supported_in-Java-orange){ title="This feature is currently available for Java. Python support for direct Anthropic API (non-Vertex) is via LiteLLM."}
 
 You can integrate Anthropic's Claude models directly using their API key or from a Vertex AI backend into your Java ADK applications by using the ADK's `Claude` wrapper class.
@@ -646,6 +663,8 @@ agent_finetuned_gemini = LlmAgent(
 
 ### Third-Party Models on Vertex AI (e.g., Anthropic Claude)
 
+<!-- TODO: Golang version: comment needed-->
+
 Some providers, like Anthropic, make their models available directly through
 Vertex AI.