google/adk-samples: what the ADK recipe collection actually contains

What google/adk-samples solves and who it is aimed at

The README frames the problem directly: instead of a blank page, you get a working foundation. The collection is described as small, runnable agents that show how to solve real problems with the Agent Development Kit, and the stated use is to fork one as the starting point for your own project or to browse the patterns. That is a narrower promise than a framework. ADK itself lives in separate repositories for each language SDK, and this repository is the sample layer on top.

The audience is therefore engineers who have already decided to build on ADK and now need to see how a session, an OAuth flow, a guardrail or a retrieval pattern is wired in practice. The README names customer service bots and research agents as examples of what people build. If you have not chosen an agent framework yet, this repository will not help you choose: it assumes the ADK decision and shows idioms.

The repository is not archived, and the last push was on 2026-09-15.

The core and contrib split, and what each one is for

Recipes live in two top-level directories, and the distinction is editorial rather than technical. core/ holds canonical patterns curated by the agents-cli team, described as small and focused recipes that teach one thing well, with OAuth flows, session memory, guardrails and RAG patterns given as examples. contrib/ holds community-contributed recipes that are broader in scope, each a self-contained example for a specific use case or industry workflow.

That split matters when you are choosing where to copy from. A core recipe is meant to demonstrate one mechanism, so it will be short and probably incomplete for anything beyond that mechanism. A contrib recipe is meant to stand alone for a use case, which usually means more moving parts and more assumptions about your environment. The README says each recipe has its own README.md with setup and run instructions, so the entry point is always the recipe directory, not the repository root.

The top-level layout also carries language directories: python/, go/, java/, kotlin/ and typescript/. The README's prerequisites section links a separate ADK SDK repository for each of those languages, so the sample you pick has to match the SDK you have installed.

Installing a recipe and running it for the first time

The repository README does not give install steps for individual recipes; it points at the ADK Get Started guide at adk.dev/get-started for ADK itself and says each recipe carries its own README.md with setup and run instructions. So the honest first step is to pick a recipe directory and read that file.

The repository root does define its own tooling project. pyproject.toml names it adk-samples-tools, requires Python 3.11 or newer, and declares pyyaml and jsonschema as runtime dependencies. It also pins a minimum uv version, which is the package manager the tooling expects:

[project]
name = "adk-samples-tools"
version = "0.1.0"
requires-python = ">=3.11"
dependencies = [
  "pyyaml",
  "jsonschema",
]

Development dependencies are kept in a separate group and the file comments say to install them with uv sync --dev. That group exists for the repository tooling under tools/ and the skill scripts under .agents/skills/, not for running recipes:

uv sync --dev

The same file registers a console script named validate pointing at validate:main, which is the repository's own recipe validation entry point. Running it is how you check that a recipe you edited still conforms to the repository's expectations, and it is the closest thing to a first real use that the root configuration supports on its own:

uv run validate

For the agent itself, follow the recipe README. The repository README's prerequisites section links the ADK Python, TypeScript, Go, Java and Kotlin SDK repositories, so install the SDK for the language of the recipe you chose before you try to run it.

The disclaimer is the most important line in the README

The README ends with a disclaimer that is unusually blunt for a Google-owned repository. It states that this is not an officially supported Google product, that it is not eligible for the Google OSS Vulnerability Rewards Program, and that the recipes are for demonstration and as starting points, not production use.

Treat that as a design constraint rather than boilerplate. It means there is no support commitment behind a recipe you fork, and no bug bounty pathway if you find a security problem in one. For a repository whose core/ directory advertises OAuth flows and guardrails, that combination deserves a second look: the patterns teach you how to wire authentication and safety controls, but the code demonstrating them carries no security-response promise. If your plan is to lift an OAuth recipe into a service that handles real credentials, the disclaimer tells you the review burden is entirely yours.

