go-adk

Expert guidance for developing agents with google.golang.org/adk (Go ADK).

When to trigger

• The user mentions Go ADK, google.golang.org/adk, adk-go, or asks how to build agents in Go.
• The task involves ADK concepts like llmagent, tools, callbacks, sessions/state/memory, workflow agents, streaming, MCP, A2A, ADK web/API runtime, launchers, deployment, evaluation, or safety controls.

Core rules

• Treat [references/llms-index.md](references/llms-index.md) as the required ADK coverage map.
• Target the current stable Go ADK v1.x surface; as of May 5, 2026, use v1.2.0 as the default baseline unless the repo pins an older tag.
• Prefer official ADK Go APIs, package docs, and examples over ad-hoc wrappers.
• Follow existing repository patterns first (imports, launcher style, layout, env handling).
• For version-sensitive behavior, check package docs and release/docs pages before giving definitive guidance.
• Prioritize Go-specific ADK docs first; if a feature is documented only in another SDK doc, call that out explicitly and avoid presenting it as established Go API.
• Keep agent names unique and never use user as an agent name.
• Use concise Description fields so delegation and tool selection remain reliable.
• Treat ADK Web as development-only unless the user explicitly asks for production runtime choices.
• Do not mix older pre-v1 snippets with current v1 launcher/runtime patterns in the same answer.

Workflow

1. Map task to ADK domain:

- Build, run, deploy, evaluate, safety, components, protocols, or reference. - Load only the relevant sections from [references/llms-index.md](references/llms-index.md).

1. Confirm execution style:

- Launcher-first app (cmd/launcher/full for local development, cmd/launcher/prod for production-facing launchers) or embedded runtime (runner.New(...) + Runner.Run(...)). - Local CLI, dev web UI, REST/API server, or custom service loop.

1. Build the first working agent:

- llmagent.New(llmagent.Config{...}) with a concrete model (commonly gemini.NewModel(ctx, ..., &genai.ClientConfig{...})). - Add minimum viable Instruction, Description, and either Tools or Toolsets.

1. Add tools safely:

- Use functiontool.New(...) for typed custom tools. - Use mcptoolset.New(...), skills, or other ADK-native integrations only when needed. - For sensitive tools, apply confirmations, auth, and policy callbacks; prefer tool.WithConfirmation(...) for grouped toolsets.

1. Wire stateful execution:

- Sessions via session.Service (often session.InMemoryService() for local dev). - Add memory.Service only when cross-session retrieval is required. - Add artifact/state/context management only when required by the workflow.

1. Apply control points:

- Use callbacks (Before/After Agent, Before/After Model, OnModelError, Before/After Tool, OnToolError) for logging, caching, guardrails, and overrides. - Prefer plugins for reusable security policy enforcement.

1. Scale composition:

- Use workflow agents for deterministic orchestration (sequentialagent, parallelagent, loopagent). - Use multi-agent delegation (descriptions + transfer behavior) only when specialization is clear. - Use remote agents/A2A only when process or host boundaries are intentional.

1. Select runtime/deployment posture:

- Local dev: full.NewLauncher() with go run agent.go, go run agent.go web api, or go run agent.go web api webui. - Production: prod.NewLauncher() or embedded server/runtime plus deployment target, observability, and safety posture.

1. Verify behavior end-to-end:

- Validate happy-path conversation, tool errors, callbacks, session lifecycle, confirmation behavior, and evaluation criteria.

Output expectations

• Provide exact Go imports, runnable snippets, and command lines that match the chosen runtime mode.
• Call out version-sensitive behavior if the user targets older ADK tags or the repo mixes docs from multiple ADK generations.
• Mention the relevant ADK doc section when guidance comes from llms-index categories beyond core Go quickstart pages.
• Prefer small, testable incremental changes over large rewrites.

References

• Quickstart and launcher baseline: [references/quickstart.md](references/quickstart.md)
• Core APIs and agent config: [references/core-primitives.md](references/core-primitives.md)
• Tools, callbacks, and guardrails: [references/tools-and-guardrails.md](references/tools-and-guardrails.md)
• Runtime modes, examples, and A2A: [references/runtime-and-examples.md](references/runtime-and-examples.md)
• Models, versioning, and operations posture: [references/models-and-operations.md](references/models-and-operations.md)
• Required ADK source map (llms.txt-derived curated index): [references/llms-index.md](references/llms-index.md)