Added initial llms.txt #261

ivanmkc · 2025-11-11T16:24:11Z

Initial llms.txt which is a condensed version of adk-docs, specific for Golang.

This is an initial, baseline version which will be benchmarked against future versions (or not using a llms.txt).

Equivalent to: https://github.com/google/adk-python/blob/main/llms-full.txt

This will need updating when the API changes.

gemini-code-assist · 2025-11-11T16:24:26Z

Summary of Changes

Hello @ivanmkc, I'm Gemini Code Assist¹! I'm currently reviewing this pull request and will post my feedback shortly. In the meantime, here's a summary to help you and other reviewers quickly get up to speed!

This pull request introduces a new, comprehensive documentation file, llms.txt, tailored for the Go Agent Development Kit (ADK). It aims to provide a clear and concise reference for developers, covering fundamental agent concepts, multi-agent architectures, advanced features like context management and callbacks, and inter-agent communication. This initial version is designed to serve as a baseline for future evaluation and improvement.

Highlights

New Documentation File: Introduces llms.txt, a new documentation file specifically for the Go Agent Development Kit (ADK).
Comprehensive Go ADK Summary: Provides a condensed yet detailed summary of ADK concepts for Golang, including core agent building blocks, multi-agent orchestration, and advanced features.
Core Agent Concepts: Explains the LlmAgent, its configuration, and how to use various Tools (Function Tools and Built-in Tools like GoogleSearch) with code examples.
Multi-Agent Systems: Details WorkflowAgents such as SequentialAgent, ParallelAgent, and LoopAgent, and the concept of using an AgentTool for hierarchical delegation.
Advanced ADK Features: Covers implementing Custom Agents, managing Context and State (Invocation, Readonly, Callback, Tool contexts), utilizing Callbacks (Before/After Agent/Model/Tool), and working with Artifacts and Memory.
Agent2Agent (A2A) Communication: Describes how to expose an agent as a remote service and how local agents can consume remote A2A agents, facilitating distributed multi-agent systems.
Benchmarking Intent: This initial version of the documentation is intended to be benchmarked against other versions to assess its effectiveness.

Using Gemini Code Assist

The full guide for Gemini Code Assist can be found on our documentation page, here are some quick tips.

Invoking Gemini

You can request assistance from Gemini at any point by creating a comment using either /gemini <command> or @gemini-code-assist <command>. Below is a summary of the supported commands on the current page.

Feature	Command	Description
Code Review	`/gemini review`	Performs a code review for the current pull request in its current state.
Pull Request Summary	`/gemini summary`	Provides a summary of the current pull request in its current state.
Comment	@gemini-code-assist	Responds in comments when explicitly tagged, both in pull request comments and review comments.
Help	`/gemini help`	Displays a list of available commands.

Customization

To customize Gemini Code Assist for GitHub experience, repository maintainers can create a configuration file and/or provide a custom code review style guide (such as PEP-8 for Python) by creating and adding files to a .gemini/ folder in the base of the repository. Detailed instructions can be found here.

Limitations & Feedback

Gemini Code Assist may make mistakes. Please leave feedback on any instances where its feedback is incorrect or counter productive. You can react with 👍 and 👎 on @gemini-code-assist comments. If you're interested in giving your feedback about your experience with Gemini Code Assist for Github and other Google products, sign up here.

You can also get AI-powered code generation, chat, as well as code reviews directly in the IDE at no cost with the Gemini Code Assist IDE Extension.

Review the Privacy Notices, Generative AI Prohibited Use Policy, Terms of Service, and learn how to configure Gemini Code Assist in GitHub here. Gemini can make mistakes, so double check it and use code with caution. ↩

gemini-code-assist

Code Review

This pull request introduces llms.txt, a new comprehensive documentation file for the Go Agent Development Kit (ADK). The file provides a good overview of the ADK's features with code examples. My review focuses on improving the correctness and robustness of these Go code snippets. I've identified several critical issues, including potential panics from unsafe type assertions and ignored errors, which could mislead users. I've provided suggestions to fix these issues by adding proper error handling and safe type checks. Additionally, I've pointed out some formatting inconsistencies and minor clarity improvements in the documentation to enhance readability.

llms.txt

ivanmkc · 2025-11-11T17:03:56Z

I'll address some of the AI-comments. The llms.txt isn't supposed to be runnable code but I'll add more err checks so the AI-user of llms.txt isn't biased to write code that ignores errors.

