debug.go

Overview

The debug.go file implements the DebugAPIController, a REST API controller responsible for exposing debugging and diagnostic information related to AI agent sessions and their events. It provides HTTP handlers to retrieve detailed trace data and graphical representations of session event workflows, aiding in analysis, troubleshooting, and observability of agent invocations and interactions.

This controller acts as a bridge between the session service, agent loader, and span exporting services to gather, process, and present debug information in JSON format for client consumption. It is part of the broader REST API Controllers that expose various agent runtime and management functionalities over HTTP.

Entities

DebugAPIController

The core struct of this file, encapsulating dependencies necessary for debug operations:

type DebugAPIController struct {
	sessionService session.Service
	agentloader    agent.Loader
	spansExporter  *services.APIServerSpanExporter
}

• sessionService: Interface to retrieve session and event data.

• agentloader: Loads configured agents by application name.

• spansExporter: Provides access to collected trace data representing spans of execution.

Constructor

NewDebugAPIController

func NewDebugAPIController(sessionService session.Service, agentLoader agent.Loader, spansExporter *services.APIServerSpanExporter) *DebugAPIController

• Parameters:

  • sessionService: Provides session retrieval and event information.

  • agentLoader: Loads agents for given applications.

  • spansExporter: Supplies span trace data for debugging.

• Returns: Pointer to a new DebugAPIController instance with injected dependencies.

• Usage:
  Used to instantiate the controller during REST API router setup, ensuring it has access to required service layers for debug operations.

HTTP Handlers

TraceDictHandler

func (c *DebugAPIController) TraceDictHandler(rw http.ResponseWriter, req *http.Request)

• Purpose:
  Returns detailed debug trace information for a specific event in a session as a dictionary (JSON object).

• Behavior:

  1. Extracts event_id from the HTTP path parameters.

  2. Validates presence of event_id, returning HTTP 400 if missing.

  3. Calls spansExporter.GetTraceDict() to retrieve a map of event IDs to their trace dictionaries.

  4. Looks up the trace dictionary for the requested event.

  5. Returns HTTP 404 if event not found.

  6. Encodes and writes the trace dictionary as a JSON response with HTTP 200 status.

• Parameters:

  • rw: HTTP response writer.

  • req: HTTP request.

• Example Usage:
  HTTP GET /api/debug/trace/{event_id} → Returns JSON trace dictionary for the given event.

EventGraphHandler

func (c *DebugAPIController) EventGraphHandler(rw http.ResponseWriter, req *http.Request)

• Purpose:
  Returns a graph representation of the relationships and functional calls/responses within a specific session event. The graph is returned in DOT language format for visualization.

• Behavior:

  1. Extracts session identifiers (appName, userID, sessionID) from HTTP parameters using models.SessionIDFromHTTPParameters.

  2. Retrieves the session data via sessionService.Get.

  3. Extracts event_id parameter and validates presence.

  4. Searches the session's events to locate the event matching event_id.

  5. If event not found, returns HTTP 404.

  6. Identifies functional calls and responses within the event by invoking helper functions functionalCalls and functionalResponses.

  7. Constructs a list of highlighted node pairs based on function names and event author.

     • If functional calls exist, pairs each call's name with the event author.

     • Otherwise, uses functional responses.

     • Defaults to pairing the event author with itself if no function calls/responses exist.

  8. Loads the appropriate agent for the app using agentloader.LoadAgent.

  9. Calls services.GetAgentGraph with the agent and highlighted pairs to generate the DOT graph.

  10. Returns the graph source as a JSON response.

• Parameters:

  • rw: HTTP response writer.

  • req: HTTP request.

• Example Usage:
  HTTP GET /api/debug/graph/{appName}/{userID}/{sessionID}/{event_id} → Returns JSON with DOT graph source string.

Helper Functions

functionalCalls

func functionalCalls(event *session.Event) []*genai.FunctionCall

• Purpose:
  Extracts a slice of all function calls embedded within the parts of the LLM response content associated with an event.

• Parameters:

  • event: Pointer to a session.Event.

