AGENTS.md · google/adk-go

Sections

1. Project overview
2. Skills
3. Setup & core commands
4. Definition of done
5. Repository layout
6. Conventions & idioms
7. Logging and error messages
8. Comments
9. Extending the framework
10. API shape
11. Multi-module development
12. Testing
13. Boundaries
14. Before you open a PR
15. Self-review
16. PRs & commits
17. Alignment with adk-python
18. Resources

First lines (shown under the repo's Apache-2.0 license)

# AGENTS.md

Context for AI coding agents (Claude Code, Gemini CLI, Cursor, Copilot, etc.)
working in the ADK Go repository. Human contributors should start with
CONTRIBUTING.md.

## Project overview

ADK Go (`google.golang.org/adk/v2`) is an open-source, code-first Go toolkit for
building, evaluating, and deploying AI agents. It is model-agnostic but
optimized for Gemini, and is one of several ADK implementations — Go, Python,
Java, Kotlin, and TypeScript — that share a conceptual model but are independent
codebases. Requires the Go version declared in `go.mod`.

Development happens on `main`, the 2.x line. `v1` is the maintenance branch for
1.x; target it only for fixes that must ship to 1.x. See
[Branches](CONTRIBUTING.md#branches).

## Skills

See [AI-assisted development](CONTRIBUTING.md#ai-assisted-development) in
`CONTRIBUTING.md` for what this repo ships. The rule for agents: task-specific
instructions live in `.agents/skills/<name>/SKILL.md`, and you read the matching
one before starting that kind of work.

## Setup & core commands

This repo is multi-module: the root module `google.golang.org/adk/v2` plus
`plugin/agentanalytics`. Set up a Go workspace first — `go.work` is local-only
and gitignored, and `go work init` fails if one already exists:

```bash
test -f go.work || go work init
go work use -r .
```

Then run from the repo root. The `work` pattern spans every module in the
workspace, while `./...` matches only the module you are standing in:

- Build:       `go build -mod=readonly work`
- Test:        `go test -race -mod=readonly -count=1 -shuffle=on work`
- Single pkg:  `go test -race ./agent/...`
- Lint:        `golangci-lint run`   (per module; v2, CI pins v2.3.1; config in `.golangci.yml`)
- Tidy check:  `go mod tidy -diff`   (per module; must print nothing)
- Format:      `golangci-lint fmt`   (per module; applies gofumpt + goimports)

Without a `go.work`, `work` silently falls back to the root module alone and
still exits 0, so confirm the workspace exists before trusting a green run.

Install the same `golangci-lint` CI uses. A newer release reports findings CI
does not, which reads as a failure you did not cause:

```bash
go install github.com/golangci/golangci-lint/v2/cmd/golangci-lint@v2.3.1
```

`golangci-lint` and `go mod tidy` are per-module, so a run from the repo root
covers only the root module. This loop covers every module the way CI does:

```bash
for m in $(find . -name go.mod -not -path './.git/*' -exec dirname {} \;); do
  ( cd "$m" \
    && go mod tidy -diff \
    && go build -mod=readonly ./... \
    && go test -race -mod=readonly -count=1 -shuffle=on ./... \
    && golangci-lint run ) || echo "FAILED: $m"
done
```

`golangci-lint run` reports formatting problems too, as `gofumpt` and
`goimports` findings, but it does not fix them. `golangci-lint fmt` rewrites
the files in place, and `golangci-lint fmt --diff` shows what it would change
without writing anything.

## Definition of done

A change is complete only when all of these pass locally:

1. `go build` (above) succeeds.
2. `go test` (above) is green.
3. `golangci-lint run` reports no findings, in every module.
4. `go mod tidy -diff` prints nothing, in every module.
5. New/changed behavior has tests, and each one has been seen to fail with the
   source change reverted. See [Before you open a PR](#before-you-open-a-pr).
6. Every new Go file starts with the Apache 2.0 license header (enforced by `goheader`).
7. The root `go.mod` does not require an in-repo submodule (enforced by the
   `guardrail` CI job).

## Repository layout

- `agent/`     Agent interface + types (`llmagent`, `remoteagent`, `workflowagent`;
  `workflowagents/` holds `loopagent`, `parallelagent`, `sequentialagent`)
- `runner/`    Execution engine that drives the run loop
- `workflow/`  Node/graph-based workflow engine for multi-agent apps
- `model/`     LLM abstraction (`gemini`, `apigee`, `anthropicmodel`, `openaimodel`)
- `tool/`      Tool/Toolset interface + built-in tools (incl. `skilltoolset/`, `mcptoolset/`)
- `session/`   Conversation state + events
- `memory/`, `artifact/`   Long-term memory and file/data services
- `auth/`      Credentials and auth providers for outbound requests
- `agentregistry/`  Client for Google Cloud Agent Registry (A2A agents, MCP servers, models)
- `plugin/`    Cross-cutting lifecycle hooks; `plugin/agentanalytics` is a separate module
- `server/`    HTTP servers (`adkrest` is primary; `adka2a`, `agentengine`)
- `cmd/`       CLI (`adkgo`) and server launchers
- `telemetry/`, `util/`   Public helper packages
- `platform/`  Overridable seams for time & UUID generation (deterministic tests)
- `internal/`  Private packages — NOT public API; `internal/httprr` is vendored
- `exp/`       Experimental features, one package each — public but NOT stable API
- `examples/`  Runnable example agents (quickstart, tools, a2a, skills, …)
- `scripts/`   Repo tooling (ADK Web container build and asset refresh)

## Conventions & idioms

- **Streaming:** agent runs return `iter.Seq2[*session.Event, error]`; consume
  with `for event, err := range … {}`. Don't collect events into a slice.
- **Interface-first:** the core abstractions are interfaces — `agent.Agent`,
  `tool.Tool`, `tool.Toolset`, and a separate `Service` interface in each of
  `session`, `artifact` and `memory`. Concrete implementations live in
  sub-packages or `internal/`, except the in-memory ones, which sit beside the
  interface they implement.
- **Callbacks over subclassing** (`Before*`/`After*` for Agent/Model/Tool). A
  `Before` model or tool callback short-circuits the underlying call when it
  returns either a non-nil result or a non-nil error. `BeforeAgentCallback`
  behaves differently: only non-nil content short-circuits, and returning an
  error surfaces that error without stopping the agent from running.
- **Errors:** wrap with `fmt.Errorf("…: %w", err)`. Use `%v` only when
  deliberately not exposing the wrapped error's type. Don't convert existing `%w` to `%v`;
  it might break callers silently. Wrap sentinels first:
  `fmt.Errorf("%w: …: %w", ErrX, err)`. Tool confirmation uses sentinel errors
  (e.g. `tool.ErrConfirmationRequired`).
- Prefer an existing helper over a new one; keep packages small and focused.

## Logging and error messages

Never put user or model data into a log line or an error message. Prompts,
model output, tool arguments and results, session and event contents, request
and response bodies, headers, credentials, tokens and API keys are customer
content or security material, at every level including debug. Log the shape
instead — a type, a count, a length, an ID you generated — so a failure stays
diagnosable without recording what the user said.

The rule covers any error you construct or wrap, and any test assertion message
that would echo a payload. URLs are not exempt: query parameters carry tokens
and identifiers.

Library code does not write diagnostics to a process-wide sink. That rules out
the standard `log` package's logger, `slog`'s default logger and its
package-level functions, `os.Stdout` and `os.Stderr`, `fmt.Print*`, and
`print`/`println`. An application embedding ADK can neither silence nor route
any of them. `forbidigo` enforces this in `golangci-lint`. Code under `cmd/` and
`examples/`, tests, and `plugin/loggingplugin` are exempt, because each of them
owns the terminal it writes to.

ADK has no logger for library code to write through yet, so return the error to
the caller instead. When that is impossible and a maintainer agrees the call
site in review, mark the line
`//nolint:forbidigo // <why the error cannot be returned>`. Call sites that
predate the rule carry `//nolint:forbidigo // pre-slog call site`; do not copy
that marker onto new code.

Every diagnostic ADK emits through `log/slog` uses the levels below. `TRACE` is