How google/adk-go works
Project Type and Purpose
• This is a full-stack, code-first Go toolkit (Agent Development Kit, ADK) designed to build, orchestrate, evaluate, and deploy AI agents.
• The repository combines:
• A core Go library (packages under agent/, artifact/, model/, tool/, session/, telemetry/, internal/…)
• CLI deployment tooling (cmd/adkgo, cmd/launcher/…)
• A REST/HTTP server exposing agent APIs (server/adka2a, server/restapi)
• Example apps demonstrating usage (examples/…).
High-Level File-Structure Analysis
• Top-Level Components:
• agent/, artifact/, model/, tool/: Core domain logic for agents, artifacts, LLM models, and tools.
• internal/…: Implementation details (e.g., LLM integration, converters, memory, session internals, HTTP-RR test harness).
• cmd/: Two sets of CLIs – the primary adkgo (for building/deploying agents) and launcher (various runtime entry points: console, web UI, prod, universal).
• server/: Two HTTP surfaces – adka2a (agent-to-agent orchestration) and restapi (CRUD and runtime endpoints for sessions, artifacts, eval).
• session/: Session management backends (in-memory, GORM-based database, Vertex AI).
• examples/: Sample programs illustrating agent use-cases (A2A, quickstart, workflow agents, web).
• Supporting packages: memory/, runner/, util/, plus CI configs and licensing.
README Insights
• The README emphasizes:
• “Modular multi-agent systems”
• “Rich tool ecosystem”
• Model-agnostic (optimized for Gemini but pluggable)
• Deploy anywhere (e.g., Google Cloud Run)
a. Main Components
1. ADK Core Library (grouped into logical subcomponents):
– Agent Engine (agent/, agent/llmagent/, agent/workflowagents/)
– Tool Framework (tool/, internal/toolinternal/)
– Artifact Service (artifact/, internal/artifact/)
– Model Abstraction (model/, internal/llminternal/)
– Session & State Management (session/, internal/sessioninternal/, internal/telemetry/)
– Memory Store (internal/memory/)
2. Deployment Surfaces:
– CLI (cmd/adkgo, cmd/launcher/*)
– REST API Server (server/adka2a, server/restapi/)
3. External Dependencies:
– LLM Providers (Gemini, Vertex AI, other OpenAI-style endpoints)
– Artifact Storage (GCS via artifact/gcs/)
– Session Store (Relational DB via GORM in session/database/)
– Cloud Platform (e.g., Google Cloud Run)
4. Supporting Services:
– Logging & Telemetry pipeline
– HTTP-RR test harness
b. Relationships & Data Flows
• CLIs and REST endpoints invoke the Agent Engine in ADK Core.
• The Agent Engine coordinates:
• LLM calls via model/ and internal/llminternal/ to external services.
• Tool invocation via tool/ interfaces.
• Artifact storage & retrieval via artifact/.
• Session read/write via session/ backends.
• Memory operations via internal/memory/.
• Agent workflows (sequential, parallel, looping) orchestrate multi-step logic.
• Results, logs, and metrics feed into the telemetry pipeline.
c. Architectural Patterns & Principles
• Package-level modularity, interface abstractions for pluggable LLMs, tools, storage.
• Test-driven structure with HTTP-RR for integration verification.
• Separation of concerns: core library vs. CLIs vs. servers vs. examples.
• Workflow agents implement common orchestration patterns.
• Cloud-native deployment via containerizable CLIs or REST servers.
d. Key Technologies & Frameworks
• Go / Go modules
• GORM (for relational session store)
• HTTP REST (via standard net/http)
• Google Cloud Run & GCS clients
• Gemini API / Vertex AI SDK