The Apache-2.0 licence is separate from the disclaimer. The licence grants the usual permissions to use, modify and redistribute the code with attribution and the licence text included. It does not create a support relationship, and it does not change the fact that Google has said this is not a supported product. Nothing here is legal advice; if the distinction between an Apache-2.0 grant and a product support commitment matters to your organisation, that is a question for your own counsel.

Repository tooling, skills and the contribution path

The repository is not only recipes. The README points contributors at a one-page Recipe Checklist and a longer Recipe Handbook, both under docs/. It also describes repo skills, the AI coding-assistant helpers used to build the repository, living in .agents/skills/, covering recipe scaffolding, manifest generation and pyproject alignment. The README explicitly warns these are not to be confused with vertical skills, which are recipes shipped to users under skills/<vertical>/<solution>/.

That naming collision is worth flagging. Two different things are called skills in the same repository, and the README has to spend a sentence disambiguating them. If you are searching the tree for something called a skill, check which directory you landed in.

The pyproject.toml comments add a detail that explains why the dev dependency group is shaped the way it is. tomlkit, ruamel.yaml and packaging are imported by the align-recipe-pyproject skill script, which pytest imports through that skill's tests, and without them collection of the whole suite fails. The comments also note that packaging is imported by a GitHub script that injects its own dependencies and does not read the dev group, so it is declared there for the test run rather than for that gate. That is a small but real example of the repository documenting its own build fragility in configuration comments.

Where this is the wrong tool, and what to use instead

The clearest failure mode is expecting a maintained library. This is a sample collection with no releases retrieved, and its own README says the code is not for production use. If you need a dependency you can pin, patch and hold to a support SLA, you want the ADK SDK repositories themselves, which the README links for Python, TypeScript, Go, Java and Kotlin. Those are the framework; this is the example layer. Adopting a recipe as a dependency rather than copying it inverts the intended relationship.

A second case is cross-language drift. The repository carries python/, go/, java/, kotlin/ and typescript/ directories, but the primary language is Python and the root tooling is a Python project. If you are building in Go or Kotlin, expect fewer recipes to choose from and expect the repository tooling to be less relevant to your work. The README's prerequisites section treats the five SDKs as equals, but the repository contents do not.

The nearest real alternative is the ADK documentation site at adk.dev and the per-language SDK repositories. The difference in approach is that documentation explains a concept and the SDK gives you the implementation, while this repository gives you a complete small agent you can run and then modify. If you learn better by reading a reference than by editing working code, the docs and SDK are the better path, and you will avoid inheriting a recipe's assumptions about project layout.

Maintenance cost and what to check before forking

The repository is not archived and the last push was on 2026-09-15, so the collection is being touched. That says nothing about any individual recipe. With no releases retrieved, there is no versioned artefact to track, which means the cost of adopting a recipe is the cost of owning a fork from the moment you copy it.

Before you copy, check three things. First, that the recipe directory has its own README.md with setup and run instructions, since the root README delegates that entirely. Second, that the recipe's language matches the ADK SDK you have installed, because the prerequisites section lists five separate SDK repositories. Third, that the recipe's pyproject, if it has one, aligns with the repository's expectations, which is what the align-recipe-pyproject skill and the validate console script exist to check.

After you fork, the validate script is your only automated signal that you have not broken the repository's conventions, and it validates against repository rules rather than against your application's needs. Budget for replacing that check with your own tests early. The Apache-2.0 licence means you can do that freely, provided you keep the licence and attribution intact.

Editorial conclusion

Adopt google/adk-samples if you want a runnable ADK starting point to fork rather than a blank directory, and if you accept the README's own framing that recipes are for demonstration. Skip it if you need a supported Google product, a security-response commitment, or a production dependency: the disclaimer explicitly rules those out. Verify first that the recipe you pick has its own README with setup and run instructions, that the language directory matches the ADK SDK you actually use, and that any recipe you fork still passes the repo's own validate script after you edit it.

Frequently asked questions

Official sources

1. google/adk-samples on GitHub
2. Issues
3. License: Apache-2.0
4. Project website
5. README