Go Agent Development Kit

Build production-ready AI agents in Go with a batteries-included toolkit. The Go Agent Development Kit (GADK) wraps language models, tool execution, retrieval-augmented memory, and multi-agent coordination behind a pragmatic API so you can focus on domain-specific logic instead of orchestration plumbing.

1. Why GADK?
2. Key Features
3. Architecture Overview
4. Quick Start
5. Configuration & Extensibility
6. Advanced Memory Engine
7. Development Workflow
8. Troubleshooting Tips
9. Contributing

Modern agents demand more than a single model call—they require deterministic session orchestration, reusable tool adapters, rich memory, and safe extensibility. GADK provides:

• A composable runtime that stitches together models, tools, memory, and sub-agents.
• Opinionated defaults that stay out of your way when you need to customise.
• Production-friendly patterns drawn from the Google Agent Development Kit terminology.

Whether you are experimenting locally or embedding agents inside an existing service, GADK provides a consistent foundation.

• Runtime orchestration – pkg/runtime exposes a single entry point for constructing an agent runtime with configurable models, tools, memory engines, and sub-agent registries. A thread-safe session manager keeps execution deterministic.
• Coordinator + specialists – pkg/agent contains the core coordinator logic, while pkg/subagents demonstrates how to plug in specialist personas (for example, a researcher) through a ToolCatalog and SubAgentDirectory abstraction.
• Tooling ecosystem – Implement the agent.Tool interface and register implementations (echo, calculator, clock, etc.) under pkg/tools. Tools become available to the coordinator prompt automatically.
• Retrieval-augmented memory – pkg/memory layers importance scoring, weighted retrieval (similarity, recency, source, importance), maximal marginal relevance, summarisation, and pruning strategies over pluggable vector stores (PostgreSQL + pgvector, Qdrant, in-memory).
• Model abstraction – pkg/models defines a slim Generate(ctx, prompt) interface with adapters for Gemini 2.5 Pro and dummy models for offline testing. Other providers (Anthropic, Ollama) can slot in via the same contract.
• Universal Tool Calling Protocol (UTCP) – Native UTCP support enables the runtime to describe and invoke tools through a modern, provider-agnostic contract.
• Command-line demo – cmd/demo showcases tool usage, delegation, and memory persistence through a configurable CLI conversation.

At the heart of the kit is runtime.Config. Supply model loaders, tool/sub-agent registries, and a memory factory and the runtime handles schema creation, session lifecycle, and safe concurrent access.

• Go 1.22+
• PostgreSQL 15+ with the pgvector extension (optional for local experimentation, required for long-term memory persistence)
• Gemini API key exported as GOOGLE_API_KEY or GEMINI_API_KEY

Install the pgvector extension and let the CLI bootstrap schemas automatically:

Flags let you customise the coordinator model (--model), session identifier (--session), context limit (--context), and short-term memory window (--window). Provide additional prompts as positional arguments to override the default script.

• Swap language models – Implement models.Agent or use bundled adapters (Gemini, Anthropic, Ollama). Provide a loader via runtime.Config.CoordinatorModel.
• Add or remove tools – Implement agent.Tool and append instances to runtime.Config.Tools. Tools follow the tool:<name> invocation pattern.
• Register sub-agents – Add agent.SubAgent implementations to runtime.Config.SubAgents and delegate in conversation with subagent:<name> do something.
• Memory backends – Use the default Postgres store or supply a custom MemoryFactory / SessionMemoryBuilder for in-memory or third-party vector stores.

The pkg/memory package exposes an Engine that composes retrieval heuristics, clustering, and pruning on top of any VectorStore.

Tune retrieval with runtime flags (no YAML required):

Schema migrations rely on online-safe ALTER TABLE ... IF NOT EXISTS statements to avoid downtime.

1. Write or update Go code.
2. Format as needed (gofmt or your editor tooling).
3. Run the full test suite:
4. Update documentation and examples when adding new tools, models, or memory backends.

• Missing pgvector extension – Ensure CREATE EXTENSION vector; runs before connecting. Without it the Postgres-backed memory store cannot create required columns.
• API key issues – Confirm GOOGLE_API_KEY or GEMINI_API_KEY is exported in the same shell where you run the demo.
• Tool discovery – When adding tools or sub-agents, verify their names are unique to avoid collisions in the catalog/directory registries.
• Deterministic tests – Use the dummy model adapter for repeatable results when writing unit tests around orchestration logic.

Issues and pull requests are welcome! Please update the README and examples when contributing new models, tools, or memory backends so the community benefits from your additions.