ivanmkc · 2025-11-11T20:37:23Z

How do I get @gemini-code-assist to re-review?

gemini-code-assist

Code Review

This pull request introduces llms.txt, a comprehensive documentation file for the Go Agent Development Kit (ADK). The file provides a good overview of the ADK's features with code examples. My review focuses on ensuring the correctness and clarity of this new documentation. I've identified several Go code snippets that would fail to compile due to incorrect API usage, particularly around handling genai.Part and other struct fields. I have provided suggestions to fix these examples. Additionally, I've pointed out some minor formatting and consistency issues to improve the document's readability.

gemini-code-assist · 2025-11-11T20:39:22Z

llms.txt

+type updateUserPreferenceResult struct {
+	Status            string `json:"status"`
+	UpdatedPreference string `json:"updated_preference"`
+}


The updateUserPreferenceResult struct is missing the Message field, but the updateUserPreference function attempts to set it on lines 454 and 465. This will cause a compilation error. Please add the Message field to the struct definition.

type updateUserPreferenceResult struct { Status string `json:"status"` UpdatedPreference string `json:"updated_preference"` Message string `json:"message,omitempty"` }

gemini-code-assist · 2025-11-11T20:39:22Z

llms.txt

+func onBeforeModelGuardrail(ctx agent.CallbackContext, req *model.LLMRequest) (*model.LLMResponse, error) {
+	for _, content := range req.Contents {
+		for _, part := range content.Parts {
+			if strings.Contains(part.Text, "finance") {
+				// By returning a non-nil response, we override the LLM call.
+				return &model.LLMResponse{
+					Content: genai.NewContentFromText(
+						"I'm sorry, but I cannot discuss financial topics.",
+						genai.RoleModel,
+					),
+				}, nil
+			}
+		}
+	}
+	// Returning nil allows the default LLM call to proceed.
+	return nil, nil
+}


The code example for onBeforeModelGuardrail incorrectly tries to access part.Text. A genai.Part is an interface, and to access its text content, you need to perform a type assertion to genai.Text. This will cause a compilation error as-is.