• Returns:
  Slice of pointers to genai.FunctionCall objects. Returns nil if no function calls exist.

• Implementation Details:
  Iterates over event.LLMResponse.Content.Parts. For each part, if a FunctionCall exists, appends it to the result slice.

functionalResponses

func functionalResponses(event *session.Event) []*genai.FunctionResponse

• Purpose:
  Extracts a slice of all function responses embedded within the parts of the LLM response content associated with an event.

• Parameters:

  • event: Pointer to a session.Event.

• Returns:
  Slice of pointers to genai.FunctionResponse objects. Returns nil if no function responses exist.

• Implementation Details:
  Iterates over event.LLMResponse.Content.Parts. For each part, if a FunctionResponse exists, appends it to the result slice.

Implementation Details and Algorithms

• TraceDictHandler relies on an internal span exporting mechanism (APIServerSpanExporter) to obtain comprehensive trace data collected during agent and session event execution. This allows associating trace spans with specific events for detailed debugging.

• EventGraphHandler builds a graph representation of event interactions based on function calls and responses extracted from the event's LLM response content. The highlighted pairs are dynamically constructed to emphasize relationships between function call names and event authors.

• The graph is generated in the DOT graph description language, which can be rendered by external tools (e.g., Graphviz) for visualization.

• The agentloader dynamically loads the AI agent configured for the given application name, ensuring that graph generation aligns with the agent's capabilities and structure.

Interaction with Other Components

• Session Service (session.Service): Provides retrieval of session data and associated events. Essential for locating the targeted event for graph and trace data extraction.

• Agent Loader (agent.Loader): Loads the AI agent instance for the specified application, necessary for agent-specific graph generation and interpretation.

• Span Exporter (services.APIServerSpanExporter): Collects and supplies trace span data related to agent executions and session events, enabling detailed trace dictionary retrieval.

• Models Package (models): Used for parsing and validating session identifiers from HTTP request parameters.

• Services Package (services): Contains utility functions like GetAgentGraph to produce graph visualizations of agent structures and interactions.

• Mux Router (github.com/gorilla/mux): Used for extracting path variables from HTTP requests.

This file is integrated into the REST API server as part of the debug endpoints, facilitating monitoring and diagnostics for ongoing agent sessions and executions. It complements the REST API Controllers by focusing on debugging and observability aspects.

Visual Diagram: DebugAPIController Structure and Workflow

flowchart TD
DebugAPIController -->|uses| sessionService[Session Service]
DebugAPIController -->|uses| agentloader[Agent Loader]
DebugAPIController -->|uses| spansExporter[Span Exporter]
TraceDictHandler --> spansExporter
TraceDictHandler --> HTTPResponse[Writes JSON Trace Dict]
EventGraphHandler --> sessionService
EventGraphHandler --> agentloader
EventGraphHandler --> services_GetAgentGraph[services.GetAgentGraph]
EventGraphHandler --> HTTPResponse[Writes JSON Graph DOT]
functionalCalls --> EventGraphHandler
functionalResponses --> EventGraphHandler

• The diagram shows the main controller with its dependencies.

• Two main HTTP handler methods (TraceDictHandler and EventGraphHandler) interact with these dependencies to fetch and prepare debug data.

• Helper functions functionalCalls and functionalResponses support EventGraphHandler by extracting needed details from events.

Usage Summary

• Register DebugAPIController with the HTTP router under debug paths (e.g., /api/debug/trace/{event_id}, /api/debug/graph/{session params}/{event_id}).

• Invoke TraceDictHandler to obtain raw trace dictionaries for events.

• Invoke EventGraphHandler to obtain a DOT graph representation illustrating functional call relationships for an event.

• These endpoints support diagnostic tools, monitoring dashboards, and developer debugging interfaces.

For detailed understanding of related REST API controller design and routing, see REST API and Web Launchers and REST API Controllers. For agent loading and session management details, refer to AI Agent Framework and Session Management. The span exporting and trace data collection is further described in Telemetry and Observability.