REST API and Web Launchers

The REST API and Web Launchers module provides the infrastructure for running and exposing AI agents via HTTP-based interfaces. It implements REST API servers, HTTP routing, and web-based launchers that allow users and clients to interact with agents over the network. This includes handling HTTP requests, routing them to appropriate controllers, serving an embedded web UI, and supporting the Agent-To-Agent (A2A) protocol for distributed multi-agent communication.

Core Concepts and Purpose

This module exists to bridge the internal AI agent framework with external clients, providing programmatic and user-friendly access through:

It solves the problem of exposing agent capabilities in an accessible manner that supports synchronous and streaming interactions, session state management, artifact handling, and remote multi-agent protocols.

Module Structure and Key Components

1. REST API Controllers

The REST API controllers implement HTTP handlers that expose agent-related functionality via JSON-based APIs. They process incoming HTTP requests, invoke the underlying agent logic, and return structured JSON responses.

Each controller interacts directly with services such as the session.Service, artifact.Service, and the agent.Loader to perform its duties.

2. Router Setup

Routing is established using the gorilla/mux package and organized into modular subrouters, each corresponding to a controller group:

The main HTTP handler (server/adkrest/handler.go) composes these subrouters into a single mux.Router instance, registering all API routes under the /api/ path prefix.

This modular routing setup enables clean separation of concerns, easy extension, and consistent REST endpoint organization.

3. Web UI Launcher

Located in cmd/launcher/web/webui/webui.go, the Web UI Launcher serves an embedded Angular-based web application from the Go binary using the Go embed package.

This allows users to interact with agents visually through a browser without needing to deploy frontend assets separately.

4. Web Server Launcher

The Web Server Launcher (cmd/launcher/web/web.go) is a flexible HTTP server framework supporting pluggable sublaunchers:

This launcher acts as a host for different web-based interfaces, including:

It ensures that these components can run together in a single HTTP server process, sharing configuration and resources.

5. API and A2A Sublaunchers

The module defines sublaunchers extending the web server with specific protocols:

These sublaunchers integrate seamlessly with the Web Server Launcher and can run concurrently to provide comprehensive agent interaction options.

Interaction and Workflow Overview

At a high level, the module operates as follows:

  1. HTTP Request Handling
    Incoming HTTP requests are routed by the main mux.Router to the appropriate controller based on the URL path and HTTP method.

  2. Controller Processing
    Controllers parse and validate request parameters and bodies. For agent runs, the RuntimeAPIController uses the agent.Loader to load the requested agent and the runner.Runner to execute the agent logic with the given session context.

  3. Agent Execution
    The runner coordinates invoking the agent, managing session state, calling tools and LLMs, and collecting resulting session events.

  4. Response Encoding
    Session events and other data are serialized into JSON and returned to the client. Streaming responses use Server-Sent Events (SSE) to provide incremental updates.

  5. Web UI Serving
    The embedded web UI is served as static files with runtime configuration, allowing browsers to interact with the REST API transparently.

  6. A2A Communication
    The A2A launcher exposes JSON-RPC endpoints enabling remote agents to invoke or communicate with this agent instance, supporting distributed architectures.

Code Illustration: Running an Agent via REST API

The core agent execution flow in the RuntimeAPIController is represented by the RunHandler method:

func (c *RuntimeAPIController) RunHandler(rw http.ResponseWriter, req *http.Request) error {
    runAgentRequest, err := decodeRequestBody(req)
    if err != nil {
        return err
    }
    sessionEvents, err := c.runAgent(req.Context(), runAgentRequest)
    if err != nil {
        return err
    }
    var events []models.Event
    for _, event := range sessionEvents {
        events = append(events, models.FromSessionEvent(*event))
    }
    EncodeJSONResponse(events, http.StatusOK, rw)
}

Here:

Visual Diagram: REST API Request Flow

flowchart TD
Client[Client HTTP Request]
Router[HTTP Router]
Controller[RuntimeAPIController]
Validate[Validate Session]
LoadAgent[Load Agent]
Runner[Runner Execute Agent]
AgentLogic[Agent & Tool Invocation]
SessionService[Session Service]
ArtifactService[Artifact Service]
Response[JSON Response / SSE Stream]
Client --> Router --> Controller
Controller --> Validate --> LoadAgent --> Runner
Runner --> AgentLogic
AgentLogic --> SessionService
AgentLogic --> ArtifactService
Runner --> Response
Controller --> Response

Relationships to Other Topics

This module is essential for exposing the capabilities of AI agents to external users and systems through standardized, scalable, and interactive HTTP interfaces.