Skip to main content

Proxy Agent

Most of our agents allow you to specify a set of parameters like temperature, model, max_tokens, vendor, etc. However, there are some cases where you might need to define those parameters dynamically.

For example, you might want to use a different temperature or model based on some external factors. This is where the Proxy Agent comes in.

The Proxy Agent allows you to define a set of parameters dynamically for each request using the request body.

Use cases​

  • Chat application where you want to allow users to choose their preferred model.
  • A/B testing different parameters to see which one works best.

Should I use this agent?​

✅ You need to switch between different parameters for each request.

⛔ You prefer to define the parameters in the agent configuration and make sure they are consistent across all requests.

Creating a Proxy Agent​

To create a Proxy Agent, follow this guide.

Request Body​

The Proxy Agent expects the following parameters in the request body:

{
    "model": "<MODEL_ID>", // Required (gpt-4o-mini, mistral-small, etc.)
    "vendor": "<VENDOR_NAME>", // Required - (OpenAI, Mistral, Anthropic, etc.)
    "messages": [
        {
            "role": "system",
            "content": "<SYSTEM_DEFINITION_GOES_HERE>",
        },
        {
            "role": "user",
            "content": "<USER_INPUT_GOES_HERE>",
            "volatileKnowledgeIds": [] // Optional - List of IDs for volatile knowledge
        }
    ], // Required
    "frequency_penalty": 0.0, // Optional. Between -2.0 and 2.0. 
    "max_tokens": 4096, // Optional.
    "presence_penalty": 0.0, // Optional. Between -2.0 and 2.0. 
    "top_p": 1.0, // Optional. Between 0.0 and 1.0.
    "temperature": 0.5, // Optional. Between 0.0 and 1.0.
    "stream": true, // Optional
    "top_k": 10, // Optional. Between 0 and 100. Default value depends on the model.
    "userIdentifier": "<USER_IDENTIFIER>", // Optional. Only available in certain agents.
    "groupIdentifier": "<GROUP_IDENTIFIER>", // Optional. Only available in certain agents.
    "useVision": false, // Optional. Enable vision capabilities for processing images with models that support it.
    "skills": { // Optional skills to enable 
        "web_search": false, // Optional. Enable web search skill
        "web_search_options": { // Optional
            "model": "<MODEL_FOR_WEB_SEARCH>", // Optional
            "vendor": "<MODEL_VENDOR>" // Optional (E.g.: OpenAI)
        },
        "image_generation": false, // Optional. Enable image generation skill
        "image_generation_options": { // Optional
            "model": "<MODEL_FOR_IMAGE_GENERATION>", // Optional
            "vendor": "<MODEL_VENDOR>" // Optional (E.g.: OpenAI)
        },
        "speech_generation": false, // Optional. Enable speech generation skill
        "speech_generation_options": { // Optional
            "model": "<MODEL_FOR_SPEECH_GENERATION>", // Optional
            "vendor": "<MODEL_VENDOR>", // Optional (E.g.: OpenAI)
            "voice": "<VOICE_NAME>", // Optional
            "speed": 1.0 // Optional. Speech speed multiplier
        }
    }
}

Usage Examples​

cURL​

curl -X POST https://api.serenitystar.ai/api/agent/{AGENT_ENDPOINT}/execute \
  -H "Content-Type: application/json" \
  -H "X-API-KEY: {API_KEY}" \
  -d '{
    "model": "mistral-medium-latest",
    "vendor": "Mistral",
    "messages": [
      {
        "role": "system",
        "content": "You are a chatbot specializing in cooking recipes."
      },
      {
        "role": "user",
        "content": "Can you give me a recipe for a chocolate cake?"
      }
    ],
    "temperature": 0.5,
    "max_tokens": 4096,
    "stream": true,
    "userIdentifier": "xxxxxxxx-xxxxxx-xxxxxx-xxxxxxxx",
    "groupIdentifier": "xxxxxxxx-xxxxxx-xxxxxx-xxxxxxxx"
  }'

C#​

using System;
using System.Net.Http;
using System.Text;
using System.Threading.Tasks;

