runtime.go

Overview

This file defines the data structure and validation logic for agent execution requests in the system. Specifically, it models a request to run an AI agent within a session context, encapsulating details such as the application name, user and session identifiers, the new input message from the user, streaming preferences, and optional state changes. The primary purpose of this file is to ensure that any request to run an agent contains all the required information before processing.

Data Structures

RunAgentRequest

RunAgentRequest is a struct representing the payload for invoking an agent run operation. It contains the following fields:

The NewMessage field uses the genai.Content type from the google.golang.org/genai package, which encapsulates content suitable for large language models.

Functions and Methods

AssertRunAgentRequestRequired()

func (req RunAgentRequest) AssertRunAgentRequestRequired() error

This method validates that all required fields within a RunAgentRequest instance are populated with non-zero values.

• Parameters:
  None (operates on the method receiver req).

• Returns:

  • nil if all required fields are present and non-zero.

  • An error describing the first missing required field found.

• Description:
  It checks the following fields for zero values: AppName, UserId, SessionId, and NewMessage. If any of these fields are zero-valued (empty string, nil, or equivalent), the function returns an error indicating which field is missing.

• Usage Example:

req := RunAgentRequest{
    AppName:   "myApp",
    UserId:    "user123",
    SessionId: "sess789",
    NewMessage: genai.Content{
        // assume content initialization
    },
}

if err := req.AssertRunAgentRequestRequired(); err != nil {
    // handle missing required field error
    log.Fatalf("Invalid request: %v", err)
}

This validation is typically called early in the agent invocation pipeline to ensure input integrity before further processing.

Implementation Details

• The AssertRunAgentRequestRequired method relies on a helper function IsZeroValue (presumably defined elsewhere in the codebase) to determine if a field is considered zero-valued. This approach provides a generic zero-value check that can handle various types including strings and complex structs.

• By requiring AppName, UserId, SessionId, and NewMessage, the system enforces that every agent run request is contextually complete, linking the request to an application, user, session, and input message.

Interaction with Other System Components

• The RunAgentRequest struct is likely consumed by components responsible for managing agent execution, such as the Agent Execution Runner that coordinates running agents within user sessions.

• The NewMessage field of type genai.Content ties into the LLM Integration and Agents topic, as it represents the input passed to large language models.

• Validation performed by AssertRunAgentRequestRequired ensures that session management components (see Session Management) receive well-formed requests to maintain consistent session states.

• Optional StateDelta allows the request to convey incremental state changes, which may be applied by state management or session services.

Diagram: RunAgentRequest Structure and Validation Workflow

classDiagram
class RunAgentRequest {
+AppName: string
+UserId: string
+SessionId: string
+NewMessage: genai.Content
+Streaming: bool
+StateDelta: *map[string]any
+AssertRunAgentRequestRequired()
}
RunAgentRequest : +AppName
RunAgentRequest : +UserId
RunAgentRequest : +SessionId
RunAgentRequest : +NewMessage
RunAgentRequest : +Streaming
RunAgentRequest : +StateDelta
RunAgentRequest : +AssertRunAgentRequestRequired()
RunAgentRequest --> IsZeroValue : uses

This diagram depicts the RunAgentRequest class with its properties and the validation method. It also illustrates its dependency on the IsZeroValue utility function for field validation.

For detailed information about agent invocation contexts, session handling, and LLM integration relevant to this request struct, see the following topics:

• LLM Integration and Agents

• Agent Invocation Context

• Session Management

• Agent Execution Runner