Skip to main content

hackagent.router.agent

Base classes and common utilities for all agent adapters.

This module provides:

  • Common exception classes for adapter errors
  • Abstract base class Agent with shared functionality
  • Utility methods for request validation, response building, and API key resolution

AdapterConfigurationError Objects​

class AdapterConfigurationError(Exception)

Base exception for adapter configuration issues.

AdapterInteractionError Objects​

class AdapterInteractionError(Exception)

Base exception for errors during interaction with an agent API.

AdapterResponseParsingError Objects​

class AdapterResponseParsingError(Exception)

Base exception for errors parsing an agent's response.

Agent Objects​

class Agent(ABC)

Abstract Base Class for all agent implementations.

It defines a common interface for the router to interact with various agents, and provides shared functionality for logging, request validation, response building, and configuration handling.

Attributes:

  • id str - Unique identifier for this agent instance.

  • config Dict[str, Any] - Configuration dictionary for this agent.

  • logger logging.Logger - Hierarchical logger instance.

  • model_name str - Name of the model (if applicable).

  • adapter_type str - Type identifier for the adapter (e.g., "OpenAIAgent").

    Default Generation Parameters (optional, set by subclasses):

  • default_max_tokens int - Default maximum tokens to generate.

  • default_temperature float - Default sampling temperature.

  • default_top_p float - Default top-p sampling parameter.

__init__​

@abstractmethod
def __init__(id: str, config: Dict[str, Any])

Initializes the agent with common setup.

Arguments:

  • id - A unique identifier for this specific agent instance or type.
  • config - Configuration specific to this agent (e.g., API keys, model names).

adapter_type​

@property
def adapter_type() -> str

Returns the adapter type name.

handle_request​

@abstractmethod
def handle_request(request_data: Dict[str, Any]) -> Dict[str, Any]

Processes an incoming request and returns a standardized response.

The response should be suitable for storage via the API and should ideally include enough information to reconstruct the interaction.

Arguments:

  • request_data - The data for the agent to process. This might include the prompt, session information, user details, etc. Common keys:
    • 'prompt': Simple text prompt
    • 'messages': List of message dicts with 'role' and 'content'
    • 'max_tokens': Override default max tokens
    • 'temperature': Override default temperature
    • 'top_p': Override default top_p

Returns:

A dictionary containing the standardized response with keys:

  • 'raw_request': The original request sent to the underlying agent.
  • 'raw_response_body': The raw response received from the underlying agent.
  • 'raw_response_headers': HTTP headers from the response if applicable.
  • 'processed_response': The key information extracted/processed.
  • 'generated_text': Alias for processed_response (for compatibility).
  • 'status_code': HTTP-like status code of the interaction.
  • 'error_message': Any error message encountered (None on success).
  • 'agent_specific_data': Adapter-specific metadata.
  • 'agent_id': The identifier of this agent.
  • 'adapter_type': The type of this adapter.

get_identifier​

def get_identifier() -> str

Returns the unique identifier for this agent instance or type.

ChatCompletionsAgent Objects​

class ChatCompletionsAgent(Agent)

Abstract base class for chat completion-based agents.

This class provides a common implementation for agents that follow the chat completions pattern (OpenAI, LiteLLM, Ollama, etc.). It handles:

  • Request validation (prompt or messages)
  • Prompt to messages conversion
  • Parameter extraction with defaults
  • Common handle_request flow with template method pattern

Subclasses must implement:

  • _execute_completion(): The actual API call to generate completions

Subclasses may override:

  • _get_completion_parameters(): To add adapter-specific parameters
  • _extract_response_content(): To handle adapter-specific response formats
  • _get_excluded_request_keys(): To exclude additional keys from kwargs

__init__​

def __init__(id: str, config: Dict[str, Any])

Initializes the ChatCompletionsAgent.

Arguments:

  • id - A unique identifier for this agent instance.
  • config - Configuration dictionary for this agent.

handle_request​

def handle_request(request_data: Dict[str, Any]) -> Dict[str, Any]

Handles an incoming request using the chat completions pattern.

This method implements the common flow for chat completion agents:

  1. Validate request (requires 'prompt' or 'messages')
  2. Convert prompt to messages if needed
  3. Extract completion parameters
  4. Execute the completion via _execute_completion()
  5. Build and return standardized response

Arguments:

  • request_data - A dictionary containing the request data. Expected keys:
    • 'prompt': Text prompt (converted to messages)
    • 'messages': Pre-formatted messages list (takes precedence)
    • 'max_tokens': Override default max tokens
    • 'temperature': Override default temperature
    • 'top_p': Override default top_p
    • Additional adapter-specific parameters

Returns:

A dictionary representing the agent's response or an error.