func onBeforeModelGuardrail(ctx agent.CallbackContext, req *model.LLMRequest) (*model.LLMResponse, error) { for _, content := range req.Contents { for _, part := range content.Parts { if text, ok := part.(genai.Text); ok && strings.Contains(string(text), "finance") { // By returning a non-nil response, we override the LLM call. return &model.LLMResponse{ Content: genai.NewContentFromText( "I'm sorry, but I cannot discuss financial topics.", genai.RoleModel, ), }, nil } } } // Returning nil allows the default LLM call to proceed. return nil, nil }

gemini-code-assist · 2025-11-11T20:39:22Z

llms.txt

+func onAfterModel(ctx agent.CallbackContext, resp *model.LLMResponse, respErr error) (*model.LLMResponse, error) {
+	if respErr != nil || resp == nil {
+		return nil, respErr // Pass through errors
+	}
+	// Modify the response text
+	originalText := resp.Content.Parts[0].Text
+	modifiedText := strings.ReplaceAll(originalText, "joke", "funny story")
+	resp.Content.Parts[0].Text = modifiedText
+	return resp, nil
+}


This example has a similar issue to the onBeforeModelGuardrail example. resp.Content.Parts[0] is a genai.Part interface and does not have a .Text field. You need to perform a type assertion to get the text, and you cannot directly assign a new string to it. You should create a new genai.Text part and replace it in the slice. This code will not compile as written.

func onAfterModel(ctx agent.CallbackContext, resp *model.LLMResponse, respErr error) (*model.LLMResponse, error) { if respErr != nil || resp == nil || resp.Content == nil || len(resp.Content.Parts) == 0 { return nil, respErr // Pass through errors } // Modify the response text if originalText, ok := resp.Content.Parts[0].(genai.Text); ok { modifiedText := strings.ReplaceAll(string(originalText), "joke", "funny story") resp.Content.Parts[0] = genai.Text(modifiedText) } return resp, nil }

gemini-code-assist · 2025-11-11T20:39:22Z

llms.txt

+	documentPart, err := ctx.Artifacts().Load(ctx, args.DocumentName)
+	if err != nil {
+		return processDocumentResult{Status: "error", Message: fmt.Sprintf("Document not found: %v", err)}
+	}


The ctx.Artifacts().Load() function returns a *artifact.LoadResponse struct. The code incorrectly assigns this to documentPart and then doesn't use it, which would cause a compilation error. The loaded artifact part should be accessed via loadResp.Part.

loadResp, err := ctx.Artifacts().Load(ctx, args.DocumentName) if err != nil { return processDocumentResult{Status: "error", Message: fmt.Sprintf("Document not found: %v", err)} } _ = loadResp.Part // The loaded document part can be used for analysis.

gemini-code-assist · 2025-11-11T20:39:22Z

llms.txt

+
+## 2. Multi-Agent Systems
+
+Complex tasks can be broken down by composing multiple agents. `WorkflowAgents` orchestrate the execution flow of their `sub_agents`.


For consistency with Go's naming conventions and the code examples in this document (e.g., agent.Config's SubAgents field), it would be clearer to refer to sub_agents as SubAgents in the descriptive text.

Complex tasks can be broken down by composing multiple agents. `WorkflowAgents` orchestrate the execution flow of their `SubAgents`.

gemini-code-assist · 2025-11-11T20:39:23Z

llms.txt

+        }
+        ```
+
+**`agent.ReadonlyContext`**


There seems to be a formatting issue. This context type should be numbered as '2.' to maintain the list's sequence.

2. **`agent.ReadonlyContext`**

gemini-code-assist · 2025-11-11T20:39:23Z

llms.txt

+
+For a complete and detailed API reference, please visit the official Go documentation.
+
+-   [:octicons-arrow-right-24: View Go API Docs](https://pkg.go.dev/google.golang.org/adk)


For consistency with POSIX standards and to prevent issues with some tools, files should end with a newline character.

- [:octicons-arrow-right-24: View Go API Docs](https://pkg.go.dev/google.golang.org/adk)

ivanmkc · 2025-11-12T18:58:40Z

Let me review the comments again.

rakyll · 2025-11-12T21:28:46Z

We are planning some breaking changes to the API surface. Would it be possible to come back to this after some of those changes land?

ivanmkc · 2025-11-12T22:55:24Z

@rakyll Of course, ping me when that happens. The eventual goal is that llms.txt will update with each breaking version.

Added llms.txt:

8a63edb

gemini-code-assist bot reviewed Nov 11, 2025

View reviewed changes

ivanmkc force-pushed the imkc--llms-txt branch from 2b6df20 to 4318870 Compare November 11, 2025 18:56

Added error checking to llms.txt

1181e84

ivanmkc force-pushed the imkc--llms-txt branch from 4318870 to 1181e84 Compare November 11, 2025 18:57

gemini-code-assist bot reviewed Nov 11, 2025

View reviewed changes

ivanmkc force-pushed the imkc--llms-txt branch 2 times, most recently from 149f28f to f432ecd Compare November 11, 2025 20:50

Added info to README.md

4d3c54c

ivanmkc force-pushed the imkc--llms-txt branch from f432ecd to 4d3c54c Compare November 11, 2025 20:51

Fixed additional review comments

fc0d2f2


		## 2. Multi-Agent Systems

		Complex tasks can be broken down by composing multiple agents. `WorkflowAgents` orchestrate the execution flow of their `sub_agents`.


		For a complete and detailed API reference, please visit the official Go documentation.

		- [:octicons-arrow-right-24: View Go API Docs](https://pkg.go.dev/google.golang.org/adk) No newline at end of file

Added initial llms.txt #261

Are you sure you want to change the base?

Added initial llms.txt #261

Uh oh!

Conversation

ivanmkc commented Nov 11, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

gemini-code-assist bot commented Nov 11, 2025

Summary of Changes

Highlights

Footnotes

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

ivanmkc commented Nov 11, 2025

Uh oh!

ivanmkc commented Nov 11, 2025

Uh oh!

gemini-code-assist bot left a comment

Choose a reason for hiding this comment

Code Review

Uh oh!

gemini-code-assist bot Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

gemini-code-assist bot Nov 11, 2025

Choose a reason for hiding this comment

Uh oh!

ivanmkc commented Nov 12, 2025

Uh oh!

rakyll commented Nov 12, 2025

Uh oh!

ivanmkc commented Nov 12, 2025

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

ivanmkc commented Nov 11, 2025 •

edited

Loading