Overview

Relevant source files

• LICENSE
• README.md
• examples/mcp/main.go
• examples/quickstart/main.go
• examples/vertexai/agent.go
• examples/vertexai/imagegenerator/main.go
• examples/workflowagents/loop/main.go
• examples/workflowagents/parallel/main.go
• examples/workflowagents/sequential/main.go
• examples/workflowagents/sequentialCode/main.go
• internal/httprr/LICENSE

Purpose and Scope

This document provides a high-level introduction to the Agent Development Kit (ADK) for Go, a framework for building, deploying, and orchestrating AI agents. It covers the framework's architecture, core components, and how they interact to enable sophisticated agent-based applications.

For detailed information about specific subsystems, refer to:

• Agent types and implementations: Agent Types
• Tool development: Tool System
• Distributed agent communication: A2A Protocol and Distributed Agents
• Deployment options: Launcher and Deployment

What is ADK Go?

The Agent Development Kit (ADK) for Go is a code-first framework that applies software engineering principles to AI agent development. It provides a modular architecture for building agents that can interact with Large Language Models (LLMs), execute tools, maintain state, and communicate with other agents.

Key characteristics:

• Model-agnostic: While optimized for Gemini via google.golang.org/genai, supports other LLM providers
• Deployment-agnostic: Run agents locally, in containers, or on cloud platforms
• Code-first: Define agent logic, tools, and workflows directly in Go
• Modular: Compose complex systems from specialized agents
• Extensible: Plugin architecture for cross-cutting concerns

Sources: README.md1-54 go.mod1-96

High-Level System Architecture

The ADK consists of six major subsystems that work together to enable agent execution:

Diagram: Core System Architecture Layers

Architecture Overview

The architecture follows a layered design organized into six subsystems:

1. User Interface Layer: Multiple entry points (console CLI, web server, full launcher) that all funnel through runner.Runner. Example applications demonstrate common patterns.

2. Agent Orchestration Layer: The runner.Runner coordinates agent selection and execution. Agents implement the agent.Agent interface and come in multiple types: LLM-driven agents, workflow agents (sequential/loop/parallel), and remote agents using A2A protocol.

3. LLM Integration Layer: The internal/llminternal.Flow orchestrates LLM request/response cycles, including prompt building, model calls, and tool execution. Supports Gemini via model/gemini package.

4. Tool Ecosystem: Extensible tool system supporting multiple patterns:

   • functiontool: Wraps Go functions with automatic schema generation
   • agenttool: Allows agents to invoke other agents as tools
   • mcptoolset: Integrates Model Context Protocol external tools
   • Built-in tools like GoogleSearch and LoadArtifacts

5. State & Data Management: Session service manages conversation history and state. Artifact service handles file storage. Memory service provides vector search. All communication flows through session.Event streams.

6. Infrastructure: Cross-cutting concerns including OpenTelemetry integration for observability and Vertex AI integration for cloud deployment.

The runner.Runner serves as the central orchestrator, managing:

• Agent selection via findAgentToRun() based on session history
• Context creation with session, artifacts, and memory services
• Plugin callback execution at lifecycle hooks
• Event streaming from agent.Run() back to callers
• Event persistence to session.Service implementations

Sources: README.md1-54 examples/quickstart/main.go1-66 cmd/launcher/full/full.go

Core Components

Agent System

The agent system is built around the agent.Agent interface, which defines a contract for executable agents:

Diagram: Agent Type Hierarchy and Configuration

Agent Types and Implementations

The framework provides six agent implementations:

Agent Type	Constructor	Purpose	Key Fields
LLM Agent	llmagent.New(Config)	Interacts with LLMs via Flow engine	Model, Tools, Instruction, OutputSchema
Sequential	sequentialagent.New(Config)	Executes SubAgents in order	SubAgents, OutputKey for state passing
Loop	loopagent.New(Config)	Iterates SubAgents up to MaxIterations	MaxIterations, Escalate for early exit
Parallel	parallelagent.New(Config)	Runs SubAgents concurrently	sync.WaitGroup, branch isolation
Remote (A2A)	remoteagent.NewA2A(Config)	Proxies to remote agents	AgentCard, a2aclient.Client
Custom	agent.New(Config)	User-defined logic	run func(InvocationContext)

All agents return iter.Seq2[*session.Event, error] from Run() method agent/agent.go46

Diagram: Agent Execution Pipeline

Execution Flow Details

When a user message is processed, the system executes this pipeline:

1. Session Retrieval: Runner retrieves or creates session with conversation history
2. Agent Selection: findAgentToRun() determines target agent by:
   • Checking for user function responses
   • Traversing event history to find last active agent
   • Validating transfer permissions
3. Context Preparation: History processed into LLM-ready format by ContentsRequestProcessor
4. LLM Interaction: Flow manages callbacks, telemetry spans, and model communication
5. Tool Execution: Function calls trigger tool execution with full tracing
6. Event Streaming: Results flow through agent → runner → user with session persistence

