Chat Completion Agent

It's a type of agent that allows you to generate responses to a given prompt, while keeping absolute control over the conversation back and forth between the user and the agent.

This means that you can append the entire conversation along with the prompt to the agent, and it will generate a response based on the context of the conversation.

Use cases

• Customer Support: A customer asks a series of questions about a product. The Chat Completion Agent can generate accurate and context-aware responses, keeping track of the entire conversation to provide relevant and helpful information to the customer.
• Interactive Storytelling: A user engages in a creative writing exercise, building a story collaboratively with the agent. The Chat Completion Agent keeps track of the plot, characters, and prior dialogue, generating coherent and engaging story segments based on the user's input.
• Personal Assistant: A user interacts with a virtual personal assistant for scheduling, reminders, and information retrieval. The Chat Completion Agent maintains context throughout the conversation, ensuring it responds appropriately to follow-up questions and commands.

Should I use this agent?

✅ You need to generate responses based on the context of the conversation, and you want to keep control over what to include in the conversation.

⛔ You just need to execute a single task based on the user's input. In those cases, you may want to use an Activity Agent.

Creating a Chat Completion Agent

To create a Chat Completion Agent, follow this guide.

Streaming

Streaming delivers the agent's response incrementally, as it's generated, via Server-Sent Events (SSE) instead of waiting for the full result to be ready.

Enable streaming for long-running executions

If your agent can take a while to respond (for example, when it runs skills or searches large knowledge bases), enable streaming so you receive the response incrementally and avoid request timeouts. To do so, add a stream parameter set to true to the key-value pairs in the request body, as shown in the examples below.

See Streaming for the full event format.

Usage examples

Let's say you have a Chat Completion Agent that provides recipes based on user queries. You can use the following code snippets to execute the agent:

Note: We currently use message as the key for the prompt and messages as the key for the conversation history. This may change in the future.

cURL

curl --location 'https://api.serenitystar.ai/api/agent/chef/execute' \
--header 'Content-Type: application/json' \
--header 'X-API-KEY: <YOUR_API_KEY>' \
--data '[
    {
        "Key": "messages",
        "Value": "[{\"role\": \"user\",\"content\": \"Give me the recipe for guacamole without tomato\"},{\"role\": \"assistant\",\"content\": \"Mash 4 ripe avocados with 1/2 onion, 1 serrano chili, and 1 garlic clove. Add juice of 1 lime, salt.\"}]"
    },
    {
        "Key": "message",
        "Value": "Add something spicy!"
    },
    {
        "Key": "stream",
        "Value": true
    }
]'

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/chef/execute"),
            Headers =
            {
                { "X-API-KEY", "<YOUR_API_KEY>" },
                { "Content-Type", "application/json" },
            },
            Content = new StringContent(@"[
                {
                    ""Key"": ""messages"",
                    ""Value"": ""[{\""role\"": \""user\"",\""content\"": \""Give me the recipe for guacamole without tomato\"\"},{\""role\"": \""assistant\"",\""content\"": \""Mash 4 ripe avocados with 1/2 onion, 1 serrano chili, and 1 garlic clove. Add juice of 1 lime, salt.\"""}]""
                },
                {
                    ""Key"": ""message"",
                    ""Value"": ""Add something spicy!""
                },
                {
                    ""Key"": ""stream"",
                    ""Value"": true
                }
            ]", 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/chef/execute'

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

payload = json.dumps([
    {
        "Key": "messages",
        "Value": "[{\"role\": \"user\",\"content\": \"Give me the recipe for guacamole without tomato\"},{\"role\": \"assistant\",\"content\": \"Mash 4 ripe avocados with 1/2 onion, 1 serrano chili, and 1 garlic clove. Add juice of 1 lime, salt.\"}]"
    },
    {
        "Key": "message",
        "Value": "Add something spicy!"
    },
    {
        "Key": "stream",
        "Value": True
    }
])

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

print(response.text)