runtime.go

Overview

The runtime.go file defines the RuntimeAPIRouter, a component responsible for routing HTTP requests related to the Runtime API endpoints. This router maps incoming HTTP requests for running AI agents to their respective handler functions implemented in the RuntimeAPIController. It provides two primary endpoints:

• /run: Handles synchronous or standard agent execution requests.

• /run_sse: Handles agent execution using Server-Sent Events (SSE) for streaming responses.

The router encapsulates the runtime controller and exposes the routes with HTTP methods and URL patterns. It integrates into the overall REST API routing infrastructure, ensuring that runtime-related API calls are correctly dispatched to controller logic.

This file is part of the broader Router Setup and REST API and Web Launchers modules, which organize API endpoints and HTTP routing.

Detailed Components

Type: RuntimeAPIRouter

type RuntimeAPIRouter struct {
	runtimeController *controllers.RuntimeAPIController
}

• Purpose:
  Holds a reference to the RuntimeAPIController to which it delegates handling of runtime API requests.

• Fields:

  • runtimeController: Pointer to a RuntimeAPIController instance responsible for the business logic of runtime agent execution.

Function: NewRuntimeAPIRouter

func NewRuntimeAPIRouter(controller *controllers.RuntimeAPIController) *RuntimeAPIRouter

• Description:
  Constructs a new RuntimeAPIRouter instance by associating it with a provided RuntimeAPIController.

• Parameters:

  • controller (*controllers.RuntimeAPIController): The controller instance to handle runtime API logic.

• Returns:

  • Pointer to a newly created RuntimeAPIRouter.

• Usage Example:

  controller := controllers.NewRuntimeAPIController(...)
  router := NewRuntimeAPIRouter(controller)
  

Method: Routes

func (r *RuntimeAPIRouter) Routes() Routes

• Description:
  Returns a slice of Route definitions that specify the HTTP routes for the runtime API.

• Returns:

  • Routes: A collection (slice) of Route structs, each defining:

    • Name: Route identifier string.

    • Methods: Supported HTTP methods (e.g., POST, OPTIONS).

    • Pattern: URL path pattern.

    • HandlerFunc: The HTTP handler function wrapped by error handling middleware.

• Defined Routes:

  • RunAgent

    • Path: /run

    • Methods: POST, OPTIONS

    • Handler: RuntimeAPIController.RunHandler wrapped with NewErrorHandler

  • RunAgentSse

    • Path: /run_sse

    • Methods: POST, OPTIONS

    • Handler: RuntimeAPIController.RunSSEHandler wrapped with NewErrorHandler

• Usage Example:

  router := NewRuntimeAPIRouter(controller)
  for _, route := range router.Routes() {
      muxRouter.HandleFunc(route.Pattern, route.HandlerFunc).Methods(route.Methods...)
  }
  

Implementation Details

• The router delegates HTTP request handling to RuntimeAPIController methods:

  • RunHandler handles standard agent execution requests.

  • RunSSEHandler supports server-sent events for streaming session events incrementally during agent execution.

• Both routes support the OPTIONS method to facilitate CORS preflight requests commonly used in web APIs.

• The handlers are wrapped using controllers.NewErrorHandler to provide a consistent error handling mechanism, converting errors into HTTP error responses.

• The router pattern /run and /run_sse are relative to the base API path (commonly /api/runtime or similar), as managed by the top-level router setup.

Interaction with Other Components

• RuntimeAPIController (REST API Controllers):
  The controller implements the core logic invoked when the router's routes are matched. It manages parsing requests, running agents via the agent execution framework, and encoding responses.

• Route and Routes types (Router Setup):
  The router uses these types to declare and organize HTTP routes.

• Main HTTP Server (REST API and Web Launchers):
  The RuntimeAPIRouter is integrated into the global HTTP routing infrastructure via the top-level router, which aggregates routes from different API domains.

• Error Handling Middleware:
  Wrapping handlers ensures errors are caught and converted to appropriate HTTP responses.

• HTTP Methods and Patterns:
  Defined to comply with REST principles and support frontend clients, including browser-based Web UI and programmatic API clients.

Visual Diagram: RuntimeAPIRouter Structure

classDiagram
class RuntimeAPIRouter {
-runtimeController: RuntimeAPIController
+Routes() Routes
}
class RuntimeAPIController {
+RunHandler()
+RunSSEHandler()
}
RuntimeAPIRouter "1" *-- "1" RuntimeAPIController

• The RuntimeAPIRouter holds a single instance of RuntimeAPIController.

• It exposes the Routes method that returns route definitions mapping HTTP paths to controller methods.

Summary of Routing Logic in runtime.go

• The RuntimeAPIRouter is a lightweight struct that binds runtime API HTTP routes to their handlers.

• It supports two POST endpoints (/run and /run_sse) with error handling.

• This design provides clean separation of routing concerns from request handling.

• It enables the REST API server to modularly add runtime-related routes alongside other API domains such as sessions and artifacts.

Relevant Links and References

• See Router Setup for overall router architecture and route aggregation.

• See REST API and Web Launchers for how REST API controllers and routers integrate into the web server.

• See RuntimeAPIController for details on handler implementations and runtime agent execution logic.

• Related middleware and error handling are part of the REST API Controllers infrastructure.

• The routes defined here are part of the /api REST endpoint namespace managed by the top-level HTTP server component.

This file plays a critical role in exposing the Runtime API endpoints for invoking AI agent execution, enabling external clients to interact with the system programmatically through HTTP.