apps.go

Overview

The apps.go source file defines the AppsAPIController, a REST API controller responsible for managing the Apps API within the system. Its primary function is to expose an HTTP endpoint that allows clients to list all currently loaded agents (referred to as "apps" in this context). This controller interacts with the agent.Loader interface to retrieve agent information and returns the list in JSON format to HTTP clients.

This file forms a part of the broader REST API and Web Launchers module, specifically under the subset of REST API Controllers. It provides a simple yet essential API surface to discover the available AI agents loaded in the system, facilitating dynamic agent selection and integration by external clients or frontends.

Detailed Explanation

Type: AppsAPIController

type AppsAPIController struct {
	agentLoader agent.Loader
}

• Purpose:
  Encapsulates the logic for handling API requests related to applications (agents). It holds a reference to an agent.Loader which is responsible for loading and listing agents.

• Fields:

  • agentLoader agent.Loader: An interface abstraction for loading agents. It provides methods to list and retrieve agents available in the system.

• Usage:
  An instance of AppsAPIController is created with an agent.Loader implementation to enable the controller to fetch agent data for API responses.

Function: NewAppsAPIController

func NewAppsAPIController(agentLoader agent.Loader) *AppsAPIController {
	return &AppsAPIController{agentLoader: agentLoader}
}

• Purpose:
  Constructs and returns a new AppsAPIController with the provided agent.Loader.

• Parameters:

  • agentLoader agent.Loader: The agent loader instance used by the controller to interact with loaded agents.

• Returns:

  • A pointer to a newly initialized AppsAPIController.

• Usage Example:

  loader := agent.NewLoader() // hypothetical loader creation
  controller := NewAppsAPIController(loader)
  

Method: ListAppsHandler

func (c *AppsAPIController) ListAppsHandler(rw http.ResponseWriter, req *http.Request) {
	apps := c.agentLoader.ListAgents()
	EncodeJSONResponse(apps, http.StatusOK, rw)
}

• Purpose:
  HTTP handler method that responds to client requests by listing all loaded agents.

• Parameters:

  • rw http.ResponseWriter: Used to write the HTTP response.

  • req *http.Request: The incoming HTTP request object.

• Behavior:

  1. Calls ListAgents() on the embedded agentLoader to retrieve a list of all agent instances currently loaded.

  2. Encodes the list of agents into JSON format.

  3. Writes the JSON response with HTTP status code 200 OK back to the client.

• Return Value:

  • None (writes directly to the HTTP response).

• Usage Context:
  This handler is intended to be registered with an HTTP router to serve the "list apps" endpoint, enabling clients to query which agents are available for invocation.

• Example HTTP Interaction:

  • Request: GET /api/apps

  • Response: JSON array of agent metadata, e.g.,

    [
      {"name": "agent1", "description": "Agent 1 description"},
      {"name": "agent2", "description": "Agent 2 description"}
    ]
    

Important Implementation Details

• The controller depends directly on the agent.Loader interface from the google.golang.org/adk/agent package, which abstracts the loading and listing of agents. This decouples the controller from the concrete agent implementations and facilitates extensibility.

• The response encoding utilizes a helper function EncodeJSONResponse (assumed to be defined elsewhere in the system) to serialize data into JSON and set the appropriate HTTP headers.

• The controller does not handle any input parameters or authentication; it simply returns all loaded agents as-is. Authentication and authorization, if any, should be managed by middleware or higher-level routing layers.

• The simplicity of this controller aligns with the broader design of REST API Controllers, focusing on RESTful operations that translate HTTP requests into agent framework service calls and return JSON responses.

Interaction with Other Components

• Agent Loader (agent.Loader):
  The core dependency that provides the list of available agents. The loader interfaces with the agent framework defined in LLM Integration and Agents and AI Agent Framework, managing the lifecycle and availability of agents.

• REST API Routing:
  This controller’s handler is typically registered with the HTTP router, part of the Router Setup subtopic, which maps HTTP paths (e.g., /api/apps) to this handler.

• Frontend/UI Components:
  The list of apps served by this controller can be consumed by the embedded Angular-based Web UI Launcher or other clients to display agent options to users.

• Sessions and Runtime Controllers:
  While this controller lists agents, other controllers like the RuntimeAPIController handle agent execution. Together, they provide a complete REST API surface for discovery and invocation.

Visual Diagram

classDiagram
class AppsAPIController {
-agentLoader: agent.Loader
+ListAppsHandler(http.ResponseWriter, *http.Request)
}
AppsAPIController --> agent.Loader

• Diagram Explanation:
  The AppsAPIController class contains a private field agentLoader of type agent.Loader. It exposes the method ListAppsHandler which serves HTTP requests. The controller relies on the agent.Loader interface to retrieve loaded agents.

References to Related Topics

• The AppsAPIController is part of the REST API Controllers group, which collectively provide HTTP handlers for runtime, sessions, apps, artifacts, and debugging APIs.

• It depends on the agent loading framework described under LLM Integration and Agents and the core AI Agent Framework.

• The API endpoints implemented by this controller are integrated into the HTTP routing infrastructure detailed in Router Setup.

• Clients interacting with this controller typically include the embedded web UI launched by the Web UI Launcher.

This file provides a lightweight and focused API endpoint to expose the available agents, facilitating dynamic discovery and integration of AI capabilities through HTTP-based APIs.