Standardize Gemini Authentication by pemujo · Pull Request #1401 · google/adk-docs

pemujo · 2026-03-06T22:32:53Z

The goal of this PR is to consolidate Gemini authentication into reusable snippets and update the most common guides to use a centralized authentication pattern. It also adds specific guidance for selecting between Vertex AI and the Gemini API, resolving developer confusion caused by inconsistent setup instructions across the site.

Summary of Changes

Authentication Standardization: Created reusable components (snippets) for Gemini API, Vertex AI (ADC), and Express Mode to eliminate fragmented setup steps.
Updated Existing Guides: Replaced redundant setup instructions in google-gemini.md, python.md, quickstart.md, and config.md with pointers to the new snippets.
Selection Logic: Added a "Choosing an API" comparison in google-gemini.md to help users decide between AI Studio and Vertex AI.
Gemini Interactions API: Moved this feature to its own dedicated document for better discoverability.
Troubleshooting: Added a dedicated troubleshooting page and moved the existing "429 Error" section there for centralized error handling.

MkDocs Maintenance:

Updated nav configuration to include the new Interactions and Troubleshooting pages.
Excluded the _snippets/ directory from the site build to prevent rendering issues.

Verification

Successfully ran mkdocs serve with zero build warnings.
Confirmed tabbed authentication blocks render correctly across all updated guides.

netlify · 2026-03-06T22:32:58Z

✅ Deploy Preview for adk-docs-preview ready!

Name	Link
🔨 Latest commit	`b7f33b4`
🔍 Latest deploy log	https://app.netlify.com/projects/adk-docs-preview/deploys/69ab5c8d3281c0000819066a
😎 Deploy Preview	https://deploy-preview-1401--adk-docs-preview.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

joefernandez

Thanks for taking a pass at this. It's helped me understand the teaching problem, here and made it clear how we should solve it.

joefernandez · 2026-03-18T23:08:39Z

