Agent Development Kit (ADK) for Go

Agent Development Kit (ADK) is an open-source, code-first Go toolkit designed for building, evaluating, and deploying sophisticated AI agents. It applies software development principles to agent creation, allowing for modular multi-agent systems and flexible orchestration.

Key characteristics include:

• Model-agnostic: While optimized for Gemini, it works with other models.
• Deployment-agnostic: Supports containerization and cloud-native environments like Google Cloud Run.
• Code-first: Agent logic, tools, and orchestration are defined directly in Go for better testability and versioning.
• Concurrency-optimized: Leverages Go's strengths for high-performance agent applications.

To add the ADK Go toolkit to your Go project, use the go get command to fetch the v2 module.

go get google.golang.org/adk/v2

In ADK v2.0, session.NewEvent requires a context.Context as its first argument. This change allows the platform package to use providers (via platform.WithTimeProvider and platform.WithUUIDProvider) installed on the context to manage event IDs and timestamps, enabling deterministic and replay-safe event production.

Migration Steps:

• Replace the old parameterless-context form or NewEventWithContext with the new signature.
• Pass the existing context from the scope (e.g., the context from an agent, tool, callback, or incoming RPC/HTTP request).
• Avoid using context.Background() in the middle of call chains; thread the existing context through your helpers.

// Before
ev := session.NewEvent(ctx.InvocationID())
// or
ev := session.NewEventWithContext(ctx, ctx.InvocationID())

// After
ev := session.NewEvent(ctx, ctx.InvocationID())

The agentengine sublauncher starts an AgentEngine server that serves the reasoning engine API. This is used when deploying to Agent Engine.

Local Access URLs:

• [webUrl]/api/reasoning_engine
• [webUrl]/api/stream_reasoning_engine

Deployed Access URLs (Google Cloud):

• https://${LOCATION_ID}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION_ID}/reasoningEngines/${RESOURCE_ID}:query
• https://${LOCATION_ID}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION_ID}/reasoningEngines/${RESOURCE_ID}:streamQuery

The eventarc sublauncher adds Eventarc trigger capabilities to an ADK web server. It exposes an HTTP POST endpoint that allows triggering agent applications via Eventarc.

When running the launcher, the endpoint will be available at: {webURL}{path_prefix}/apps/{app_name}/trigger/eventarc.

The web launcher allows you to run the Agent Development Kit (ADK) using a web server. It is designed to be extended via Sublauncher implementations, which add specific routes and functionality to the server.

To use the web launcher, you must provide at least one Sublauncher. The command-line syntax follows a pattern where you specify the web command followed by its flags, and then specify the keywords for the sublaunchers you wish to activate.

Web Launcher Flags:

• -port: Localhost port for the server (default: 8080)
• -write-timeout: Server write timeout (e.g., '10s', '2m') (default: 15s)
• -read-timeout: Server read timeout (e.g., '10s', '2m') (default: 15s)
• -idle-timeout: Server idle timeout (e.g., '10s', '2m') (default: 60s)
• -otel_to_cloud: Enables/disables OpenTelemetry export to GCP (default: false)

The universal package provides a launcher.Launcher implementation that acts as a router for multiple sublaunchers (such as console or web). It selects a sublauncher based on the first command-line argument (the keyword).

Routing Logic:

• If the first argument matches a sublauncher's Keyword(), that sublauncher is used to parse the remaining arguments.
• If no arguments are provided, or the first argument does not match any known keyword, the first sublauncher in the list provided to NewLauncher is used as the default.
• Sublaunchers must have unique keywords; otherwise, NewLauncher will fail during the parsing phase.

The Eventarc sublauncher registers a specific HTTP route for triggering applications.

Endpoint: POST /{path_prefix}/apps/{app_name}/trigger/eventarc

Parameters:

• {path_prefix}: The prefix configured via the --path_prefix flag (defaults to /api).
• {app_name}: The name of the application to trigger.

Method: POST

If you are building a parent launcher (like a universal launcher) that supports multiple modes of operation (e.g., 'console' or 'web'), implement the SubLauncher interface. Each SubLauncher is activated by a specific command-line keyword.

type SubLauncher interface {
	// Keyword returns the command-line keyword that activates this sub-launcher.
	Keyword() string
	// Parse parses the arguments for the sub-launcher. It should return any unparsed arguments.
	Parse(args []string) ([]string, error)
	// CommandLineSyntax returns a string describing the command-line flags and arguments for the sub-launcher.
	CommandLineSyntax() string
	// SimpleDescription provides a brief, one-line description of the sub-launcher's function.
	SimpleDescription() string
	// Run executes the sub-launcher's main logic.
	Run(ctx context.Context, config *Config) error
}

To create a main entrypoint for an ADK application, implement the Launcher interface. This interface is responsible for parsing command-line arguments and executing the application logic. You must provide implementations for Execute and CommandLineSyntax.

type Launcher interface {
	// Execute parses command-line arguments and runs the launcher.
	Execute(ctx context.Context, config *Config, args []string) error
	// CommandLineSyntax returns a string describing the command-line flags and arguments.
	CommandLineSyntax() string
}