handler.go

Overview

The handler.go file defines the main HTTP handler setup for the ADK REST API server. It constructs and configures a top-level HTTP router that serves the REST API endpoints related to agent sessions, runtime execution, applications, debugging, artifacts, and evaluation. This handler serves as the entry point for all incoming HTTP requests targeting the ADK REST API.

Key responsibilities of this file include:

• Initializing telemetry tracing exporters and span processors to enable observability of API server operations.

• Creating a gorilla/mux router instance and composing it from modular subrouters that handle different API areas.

• Wiring controllers to their respective subrouters, passing in service dependencies from the launcher configuration.

• Providing a single consolidated http.Handler that can be registered with an HTTP server.

This file plays a critical role in the REST API and Web Launchers topic by integrating routing, telemetry, and controller components into a unified HTTP handler serving the agent ecosystem.

Detailed Explanation of Components

Function: NewHandler

func NewHandler(config *launcher.Config) http.Handler

• Purpose:
  Creates and returns a fully configured http.Handler that serves the ADK REST API endpoints.

• Parameters:

  • config *launcher.Config — Configuration object providing initialized service instances such as session service, agent loader, artifact service, and telemetry options.

• Returns:

  • http.Handler — A configured HTTP router that dispatches requests to various ADK REST API controllers.

• Description:
  The function first creates an OpenTelemetry span exporter specific to the API server by calling services.NewAPIServerSpanExporter(). This exporter is added to the global telemetry tracer provider with a simple span processor, enabling tracing of HTTP requests and internal operations.

  Then, it initializes a mux.Router with strict slash matching enabled. The router is composed by calling setupRouter with a list of subrouters, each created by calling constructors from the routers package. These subrouters encapsulate routing and controller logic for:

  • Sessions API

  • Runtime API (agent execution)

  • Apps API (agent listing)

  • Debug API (debugging and tracing)

  • Artifacts API

  • Evaluation API

  Each subrouter is instantiated with its corresponding controller, which receives necessary dependencies from the passed config.

• Usage Example:

  config := launcher.LoadConfig()
  handler := adkrest.NewHandler(config)
  
  http.ListenAndServe(":8080", handler)
  

  This example sets up the HTTP server to listen on port 8080 and serve the ADK REST API endpoints configured by the handler.

Function: setupRouter

func setupRouter(router *mux.Router, subrouters ...routers.Router) *mux.Router

• Purpose:
  Registers multiple subrouters onto the main mux.Router.

• Parameters:

  • router *mux.Router — The root router instance to which subrouters will be attached.

  • subrouters ...routers.Router — Variadic parameter accepting any number of subrouter implementations.

• Returns:

  • *mux.Router — The same root router after subrouters have been set up.

• Description:
  Delegates the actual attachment of subrouters to routers.SetupSubRouters, which iterates through each subrouter and configures its routes on the root router. This enables modular organization and separation of concerns between different REST API endpoint groups.

• Usage Example:

  router := mux.NewRouter()
  sub1 := routers.NewSessionsAPIRouter(...)
  sub2 := routers.NewRuntimeAPIRouter(...)
  setupRouter(router, sub1, sub2)
  

Important Implementation Details

• Telemetry Integration:
  The file integrates with OpenTelemetry tracing by creating a span exporter for the API server and registering it with a simple span processor. This ensures that all HTTP requests and internal operations within the API server are traced and can be observed for performance and debugging purposes. This aspect ties into the Telemetry and Observability topic.

• Router Modularity:
  The design uses modular subrouters, each encapsulating a separate API domain. This modularity allows for easy addition or removal of API groups and simplifies maintenance by isolating route definitions and controller dependencies.

• Dependency Injection via Config:
  Controllers receive their required services (session service, artifact service, agent loader) through the launcher configuration object, enabling loose coupling and easy substitution of implementations (e.g., in-memory vs. database-backed session services).

• TODO for API Path Prefix:
  A noted TODO indicates future support for customizable API path prefixes, which would allow serving the REST API from a configurable base path instead of the root.

Interaction with Other Parts of the System

• Launcher Configuration (launcher.Config):
  Provides service instances and dependencies injected into controllers. This config is typically constructed during application startup and includes initialized session services, artifact services, and agent loaders.

• Controllers (from controllers package):
  Each controller implements HTTP handlers for its respective API area:

  • SessionsAPIController handles session lifecycle endpoints.

  • RuntimeAPIController manages agent execution endpoints.

  • AppsAPIController provides agent and app listings.

  • DebugAPIController supports debugging and tracing.

  • ArtifactsAPIController manages artifact-related endpoints.

• Routers (from internal/routers package):
  Define route patterns and associate them with controller handlers. Each subrouter corresponds to a controller set and is registered on the root router.

• Telemetry (from internal/telemetry and sdktrace):
  Span processors and exporters are set up here to trace API server operations.

• HTTP Server (external):
  The returned http.Handler is intended to be passed to an HTTP server (e.g., http.ListenAndServe) that listens for and dispatches incoming HTTP requests.

This file acts as the glue that binds the HTTP server, routing infrastructure, telemetry, and controller logic into a cohesive, operational REST API server.

Visual Diagram: Structure of handler.go

classDiagram
class Handler {
+NewHandler(config)
-setupRouter(router, subrouters)
}
class Router {
<<from mux>>
}
class SessionsAPIRouter {
<<from routers>>
}
class RuntimeAPIRouter {
<<from routers>>
}
class AppsAPIRouter {
<<from routers>>
}
class DebugAPIRouter {
<<from routers>>
}
class ArtifactsAPIRouter {
<<from routers>>
}
class EvalAPIRouter {
<<from routers>>
}
Handler --> Router : creates
Handler ..> SessionsAPIRouter : uses
Handler ..> RuntimeAPIRouter : uses
Handler ..> AppsAPIRouter : uses
Handler ..> DebugAPIRouter : uses
Handler ..> ArtifactsAPIRouter : uses
Handler ..> EvalAPIRouter : uses

References

• REST API and Web Launchers — For detailed information on REST API controllers, routing, and launcher components.

• Telemetry and Observability — For OpenTelemetry integration details and tracing infrastructure.

• Session Management, Artifact Management — For the backend services injected into controllers.

• Router Setup — For understanding the modular routing approach and subrouter definitions.