-[Context caching](/adk-docs/context/caching/),
-[Computer use](/adk-docs/tools/gemini-api/computer-use/)
-and the [Interactions API](#interactions-api).
+There are two primary APIs for accessing the Gemini model family: [Vertex AI API](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview) (available via Google Cloud Console) and the [Gemini API](https://ai.google.dev/gemini-api/docs) (available via Google AI Studio). While both provide access to the same state-of-the-art models, the choice between them depends on your specific security requirements, development phase, and deployment environment.


this is not an appropriate way to introduce the Gemini model family. This intro is WAY over-indexed on access path choices, to the point its getting in the way of the purpose of this page. This content should bet pushed down the page into a section that talks about access models, similar to the existing Gemini model authentication https://google.github.io/adk-docs/agents/models/google-gemini/#gemini-model-authentication

joefernandez · 2026-03-18T23:12:33Z

-## Gemini model authentication

-This section covers authenticating with Google's Gemini models, either through Google AI Studio for rapid development or Google Cloud Vertex AI for enterprise applications. This is the most direct way to use Google's flagship models within ADK.
+## Choosing Vertex AI API or Gemini API {#choosing-api}


This whole section feels like a sales pitch for Vertex AI API and Gemini. One of the promises of ADK as a framework is that it is open to use for all models. Its fine to provide some brief insights into why someone might want to use these products, but leave the sales job to the marketing pages for those products, it's not appropriate for technical documentation, and it will turn off developers who are looking for technical information

joefernandez · 2026-03-18T23:15:31Z

-and the [Interactions API](#interactions-api).
+There are two primary APIs for accessing the Gemini model family: [Vertex AI API](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/overview) (available via Google Cloud Console) and the [Gemini API](https://ai.google.dev/gemini-api/docs) (available via Google AI Studio). While both provide access to the same state-of-the-art models, the choice between them depends on your specific security requirements, development phase, and deployment environment.

-## Get started


Moving getting started section to the end is completely antithetical to the purpose of this page. At the end of the day developers want to know how to put a model into an agent. Burying that at the end is not appropriate

joefernandez · 2026-03-19T02:11:16Z

@@ -0,0 +1,54 @@
+Gemini Interactions API {#interactions-api}


I'm a not huge fan of splitting this out, because it makes is look like Gemini Interactions API is a model itself, rather that what it is, which is just an API option.

IF we were going to do this, the split should be:

/models/gemini/index.md
/models/gemini/interactions.md

so we can easily count the traffic to these pages together in Google Analytics

joefernandez · 2026-03-19T02:18:35Z

 Ensure your environment is configured for Vertex AI:

-1. **Authentication:** Use Application Default Credentials (ADC):
+--8<-- "docs/_snippets/gemini-authentication.md"


Duplication of GCP setup: Solving the duplication of GCP setup content by automating the content duplication is not what I had in mind.

Ideally, we want to minimize this information, because that's not what readers are here for. Also, once you get GCP access setup once, it's not something you have to keep doing. So, we concentrate that information in a single place and beef it up, and then point all docs that need that information to that location. Furthermore there is reason to believe that chopping up this content into small bits will make it harder for AI consumers to process it as useful context.

joefernandez · 2026-03-19T02:48:59Z

@@ -0,0 +1,52 @@
+# ADK roubleshooting guide


I disagree with this decision to separate this information from the Gemini model content. It's extremely unlikely we will ever pursue building a troubleshooting guide for ADK; in a nutshell, that is an unsupportable exercise from a resource perspective.

Furthermore, such guides are now irrelevant because AI coding tools are much, MUCH better at troubleshooting.

joefernandez · 2026-03-19T02:49:16Z

      - TypeScript: get-started/typescript.md
      - Go: get-started/go.md
      - Java: get-started/java.md
+      - Troubleshooting: get-started/troubleshooting.md


joefernandez · 2026-03-19T02:49:43Z

      - Ollama: agents/models/ollama.md
      - vLLM: agents/models/vllm.md
-      - LiteLLM: agents/models/litellm.md
+      - LiteLLM: agents/models/litellm.md      


remove trailing spaces

joefernandez · 2026-03-19T02:50:08Z

    - Models for Agents:
      - agents/models/index.md
      - Gemini: agents/models/google-gemini.md
+      - Gemini Interactions: agents/models/gemini-Interactions.md


we need to discuss details, but this will need to change

joefernandez · 2026-03-19T02:54:21Z

+
+#### Google Cloud Prerequisites {#setup-cloud-project}
+
+1. **Sign into Google Cloud**:


This information needs to get concentrated in a specific location, rather than being buried in the Gemini page, because every GCP product that integrates with ADK has this process as a prerequisite.

joefernandez · 2026-06-06T00:29:09Z

Closing using an alternative implementation:

Consolidate Google Cloud and Agent Platform connection info #1819

Pedro Melendez and others added 11 commits March 4, 2026 13:21

Improved gemini models guide

af13d95

Improved gemini models guide

5bff523

Rephrasing IAM permissions

da7752d

Improved gemini models guide

d6bb29e

Added model id links

fe7766e

Separate reusable sections to snippets

e9656ed

Updating snippets and pointing quickstarts to them

4b2e5e5

Updated streaming guide

157f537

Merge branch 'google:main' into Access-Gemini-central-doc

5403b24

Added troubleshooting and gemini interactions guides and updated mkdocs

1e3ea29

Updated more guides to use central doc

465c723

Merge branch 'main' into Access-Gemini-central-doc

b7f33b4

joefernandez reviewed Mar 19, 2026

View reviewed changes

joefernandez mentioned this pull request Jun 6, 2026

Consolidate Google Cloud and Agent Platform connection info #1819

Draft

joefernandez closed this Jun 6, 2026


		#### Google Cloud Prerequisites {#setup-cloud-project}

		1. Sign into Google Cloud:

Conversation

pemujo commented Mar 6, 2026

Uh oh!

netlify Bot commented Mar 6, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for adk-docs-preview ready!

Uh oh!

joefernandez left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

joefernandez commented Jun 6, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

netlify Bot commented Mar 6, 2026 •

edited

Loading