RESTful Connector

ARES supports integration with REST API deployments via the RESTfulConnector class. This connector facilitates communication with external services by handling HTTP requests and responses.

Overview

The RESTfulConnector inherits from the base Connector class and is designed to be flexible and extensible. You can subclass it to customize API interactions by overriding methods such as:

  • generate and batch_generate — main entry points for sending prompts and receiving responses.

  • _extract_message — to customize how responses are parsed.

  • _obtain_header_key — to customize how authorization tokens are retrieved.

Examples of subclasses include:

  • WatsonxRestConnector

  • WatsonxAgentConnector

Basic Configuration

ARES provides a default REST API configuration via the RESTParams dataclass. It will automatically check for the REST_API_KEY environment variable in your .env file.

Minimal example:

type: ares.connectors.restful_connector.RESTfulConnector
name: "my_local_rest_connector"
api_config:
  api_endpoint: <your deployment endpoint>

Advanced Configuration

You can customize headers, request templates, and additional parameters required by your REST API provider.

type: ares.connectors.restful_connector.RESTfulConnector
name: "my_local_rest_connector"
api_config:
  api_endpoint: <your deployment endpoint>
  api_key_env_var: MY_API_KEY  # defaults to REST_API_KEY
  timeout: 100
  header:
    Content-Type: "application/json"
    Authorization: "Bearer $HEADER_TAG"  # $HEADER_TAG is replaced with the API key from .env
  request_template:
    messages: "$MESSAGES"  # $MESSAGES is replaced with the input prompt(s)
  other:
    iam_url: <IAM identity token endpoint>
    grant_type: <grant type for IAM token request>
    token_response_timeout: 40

Note

To align the connector with a custom response format, override the _extract_message method in a subclass.

If your API requires IAM-based Bearer tokens, override the _obtain_header_key method.

WatsonX Agent Connector

The WatsonxAgentConnector is a subclass of RESTfulConnector that supports querying agent deployments on the WatsonX platform.

Example config: example_configs/custom/wx-agent-ares-native.yaml It supports both: