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.