Conversations

Overview

A Conversation represents an interactive session between the user and a Team of agents. Conversations maintain context across multiple prompts to support coherent human-like dialog. Conversations selectively load relevant chat history to help the LLM understand references and summarize past interactions to stay within token limits.

In Platform version 5.2, streaming conversations were introduced. This feature allows users to receive updates in real-time as a team processes their request.

The AI Service now supports two main types of conversations:

• Non-streaming conversations
• Streaming conversations

Non-streaming conversations

A non-streaming conversation will just have simple notifications to let the user know that the AI Service has started and then at the end, that it has concluded or resulted in an error.

How to create a conversation

To create a non-streaming conversation with a team, do the following:

1. In the Conversation Javascript object, enter the ID of the Team you want to recruit for the conversation in the property _teamId.
2. Pass the user's question in the property _input.message.
3. Submit this Conversation object to the createConversation Javascript API.

As an example, refer to the Conversation object below.

{
  _id: "8c7c8cbc-8197-4ddd-a8b8-062e3f0d4474",
  _input: {
    "message": "filter only dtType Glazing - Exterior"
  },
  _teamId: "fd0b746e-050b-40b4-bf1b-cc423402176e"
}

Conversation properties

Property	Type	Required	Description
_id	String	Optional	Conversation ID to continue an existing conversation
_input	Object	Required	Input for the conversation.
message	String	Required	The text input message content to send to the generative AI.
_teamId	String	No	The team ID for the conversation

Streaming conversations

The AI Service now allows users to run conversations through a steaming connection. As the team processes a request, progress updates are pushed to the user's screen in real-time. Previously, in normal conversations, users would just receive an indication that the team had started processing and then be notified with the final response. During processing, there had been no indication as to what was actually happening and the user would not know if the process had stalled or was still working.

Now the AI Service, can send streaming notifications each time the team starts reasoning, calls a tool, or accesses a resource such as a knowledge base. This stream of notifications is much more useful to the user and offers a more informative and engaging user experience.

Process status notifications

The process-status notification was introduced to support streaming conversation updates. It contains a phase identifier which corresponds to a point in the AI process. It also contains a short descriptive message for each notification, which is displayed to update the user.

List of process phases and notification messages

The table below lists each process phase and the message sent for each phase.

Process phase	Message shown to user
History loading	"Loading conversation history"
History ready	"Conversation history ready"
Knowledge base search starting	"Searching knowledge base..."
Knowledge base search complete	"Knowledge base search complete"
External tools loading	"Loading external tools"
External tools ready	"External tools ready"
AI is beginning to write	""Generating response..." "
The agent finished its turn	"[Agent name] finished"

Complete stream notification catalog

This table lists every notification type which the streaming connection can send.

Notification	What it tells the user
Conversation started	Conversation ID confirmed
Response token	One word/token of the agent's answer
Summary	The complete final response text
Conversation complete	Full pipeline finished
Error	Something went wrong
The team started working	The agent team has begun processing
Agent invoked	Name the specific agent now working
Agent invocation message	The custom message configured on that agent
Tool called	Name of the tool and what was sent to it
Tool result	Name of the tool and what it returned
AI is analyzing	The AI has begun its reasoning step
Process status	A human-readable progress update (see table of process phases above)
Team finished	All agents have completed their turns

Invocation message field

To support streaming conversations, a new optional field invocationMessage has been added to the agent record. When an agent with an invocation message is called during a conversation, that message is sent to the client immediately after the agent-invoked notification.

The invocationMessage field is used by the createAgents and updateAgent API methods. See table below for a summary.

Field	Type	Required	Description
invocationMessage	Text (maximum 500 characters)	No	The plain-text message is displayed to users when this agent begins working in a conversation. Leave blank to show no custom message. Setting to blank or null also removes any previously configured message.

For example, consider an agent named "Data Model Specialist" which is configured with the invocation message "Researching your question on data models, please wait...". Any user who calls that agent during a conversation will be presented with that message.

Example agent JSON record with custom _invocationMessage

{
      "_name": "Data Model Specialist",
      "_userType": "model_specialist",
      "_description": "Answers data-model questions",
      "_background": "You are the Data Model Specialist for a digital-twin platform.",
      "_config": { "_provider": "openai", "_model": "gpt-4o"},
      "_tools": ["GetNamedUserItemTool"],
      "_invocationMessage": "Researching your question on data models, please wait...",
      "_namespaces": ["{{nsfilter}}"]
}

streamConversation method

The IafAISvc Javascript API now has the streamConversation method. This method establishes a real-time streaming connection and sends developer-supplied callbacks as each notification type arrives.

Note: For conversations that do not require streaming, use the createConversation method instead.

The streamConversation method accepts the same conversation request object as createConversation, plus a second argument — a single event hanlder function - onEvent.

Rather than a set of per-notification callbacks, every notification is delivered to this one handler as an object of the form { type, payload }, where type is the stream event name and payload is the parsed JSON body (or the raw string if the body is not JSON).

Callers switch on type to react only to the notifications they care about. Types which are not handled are simply ignored.

Event types delivered to onEvent:

event.type	Delivered when	event.payload
conversation	The conversation ID is confirmed, and streaming begins (fires once).	{id}
team-start	The agent team has started working.	empty
agent-invoked	A specific agent has begun its turn.	{agentName}
agent-invocation-message	The custom invocation message for that agent (only if one is configured).	{agentName, message}
llm-analysing	The AI has begun its reasoning or planning step.	{agentName?}
tool-invoked	A tool has been called.	{toolName, input?, callId?, agentName?}
tool-result	A tool has returned its result.	{toolName, output?, callId?, agentName?, truncated?}
process-status	A progress notification for a silent phase.	{phase, description, agentName?}
agent-message	A response token or chunk of information from the AI.	{id?, agent?, delta, isFinal, path?}
team-done	All agents in the team have completed their turns.	empty
summary	The complete final response text (fires once, just before complete).	{content}
complete	The full conversation response is finalised.	{_id, _output}
error	The server signalled an error, or the connection failed.	Error/{message}
close	Terminal frame	empty

How the streamConversation method works

The streamConversation method returns a handle with two components:

• abort() — Tears the connection down immediately. For example, if the user navigates away or cancels.
• done — A promise that resolves when the stream ends normally and rejects if the connection fails before complete or error could be delivered.

Calling sequence

The streamConversation calling sequence works as follows:

1. The application calls streamConversation with a request object and an onEvent handler.
2. A streaming connection is opened to the AI Service.
3. As each notification arrives, onEvent is invoked immediately with { type, payload }.
4. When the stream ends, a complete or error event is delivered. The terminal close frame follows. The connection closes, and is concluded by done.
5. If the caller calls abort() on the returned handle before the stream ends, the connection is cleanly torn down.

Javascript API support

Streaming conversations are supported in the Javascript API by the createAgents, updateAgent, and streamConversation API methods.

For more information see the IafAISvc page in the Javascript API section.

REST API support

In the REST API, you can use the Create Conversations API call to set up a streaming converstation.

It has the endpoint:

POST /aisvc/api/v1/conversations

To specify a streaming conversation, set the Boolean parameters stream to true, and sync to true.

Query parameters

Parameter	Type	Description	Required
nsfilter	String	Filter by namespace.	Required
sync	Boolean	Perform synchronous/asynchronous conversation.	Optional
stream	Boolean	When true (together with sync=true), stream the response as Server-Sent Events instead of returning a single JSON body.	Optional

For more information see the Conversations page in the REST API section.