Skip to main content

Concepts

note

This page provides a few key concepts that are important to understand before you start using the Agents. We also cover a few different use cases and which endpoints may be most appropriate for you for those use cases

Agents​

An Agent is an AI agent available on the Engage Smarter AI platform. An Agent is what you call when you are looking for a response to specific inputs.

Different Agents have different capabilities and are tuned and tested for use in different use cases. As an organisation you may have specific custom Agents available for your use cases that are only available on your organisation.

Any agent can be selected and used with either the Conversations or Runs API.

Messages​

These Message objects that represent a UserMessage, an AgentMessage or other key messages such as status or info messages.

All messages follow the same data structure which includes the content.

Conversations API​

The use of the Conversations API is recommended for most use cases, as it provides a more natural conversational experience. Examples of use cases include:

  • You are building a chatbot or virtual assistant
  • You are building a conversational interface for a mobile app
  • You are integrating our AI into a CRM or Live Chat conversational system

A Conversation stores a thread of Message objects that the Agent sees as a conversation. This way when a user makes a request, the previous messages are taken account of in the context.

There is no linkage between different Conversations. So if you start a new conversation, the Agent will not know anything about the messages that may have been created on other Conversations.

Runs API​

The Runs API may be more suitable for batch processing or when a conversational experience is not required. Examples of use cases include:

  • You have a message thread already and wish to use our guardrails to review the thread or message
  • You have a batch of existing conversations you want to get sample AI responses for
  • You are only ever going to require one response from an agent and the user will never be asking a follow up question.

Using the Runs API, your call to the API is a list of messages. The response from the API is a list of AI responses. This is a stateless call to the API and so you do not need to have set up a conversation thread in advance. Under the hood, our API will set up a conversation thread so you can continue the conversation using the Conversations API below if you wish.

This API setup is similar to the OpenAI setup in that each call is stateless and you need to send the full conversation thread each time.

Response options​

By default the API will only return the agent messages generated.

However as these messages are saved to the conversation thread, if you set return_inputs=True, the API will also return the sent messages together with their IDs and metadata when calling the API chat endpoint.

You will see that all messages in this thread have the same run ID for this run, and all are part of the same conversation ID which is created under the hood for this run.