Sources: runner/runner.go44-234 internal/llminternal/base_flow.go244-356

Runner and Execution Engine

The runner.Runner type orchestrates agent execution:

Diagram: Runner Components and Data Flow

Runner Execution Flow

The runner.Runner.Run() method orchestrates execution through these steps:

1. Retrieve session via SessionService.Get() runner/runner.go120-128
2. Find target agent using findAgentToRun() which:
   • Checks for user function responses via handleUserFunctionCallResponse() runner/runner.go327-350
   • Traverses event history backwards to find last active agent runner/runner.go301-319
   • Validates transfer permissions via isTransferableAcrossAgentTree() runner/runner.go353-366
3. Create context using icontext.NewInvocationContext() with:
   • Parent map for agent hierarchy navigation runner/runner.go138
   • Plugin manager for callback execution runner/runner.go142
   • Artifacts, memory, and session services runner/runner.go145-162
4. Append user message via appendMessageToSession() runner/runner.go172-177
   • Optionally converts inline blobs to artifacts runner/runner.go261-275
5. Execute plugins: RunBeforeRunCallback() can short-circuit runner/runner.go184-197
6. Run agent via agent.Run(ctx) runner/runner.go200
7. Process events in loop:
   • Call RunOnEventCallback() for each event runner/runner.go209-218
   • Persist non-partial events via SessionService.AppendEvent() runner/runner.go222-227
   • Yield to caller runner/runner.go229-231

Agent Selection Algorithm

The findAgentToRun() method implements agent routing logic:

Sources: runner/runner.go44-234 runner/runner.go292-379

Tool Ecosystem

Tools provide agents with capabilities beyond language generation:

Diagram: Tool Interface Hierarchy and Implementations

Diagram: Tool Creation Patterns and Tool Interface

Tool Types and Usage

Tool Type	Package	Purpose	Key Methods/Fields
Function Tool	tool/functiontool	Wraps Go functions	New<FileRef file-url="https://github.com/google/adk-go/blob/da1d6a56/TArgs, TResult" undefined file-path="TArgs, TResult">Hii</FileRef>
MCP Toolset	tool/mcptoolset	MCP protocol client	New(Config{Transport})
Google Search	tool/geminitool	Gemini search integration	GoogleSearch{} (zero-value)
Agent Tool	tool/agenttool	Invoke agents as tools	New(agent.Agent, *genai.Schema)
Load Artifacts	tool/loadartifactstool	Access session blobs	New()
Transfer Tool	internal/llminternal	Agent delegation	Auto-injected by Flow

Tools receive a tool.Context interface providing access to:

• Artifacts(): Session file storage operations
• State(): Read/write session state
• Actions(): Emit actions like Escalate, TransferToAgent, or StateDelta

Sources: tool/functiontool/functiontool.go1-150 tool/mcptoolset/mcptoolset.go1-100 internal/llminternal/base_flow.go538-630

Function Tool Creation and Execution

The functiontool package wraps Go functions with automatic schema generation:

Tool Context and Event Actions

Tools receive a tool.Context providing access to session services and the ability to emit actions:

Sources: tool/functiontool/functiontool.go1-150 tool/mcptoolset/mcptoolset.go1-100 tool/geminitool/google_search.go1-50

Session Management and State

Sessions provide persistence and state management:

Diagram: Session Service Architecture and State Scopes

Diagram: Session Service Architecture and State Scopes

Session Service Implementations

Implementation	Package	Storage	Use Case	Key Features
InMemoryService	session/session.go	RAM (omap.Map)	Development/testing	Fast, order-preserving
DatabaseService	session/database	SQL (GORM)	Production	PostgreSQL, MySQL, SQLite, Spanner
VertexAIService	session/vertexai	GCP	Cloud deployment	Reasoning Engine integration

State Scopes and Persistence

The state system uses key prefixes to determine scope and lifecycle:

• app: - Application-wide state shared across all users and sessions (persisted)
• user: - User-specific state shared across that user's sessions (persisted per user)
• (no prefix) - Session-specific state for single conversation (persisted)
• temp: - Temporary state for current invocation only (NOT persisted)

State is modified via session.EventActions.StateDelta which is merged during AppendEvent().

Event Processing and State Deltas

Events carry StateDelta which is merged into state during AppendEvent():

Sources: session/session.go1-200 session/database/session.go1-300 session/vertexai/session.go1-150

LLM Integration Layer

The Flow engine manages LLM interactions:

Diagram: Flow Engine Request/Response Pipeline

Diagram: LLM Flow Request and Response Processing

Flow Execution Lifecycle

The internal/llminternal.Flow.Run() method orchestrates LLM interactions:

1. Request Processing: 12 RequestProcessors transform the model.LLMRequest

   • ContentsRequestProcessor converts session history to []genai.Content
   • eventBelongsToBranch() filters events by branch for agent isolation
   • rearrangeEventsForLatestFunctionResponse() ensures proper function call/response pairing
   • Tools can inject additional request modifications via RequestProcessor.ProcessRequest()