class Program
{
    static async Task Main()
    {
        var client = new HttpClient();
        var request = new HttpRequestMessage
        {
            Method = HttpMethod.Post,
            RequestUri = new Uri("https://api.serenitystar.ai/api/agent/{AGENT_ENDPOINT}/execute"),
            Headers =
            {
                { "X-API-KEY", "{API_KEY}" },
                { "Content-Type", "application/json" },
            },
            Content = new StringContent(@"{
                ""model"": ""mistral-medium-latest"",
                ""vendor"": ""Mistral"",
                ""messages"": [
                    {
                        ""role"": ""system"",
                        ""content"": ""You are a chatbot specializing in cooking recipes.""
                    },
                    {
                        ""role"": ""user"",
                        ""content"": ""Can you give me a recipe for a chocolate cake?""
                    }
                ],
                ""temperature"": 0.5,
                ""max_tokens"": 4096,
                ""stream"": true,
                ""userIdentifier"": ""xxxxxxxx-xxxxxx-xxxxxx-xxxxxxxx"",
                ""groupIdentifier"": ""xxxxxxxx-xxxxxx-xxxxxx-xxxxxxxx""
            }", Encoding.UTF8, "application/json"),
        };

        var response = await client.SendAsync(request);
        var responseContent = await response.Content.ReadAsStringAsync();
        Console.WriteLine(responseContent);
    }
}

Python​

import requests
import json

url = 'https://api.serenitystar.ai/api/agent/{AGENT_ENDPOINT}/execute'

headers = {
    'Content-Type': 'application/json',
    'X-API-KEY': '{API_KEY}'
}

payload = json.dumps({
    "model": "mistral-medium-latest",
    "vendor": "Mistral",
    "messages": [
        {
            "role": "system",
            "content": "You are a chatbot specializing in cooking recipes."
        },
        {
            "role": "user",
            "content": "Can you give me a recipe for a chocolate cake?"
        }
    ],
    "temperature": 0.5,
    "max_tokens": 4096,
    "stream": True,
    "userIdentifier": "xxxxxxxx-xxxxxx-xxxxxx-xxxxxxxx",
    "groupIdentifier": "xxxxxxxx-xxxxxx-xxxxxx-xxxxxxxx"
})

response = requests.request("POST", url, headers=headers, data=payload)

print(response.text)

Skills​

The Proxy Agent supports various skills that can enhance its capabilities. These skills can be enabled or disabled for each request.

Enables the agent to search the web for information to answer queries.

{
  "skills": {
    "web_search": true,
    "web_search_options": {
      "model": "gpt-4-search",
      "vendor": "OpenAI"
    }
  }
}

Parameters​

  • web_search (boolean): Enable or disable web search capability.
  • web_search_options (object, optional): Configuration options for web search. If not provided, default values will be used.
    • model (string, optional): The model to use for processing web search results. Default: "gpt-4o-search-preview"
    • vendor (string, optional): The vendor of the model. Default: "OpenAI"

Image Generation​

Enables the agent to generate images based on text prompts.

{
  "skills": {
    "image_generation": true,
    "image_generation_options": {
      "model": "dall-e-3",
      "vendor": "OpenAI"
    }
  }
}

Parameters​

  • image_generation (boolean): Enable or disable image generation capability.
  • image_generation_options (object, optional): Configuration options for image generation. If not provided, default values will be used.
    • model (string, optional): The model to use for generating images. Default: "dall-e-2"
    • vendor (string, optional): The vendor of the model. Default: "OpenAI"

Speech Generation​

Enables the agent to convert text responses into speech audio.

{
  "skills": {
    "speech_generation": true,
    "speech_generation_options": {
      "model": "tts-1",
      "vendor": "OpenAI",
      "voice": "alloy",
      "speed": 1.0
    }
  }
}

Parameters​

  • speech_generation (boolean): Enable or disable speech generation capability.
  • speech_generation_options (object, optional): Configuration options for speech generation. If not provided, default values will be used.
    • model (string, optional): The model to use for speech generation. Default: "tts-1"
    • vendor (string, optional): The vendor of the model. Default: "OpenAI"
    • voice (string, optional): The voice to use for the generated speech. Default: "alloy"
    • speed (float, optional): Speed multiplier for the generated speech. Default: 1.0

Example with Multiple Skills​

You can enable multiple skills in a single request:

{
  "model": "claude-3-7-sonnet-latest",
  "vendor": "Anthropic",
  "messages": [
    {
      "role": "user",
      "content": "Create an image of a mountain landscape and describe it. Also provide information about famous mountain ranges."
    }
  ],
  "temperature": 0.7,
  "stream": true,
  "skills": {
    "web_search": true,
    "speech_generation": true,
    "image_generation": true,
    "image_generation_options": {
      "model": "dall-e-3",
      "vendor": "OpenAI"
    }
  }
}