Managing conversations
Listing conversations
Listing conversations returns only the conversations the calling user started, newest first. A user looking through their history sees their own conversations, not everyone's in the project.
const mine = await IafAISvc.getConversations({}, ctx, { _pageSize: 50 });
To list every user's conversations in the namespace, for example so an administrator can review usage, pass allUsers: true:
const everyone = await IafAISvc.getConversations({ allUsers: true }, ctx, { _pageSize: 50 });
This requires READ on all conversations in the namespace, which means aisvc:conversation:* or a broader grant such as aisvc:*:*, held directly or through a user group. Users who can only read individual conversations that were shared with them get a 403. They can still open each shared conversation by its id. Pagination and ordering work the same way in both cases.
To order by something other than creation time, pass _sortBy (createdAt or updatedAt) and optionally _sortOrder (asc or desc, default desc) with the other options. For example, to show the conversations that were most recently continued first:
const recent = await IafAISvc.getConversations({}, ctx, { _sortBy: 'updatedAt', _sortOrder: 'desc', _pageSize: 50 });
The same two options work when listing agents, tools, teams, MCP tools, MCP tool filters, external MCP server configs and knowledge bases.
Deleting conversations
Deleting a conversation removes it permanently, along with its turns, attachment references, token usage and traces. There is no undo, and a deleted conversation cannot be resumed.
To delete one conversation, pass its id:
await IafAISvc.deleteConversation(conversationId, ctx);
This requires DELETE permission on the conversation. A user with the Platform Manager role can delete any user's conversation in any namespace without holding conversation permissions there.
A Platform Manager can also clear a namespace's entire conversation history, for example for cleanup or data retention. So can a user who holds DELETE on all conversations in the namespace (aisvc:conversation:* or aisvc:*:*). Because the delete covers every user's conversations, you have to confirm it explicitly with { _scope: 'all' }, and ctx has to name exactly one namespace:
const { _deleted } = await IafAISvc.deleteAllConversations({ _scope: 'all' }, { ...ctx, _namespaces: ['your_namespace'] });
The namespace delete is all or nothing: if anything fails, no conversations are deleted. Users who can delete only individual conversations get a 403.
Each delete is audited. A ResourceHardDeleted event is written for every deleted conversation, and the delete is logged with who performed it, when, in which namespace, and which conversations were removed. For the REST endpoints, response codes and audit details, see Delete Conversation.
Response language
While a Team works, the AI Service produces text of its own: the progress captions a streaming client renders, and the message on an error. Send an Accept-Language header to choose the language for that text — en and ja are supported, and anything else falls back to en.
const conversation = await IafAISvc.createConversation(
request, ctx, { headers: { 'Accept-Language': 'ja' } }
);
The same option works on IafAISvc.streamConversation, where it decides the language of the process-status captions and any error frame:
IafAISvc.streamConversation(request, onEvent, ctx, { headers: { 'Accept-Language': 'ja' } });
This does not translate the answer. The agent's response follows its prompt and system message, so an agent written in English answers in English however this header is set. To change the language of the answer itself, write the prompt in that language or configure the agent for it.