Skip to main content

hackagent.router.agent

Agent base class + adapter exception types.

After issue 379 this module is the only piece of the old adapters/ folder still in use. Agent is the abstract base that :class:hackagent.router.providers.adk.ADKAgent inherits from to plug non-chat-completion protocols into the router. Chat-completion AgentTypes don't go through Agent at all — they're driven directly from :class:hackagent.router.router.AgentRouter via _ChatRegistration.

The AdapterConfigurationError / AdapterInteractionError / AdapterResponseParsingError names are kept (rather than renamed to AgentConfigurationError etc.) so existing except clauses in attack code keep working.

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.