Continual Copilot Headless API

This is a short guide to help you understand how to use the new Copilot API to submit user messages to a copilot, add context to user messages, and enable conversations.

Pre-requisites

Create an API key and copy the copilot ID to include in the API request.

Create an API key

Log into https://console.continual.ai (opens in a new tab), click on API Keys on the bottom left, and create a new key. The secret key is necessary for making an API request.

Copy the Copilot ID from the Continual Console

Log into https://console.continual.ai (opens in a new tab)
Click on an existing copilot and copy the copilotId either by looking at the url https://console.continual.ai/copilots/<copilotId>/overview or clicking on it in the top right corner of the copilot overview page

Sending a message to the copilot

Below are examples in CURL, Python, and Typescript for submitting a message to a copilot as an anonymous user. Because it’s an anonymous user, feel free to set the userId to whatever you’d like.

curl -X POST <https://console.continual.ai/api/v1/runs> -H
    "Content-Type: application/json" --data '{
        "copilotId": "<YOUR-COPILOT-ID>",
        "messages": [
        {
            "type": "user",
            "user": {
            "userId": "<YOUR-USER-ID-OR-ANONYMOUS-ID>",
            "content": [
                {   
                    "type": "text",
                    "text": {
                        "value": ["When was the last maintenance update?"]
                    }
                }]
        } }
    ] }'

Parsing the copilot response

Here's an example of parsing the response to extract the copilot's message.

import requests
import json
 
url = "https://console.continual.ai/api/runs"
headers = {
    "Content-Type": "application/json",
    "Authorization": "Bearer <YOUR-API-SECRET>"
}
data = {
    "copilotId": "<YOUR-COPILOT-ID>",
    "messages": [
        {
            "type": "user",
            "user": {
                "userId": "brendan",
                "content": [
                    {
                        "type": "text",
                        "text": {
                            "value": ["Howdy partner!"]
                        }
                    }
                ]
            }
        }
    ]87
}
def parse_events(response):
    events = []
    for line in response.iter_lines():
        if line:
            decoded_line = line.decode('utf-8')
            if decoded_line.startswith('data:'):
                events.append(json.loads(decoded_line[5:]))
    return events
 
 
response = requests.post(url, json=data, headers=headers, stream=True)
 
# Check if the connection was successful
if response.status_code == 200:
    # Parse the events from the response
    events = parse_events(response)
 
    # Process the events
    for event in events:
        if(event['event'] == 'message:created'):
            if(event['data']['data']['type'] == 'copilot'):
                print("Copilot:", event['data']['data']['copilot']['content'][0]['text']['value'][0])
 
else:
    print("Failed to connect, status code:", response.status_code)

Adding Context to User Messages

Context is any additional data that is sent to the copilot in addition to the user’s message. This includes the Instructions by default but can also include arbitrary data such as a PDF attachment or where the user is within the application.

The additionalInstructions field in the request parameters can be used to give the copilot information about context on a per run basis. The field is a string and it can be used to prompt the copilot to handle data that is passed in per run.

This enables use cases like summarization of content on a webpage or JSON app data. Here is an example JSON for a sales reps weekly calendar:

curl -X POST <https://console.continual.ai/api/v1/runs> -H
   "Content-Type: application/json" --data '{
        "copilotId":"<YOUR-COPILOT-ID>",
        "messages": [
       {
         "type": "user",
         "user": {
           "userId": "<YOUR-USER-ID-OR-ANONYMOUS-ID>",
           "content": [
             {
               "type": "text",
               "text": {
                 "value": ["Could you summarize my morning meetings
   for the week?"]
} }
] }
} ],
        "additionalInstructions": "The following JSON describes the
   users appointments for the week:\\n {
       "sales_representative": "John Doe",
       "week": "2023-12-18 to 2023-12-24",

     "appointments": [
        {
            "day": "Monday",
            "time_of_day": "Morning",
            "client": "Client A",
            "location": "Location 3",
            "meeting_notes": "Discuss software interface design
and user experience requirements."
        },
        {
            "day": "Monday",
            "time_of_day": "Afternoon",
            "client": "Client B",
            "location": "Location 8",
            "meeting_notes": "Review database scalability and
security features needed."
        },
        {
            "day": "Wednesday",
            "time_of_day": "Morning",
            "client": "Client A",
            "location": "Location 3",
            "meeting_notes": "Discuss software interface design
and user experience requirements."
        },
        {
            "day": "Wednesday",
            "time_of_day": "Afternoon",
            "client": "Client B",
            "location": "Location 7",
            "meeting_notes": "Review database scalability and
security features needed."
        },
        {
            "day": "Friday",
            "time_of_day": "Morning",

             "client": "Client A",
            "location": "Location 9",
            "meeting_notes": "Discuss software interface design
and user experience requirements."
        },
        {
            "day": "Friday",
            "time_of_day": "Afternoon",
            "client": "Client B",
            "location": "Location 8",
            "meeting_notes": "Review database scalability and
security features needed."
        }
] }"
}'

Enabling conversations

Each API call returns a threadId allowing you, the app developer, to support conversational use cases. To submit a message to a specific thread, simply add a threadId to your api call as shown below.

Using the same CURL example from above:

curl -X POST https://console.continual.ai/api/v1/runs \
  -H "Content-Type: application/json" \
  --data '{
    "copilotId": "<YOUR-COPILOT-ID>",
    "threadId": "<YOUR-THREAD-ID>",
    "messages": [
      {
        "type": "user",
        "user": {
          "userId": "<YOUR-USER-ID-OR-ANONYMOUS-ID>",
          "content": [
            {
              "type": "text",
              "text": {
                "value": ["Hello!"]
              }
            }
          ]
        }
      }
    ]
  }'

Create a copilot for an EdTech application @continual/react