adk: Instructions file for Codex

Inference Gateway A2A ADK

README for AI coding agents working in this repository. See README.md for user-facing docs and CONTRIBUTING.md for the full contributor workflow.

Project Overview

Go library for building Agent-to-Agent (A2A) protocol agents. Module path: github.com/inference-gateway/adk. Core packages: client/ (JSON-RPC client), server/ (server builder, task handlers, agent, storage, artifacts, middlewares, telemetry), types/ (protocol types). It is not a binary - main.go is a placeholder. The root module and every examples/<scenario>/client and examples/<scenario>/server directory are separate Go modules, each example with its own docker-compose.yaml (run with cd examples/<name>/server && go run .). Examples are how users learn the API and broken examples do not surface in unit tests; scan them when changing public surfaces.

Commands

Run from the repo root; task --list lists all targets.

• task format - gofmt on Go files, Prettier on Markdown
• task lint - golangci-lint run; task lint:examples runs markdownlint --fix on example Markdown
• task test - go test -v -cover ./...; single test: go test -run TestNameRegex -v ./server/...
• task tidy - go mod tidy in every module (root + examples)
• task a2a:download-schema + task a2a:generate-types - refresh the vendored schema.yaml and regenerate types/generated_types.go
• task providers:download-schema + task generate:providers - refresh providers-schema.yaml and regenerate provider artifacts (.env.example, docker-compose.yaml, READMEs)
• task generate:mocks (generate:mocks:clean to wipe first) - regenerate Counterfeiter mocks in client/mocks/ and server/mocks/
• task generate - umbrella for types, providers, and mocks
• task precommit:install - install the pre-commit hook (format, tidy, mocks, lint, test; fails if files stay dirty)

Architecture

• Server is assembled with A2AServerBuilder: gin HTTP/JSON-RPC layer (/.well-known/agent-card.json discovery, /a2a JSON-RPC entrypoint), task storage, task handlers, an optional LLM agent, and optional artifact storage.
• Two task-handler interfaces, deliberately distinct: TaskHandler.HandleTask (sync/queued path for SendMessage and the background processor) and StreamableTaskHandler.HandleStreamingTask (returns a channel of CloudEvents for SendStreamingMessage and SubscribeToTask; event types are the EventXxx constants in types/types.go). WithDefaultTaskHandlers() installs implementations that handle input-required pausing; use WithBackgroundTaskHandler / WithStreamingTaskHandler for custom orchestration.
• The agent is stateless. It does not own conversation history; the task's History is passed to every RunWithStream(ctx, []Message) call. Build one with AgentBuilder.
• Callbacks (server/callbacks.go): BeforeAgent/AfterAgent, BeforeModel/AfterModel, BeforeTool/AfterTool. Before callbacks short-circuit by returning non-nil; after callbacks can replace outputs. Guardrails, caching, and authorization are built on these - there is no separate middleware concept for them.
• Storage is an interface with in-memory (default) and Redis implementations, selected via QUEUE_PROVIDER.
• Artifacts run on a separate HTTP server (default port 8081, ArtifactsServerBuilder) with filesystem or MinIO backends. Proxy mode is default; ARTIFACTS_STORAGE_BASE_URL enables direct downloads. See docs/artifacts.md.
• Config (server/config/) is one Config struct loaded by sethvargo/go-envconfig with prefixed groups (AGENT_CLIENT_*, CAPABILITIES_*, AUTH_*, QUEUE_*, TASK_RETENTION_*, SERVER_*, TELEMETRY_*, ARTIFACTS_*). AgentName, AgentDescription, AgentVersion have no env tags; inject them at build time with -ldflags "-X 'github.com/inference-gateway/adk/server.BuildAgentName=...'" (likewise BuildAgentDescription, BuildAgentVersion).