Adk Sample Creator

ADK Go sample creator

An example earns its place by teaching one thing faster than the package docs can. It must run. Two families set the standard, and which one you are writing decides several of the choices below:

• Engine samples — examples/workflow/*. They exercise ADK itself, need nothing beyond the binary and sometimes a model, and their subject is the shape of a graph.
• Integration samples — examples/agentregistry/*. They talk to a live external service, so they carry cloud prerequisites, credentials, failures worth unwrapping, and output that depends on the reader's own project.

Copy the shape of the nearer family rather than inventing one.

examples/README.md documents an older launcher API (ParseAndRun, FormatSyntax). Follow the templates here, not that file.

Layout

examples/<area>/<name>/
├── main.go
└── README.md

lower_snake directory names (hitl_simple), nested by theme once a family grows (routing/llm, dynamic/hitl). When the area keeps an index table — examples/workflow/README.md and examples/agentregistry/README.md do — add a row with the same columns as its neighbours, including LLM?. Most areas keep none, and none is needed.

main.go

Copy templates/main.go.tmpl: it carries the Apache 2.0 header the goheader linter demands, the package doc line, and the launcher wiring. context.Background() is correct there — main is an entrypoint, and it stays banned in library code.

full.NewLauncher() serves console, which is the default, plus web and its api, a2a, webui, pubsub and eventarc sublaunchers. When anything is deferred, move the body into run(ctx) error and let main do the log.Fatal.

Each of these has cost a review round:

• Pick a versioned model, not a -latest alias, in any sample whose README documents the Vertex AI path: Vertex does not serve the aliases, so the documented instructions would fail at model construction. gemini-3.5-flash answers on both backends.
• A required variable is read plainly and checked for empty, failing with a message that names it; cmp.Or(os.Getenv("X"), "default") is for the optional ones, and hides a missing value if you reach for it first. Watch for a variable a neighbouring library also reads: GOOGLE_CLOUD_LOCATION steers genai and the Agent Registry client, so a region meant for the model silently moves the catalog lookup.
• log.SetFlags(0) when the output is a transcript. Otherwise every line carries a timestamp, and a README that omits it is showing output the code cannot produce.
• log.Fatal only from main. Inside a body that defers a close, it skips the defer.
• Render API failures as something actionable — unwrap the typed error and keep the part that identifies the fix (see explain in the agentregistry samples), rather than printing the service's whole JSON envelope.
• Comments say WHY. Never narrate the next line.

README

Copy templates/README.md.tmpl and fill the placeholders in; it spells out what each section is for. The order is fixed — title and the Concept / Needs LLM? block, Goal, Requirements, How it works, Running the sample, Example session, What it shows, Notes — but Requirements, What it shows and Notes come out when they have nothing to say.

Older examples call the third section Authentication and the fourth Workflow; leave those alone. Use the template's names for anything new, with one exception: an engine sample really is built on a workflow graph, so Workflow stays the truer heading there, over a node-graph diagram rather than a sequence. An integration sample is the case the template is cut for — Requirements earns its place because an enabled API and an IAM role are not credentials, and the diagram is a sequence because the interesting part is what happens once, at startup, versus what happens on every turn.

Mermaid

Mermaid is the repo default; no ASCII art. Reach for sequenceDiagram first: a sample is a sequence of calls, and the ordering is usually the point — a flow chart that mixes startup with the first user turn hides that resolution happened once, before the agent existed. Use graph LR/graph TD when the subject really is a topology, such as an engine sample's node graph.

The transcript is evidence

• Paste output you actually got. Never invent it, never tidy it up.
• Say where it came from and which part generalizes: "Real output from a project with the Cloud Logging API enabled, abridged in the middle. Your logs will differ."
• Abridge with ..., and say that you did.
• When the sample is deterministic, say so: "No model runs here, so the output is exactly this." That is the answer to "is this reproducible?" — a question reviewers do ask.
• Anonymize project IDs to my-project; leave generated resource IDs structurally intact.

Prose

Write so a reviewer never has to read a sentence twice. Do not build an antithesis whose second half points back at a noun two clauses ago — state the rule, then the exception, in separate sentences. And state each fact once: the same explanation in a doc comment, the How it works section and the Notes is two copies too many.

Before you call it done

From the repo root, with a workspace (test -f go.work || go work init && go work use -r .):

go build -mod=readonly work
go vet ./examples/...
golangci-lint run
go mod tidy -diff

Then run the sample and paste what it printed into the README. Examples are part of the root module, so one that does not compile breaks CI for everyone.

Final check:

• row added to the area's index table, if it keeps one
• every environment variable the code reads is in the table
• the transcript is real output, and says what about it generalizes
• license header present, golangci-lint run clean
• it runs