Skip to main content

Long-running AI conversations

Manage AI assistants, conversation threads, and context files to create a unique AI experience for users​

With AI assistants, conversations take place in threads, allowing the assistant to incorporate information from the ongoing conversation. This creates a bespoke experience that allows you to connect with users on a level that is both personal and global.

Benefits​

  • Access conversation history across user sessions so the right people have the right information when they need it.
  • Provide support to users on a global scale at the assistant level that can take in files as context and respond accordingly.
  • Create a unique experience for users at the thread level, enabling uniquely relevant interactions.
  • Generate new assistants and context on the fly with unique instructions to suit varying needs.

To interact with the assistant, use the Squid Client SDK.

Note

Squid AI assistant requires admin access, so its methods must be run in the Squid backend.

Create the assistant client​

To perform assistant operations, first create an assistant client using the ai().assistant() method:

Backend code
const assistantClient = squid.ai().assistant();

Create an assistant​

To create a new AI assistant, use the createAssistant method. The method takes the following parameters:

  • name - The name of the assistant.
  • instructions - Instructions for the assistant. For example, "You are a pirate; only answer questions like a pirate would."
  • functions - An optional array of function names annotated with @aiFunction in your Squid backend that are available to the assistant. For more information, see the documentation on AI functions.
  • toolTypes - An optional array of tool types. The two available tool types are 'code_interpreter' and 'retrieval'. Code interpreter uses a working Python interpreter in a sandboxed, firewalled execution environment. Retrieval provides a flexible solution for semantic search and retrieval of personal or organizational documents using natural language queries.

The method returns a promise that resolves to the created assistant's ID. Use the assistant ID to manage actions on the assistant, like adding or deleting threads, adding or deleting files, and deleting the assistant. For future access, you can store the assistant ID in your database solution using the Squid Client SDK and your database connector.

Backend code
const assistantId = await assistantClient.createAssistant(
  'YOUR_ASSISTANT_NAME',
  "YOUR ASSISTANT'S INSTRUCTIONS",
  ['AI_FUNCTION_NAME_1', 'AI_FUNCTION_NAME_2'],
  ['ASSISTANT_TOOL_TYPE_1', 'ASSISTANT_TOOL_TYPE_2']
);

Create a thread​

Conversations with an AI assistant take place in threads. Each thread is a long-persistent conversation within a specified assistant that you can send questions to. AI assistants require at least one thread in order to interact with them.

To create a new thread, use the createThread method, passing the ID of the AI assistant for which the thread is created. This method creates a new thread for an AI assistant.

This method returns a promise that resolves to the created thread's ID.

Backend code
const threadId = await assistantClient.createThread(assistantId);

Like the assistant ID, you can store this thread ID in your database solution to access the conversation in the future using the Squid Client SDK and your database connector.

Add a file to the assistant​

To add a file to an AI assistant for retrieval or code analysis, use the addFileToAssistant method, passing the assistant ID and the file. The method returns a promise that resolves to the ID of the added file.

When adding a file from a frontend, use the File type.
When adding a file from a backend environment, use the BlobAndFilename type.

Backend code
const fileId = await assistantClient.addFileToAssistant(assistantId, YOUR_FILE);

Remove a file from the assistant​

To remove a file from the assistant, use the removeFileFromAssistant method, passing the assistant ID and the file ID of the file you are removing:

Backend code
await assistantClient.removeFileFromAssistant(assistantId, fileId);

This method returns a promise that resolves when the file is removed.

Add a file to a thread​

AI assistants support providing context on the fly during a conversation. Users can provide documents or images to a specific thread, and the assistant can then respond to queries based on those files.

To add a file to a thread, use the addFileToThread method, passing the thread ID and the file.

When adding a file from a frontend, use the File type.
When adding a file from a backend environment, use the BlobAndFilename type.

Backend code
const fileId = await assistantClient.addFileToThread(threadId, FILE_TO_ADD);

Like adding a file to an assistant, this method returns a promise that resolves to the ID of the added file.

Note

Files added to a specific thread are only accessible to that thread. The context provided by these files is not available to other threads within the same assistant.

Query the assistant​

To send a question to the assistant, use the queryAssistant method, passing the assistant ID, thread ID, prompt, and the file IDs for any relevant files. File IDs are associated with the given thread.

This method returns a promise that resolves to the assistant's response.

Backend code
const response = await assistantClient.queryAssistant(
  assistantId,
  threadId,
  "What is our company's policy on bringing pets to the office?",
  fileId
);

By default, query responses are in string format. Responses in JSON format can be very useful for automating tasks because they simplify the process of passing values to other functions or taking actions on a database like queries or writes.

To specify the query response type, include the optional options parameter with your queryAssistant call:

Backend code
const response = await queryAssistant(
  assistantId,
  threadId,
  "What is our company's policy on bringing pets to the office? Respond in JSON format",
  fileId,
  { responseFormat: 'json_object' } // options
);

The options object currently has multiple attributes, which can be found in the reference documentation.

Note

when specifying json_object as the response format, your prompt must include the word "JSON".

Delete an assistant​

To delete an assistant, use the deleteAssistant method, passing the assistant ID.

This function returns a promise that resolves when the assistant is deleted.

Backend code
await assistantClient.deleteAssistant(assistantId);

Delete a thread​

To delete a thread, use the deleteThread method, passing the thread ID.

This function returns a promise that resolves when the assistant is deleted.

Backend code
await assistantClient.deleteThread(threadId);