2. Model Call: Execute via generateContent()

   • Wraps call with OpenTelemetry span via telemetry.StartGenerateContentSpan()
   • Executes BeforeModelCallbacks (can return cached response)
   • Calls model.GenerateContent(ctx, req, useStream)
   • Logs request/response via telemetry
   • Aggregates streaming responses
   • Executes AfterModelCallbacks

3. Tool Execution: Process function calls from model

   • handleFunctionCalls() creates toolinternal.ToolContext with session services
   • Each tool wrapped with telemetry span
   • RunBeforeToolCallback() can skip execution
   • Invoke tool.Run(toolCtx, args) with type conversion
   • RunAfterToolCallback() for post-processing
   • Merge parallel tool results

4. Response Processing: Apply ResponseProcessors

   • nlPlanningResponseProcessor handles natural language planning
   • codeExecutionResponseProcessor handles code execution responses

5. Event Finalization: Create and yield session.Event

   • Set Author, Branch, InvocationID
   • Populate LLMResponse with model output
   • Include Actions.StateDelta for state updates
   • Mark LongRunningToolIDs for async operations

Sources: internal/llminternal/base_flow.go244-630 internal/llminternal/contents_request_processor.go1-250

A2A Protocol and Remote Agents

The A2A (Agent-to-Agent) protocol enables distributed agent systems:

A2A Protocol Overview

ADK agents can act as both A2A clients and servers:

As client (via remoteagent.NewA2A()):

• Creates proxy agent that converts local session history to a2a.Message format
• Wraps non-target agent events as context
• Sends via HTTP/WebSocket transport
• Converts received a2a.Event back to session.Event

As server (via adka2a.Executor):

• Exposes local ADK agents via A2A JSON-RPC protocol
• Manages task state machine (Submitted/Working/Completed/Failed/InputRequired/Canceled)
• Converts ADK session.Event to a2a.Event format
• Handles long-running tools requiring user input mid-execution

Sources: High-level diagrams (Diagram 5), go.mod47

Entry Points and Deployment

Diagram: Deployment Architecture Options

ADK provides multiple deployment patterns with consistent agent code:

Entry Point	Type	Use Case	Implementation
Console CLI	Interactive REPL	Local development, debugging	console.Launcher
Web Server	HTTP endpoints	Web applications, integrations	web.Launcher
Full Launcher	Combined modes	All-in-one deployment	full.NewLauncher()
A2A Server	JSON-RPC	Agent-to-agent communication	adka2a.Executor

Deployment Modes:

1. Local Development: Use console.Launcher or web.Launcher with session.InMemoryService() for rapid iteration

2. Cloud Run: Deploy containerized web.Launcher with session/database and cloud storage for production-grade persistence

3. Vertex AI: Deploy to managed Reasoning Engine with session/vertexai for simplified operations

4. Distributed A2A: Deploy agents independently using adka2a.Executor and connect via remoteagent.NewA2A() for microservices architecture

Key Insight: Agent definitions (llmagent.Config, tools, instructions) are deployment-agnostic. Only launcher and service configurations change between environments, enabling local development with production parity.

Sources: cmd/launcher/console/console.go cmd/launcher/web/web.go examples/quickstart/main.go34-65 examples/vertexai/agent.go38-77

Key Dependencies and Technologies

Diagram: External Dependencies and Integration Points

The ADK integrates with several external systems and technologies:

Dependency	Purpose	Package	Usage in ADK
Gemini API	LLM provider (primary)	google.golang.org/genai	model/gemini wraps client
A2A Protocol	Agent-to-agent communication	github.com/a2aproject/a2a-go	agent/remoteagent and server/adka2a
MCP	External tool integration	github.com/modelcontextprotocol/go-sdk	tool/mcptoolset
GORM	Database ORM	gorm.io/gorm	session/database
Vertex AI	Cloud deployment	cloud.google.com/go/aiplatform	session/vertexai
OpenTelemetry	Observability	go.opentelemetry.io/otel	telemetry package

The framework follows Go idioms and leverages:

• Go 1.23+ features: iter.Seq2 for streaming events from agent.Run()
• Context propagation: All operations receive context.Context
• Interface-driven design: Core types like agent.Agent, tool.Tool, session.Service are interfaces
• Structured concurrency: sync.WaitGroup for parallel agents, channels for event streaming

Sources: go.mod1-96 agent/agent.go34-50

Getting Started

To begin using ADK Go:

1. Install: go get google.golang.org/adk
2. Review examples: See the examples/ directory in the repository
3. Follow tutorials: Start with Quick Start Tutorial
4. Explore agent types: Learn about LLM Agents and Workflow Agents
5. Deploy: Choose from local development or cloud deployment

For comprehensive documentation, see the full wiki at https://google.github.io/adk-docs/

Sources: README.md40-46