Skip to main content
Version: v5.3

Archiving conversations

Overview​

Introduced in Platform version 5.3, the AI service now records update messages which appear while a conversation is in progress. This new feature archives all messages for every turn, in every conversation, recording the full execution trace of the conversation and noting which agents were invoked.

This feature archives both steaming and non-streaming conversations.

Authorized users can also access APIs to retrieve the archived trace by conversation, and by individual turn.

This feature addresses an issue in previous versions of the AI Service, whereby there was no record of which agent produced an answer or why. Having access to archived conversations messages will help in any analysis of why the AI Service produced a particular answer. Having an archive of these messages can also help with audit and compliance requirements.

How this archiving feature is implemented​

The archiving feature works as follows:

  1. Always-on trace recorder - A new internal component buffers events such as: agent invoked, tool invoked, tool result, process status, attachment status, token usage, and any errors. This recorder component is attached to every conversation turn.
  2. Turn trace store - Once the turn row has been persisted, the buffered events are written to a database table in a single batched insert, one row per event. This operation is linked to both the conversation and the individual turn, and can never fail.
  3. Two new read API endpoints return the archived trace - New API endpoints allow you to retrieve information about a whole conversation, or a single turn. The archived events are paged, filterable by event type, and protected by the existing conversation READ permission.
  4. Configurable retention purge - A scheduled job purges trace rows older than a configurable retention period, defaulting to 30 days.

Catalog of archived events​

The table below describes the full list of events which can be recorded by the archive feature.

Event typeWhen this event occursEvent payload
history_contextThe prior-turn context for this turn has been assembled and fitted to the token budget.{ strategy, turns[], selectedCount, truncated }, each turn carries its ID, how it was selected, and the text that the model received
knowledge_contextAn agent's knowledge base text has been assembled and fitted to its token budget.{ agentName, knowledgeBases[], characters, truncated, text? } — the passage which the agent received and stored in full. knowledgeBases holds knowledge base user types, not IDs, because that is what the retrieval matches on.
attachment_statusA file attachment was selected, loaded, unavailable or failed.{ agentName, provider, name, fileId, fileVersionId, scope, status }
agent_invokedAn agent began its turn.{ agentName, invocationMessage? } — the caption the user was shown while it worked, when one is configured
agent_messageAn agent finished and returned its output.{ agentName, content} — that agent's complete text for this invocation.
supervisor_routeA supervisor chose the next agent (supervisory teams only){ supervisor, selected, reason }
tool_invokedA tool call was issued.{ toolName, callId, agentName, input }
tool_resultA tool call returned.{ toolName, callId, agentName, output, artifact? } — artifact carries the second half of an MCP content_and_artifact result (embedded resources, structuredContent, _meta) and is not sent on the SSE stream.
process_statusAn agent finished its span.{ phase: 'agent_finished', agentName }
errorThe turn failed.{ message, status, failedAgent }

REST API endpoints​

To facilate this new feature, two new READ endpoints are available in the REST API.

HTTP request methodPathPurposeAuthorization
GET/aisvc/api/v1/conversations/{id}/traceArchived trace for a whole conversationconversation:{id} READ
GET/aisvc/api/v1/conversations/{id}/turns/{turnId}/traceArchived trace for one turnconversation:{id} READ

Note: Both endpoints reuse the exact authorization rule already applied by GET /conversations/{id}. A user who can read the conversation can read its trace. Anyone else receives the same HTTP 403 Forbidden access error they receive for the conversation itself.

API query parameters​

These apply to both endpoints.

ParameterTypeDefaultDescription
_offsetinteger (>= 0)0Standard paging offset. A non-integer or negative value returns a HTTP 400 error.
_pagesizeinteger (1 - 200)Service default (25)Page size. Capped because payloads are stored whole. A value outside the range returns a HTTP 400 error.
_eventTypestring (repeatable))AllFilter to one or more event types. For example: ?_eventType=tool_invoked or ?_eventType=tool_invoked&_eventType=tool_result
_turnIdstring (UUID)No defaultConversation endpoint only. This is equivalent to calling the turn endpoint.

Response structure​

The response will have the same structure as the standard paged structure already used across the AI Service.

{
"_list": [
{
"_id": "0f0d0a5e-...",
"_conversationId": "b9c2f0e1-...",
"_turnId": "3d4a17bc-...",
"_sequence": 4,
"_eventType": "tool_invoked",
"_agentName": "Data Model Specialist",
"_toolName": "GetNamedUserItemTool",
"_callId": "call_8fJ2...",
"_payload": {
"input": { "_name": "Doors", "_namespaces": ["ns-acme"] }
},
"_metadata": { "_createdAt": 1755000000000, "_createdById": "auth0|..." }
},
{
"_id": "1a7c33d2-...",
"_conversationId": "b9c2f0e1-...",
"_turnId": "3d4a17bc-...",
"_sequence": 5,
"_eventType": "tool_result",
"_agentName": "Data Model Specialist",
"_toolName": "GetNamedUserItemTool",
"_callId": "call_8fJ2...",
"_payload": { "output": "{\"_list\":[{\"_id\":\"...\"}]}" },
"_metadata": { "_createdAt": 1755000000123, "_createdById": "auth0|..." }
}
],
"_offset": 0,
"_pageSize": 2,
"_total": 27
}

Notes on response​

Note the following:

  • _payload is returned verbatim as archived.
  • Tool inputs and outputs are stored and returned complete. The example above is abbreviated for readability only, and there is no truncation flag because nothing is truncated on the way in.
  • Callers reading a conversation with large tool outputs should page with a modest _pageSize. This is advised as a single page's size is determined by the payloads it contains.

HTTP error responses​

HTTP error codeWhen this error occurs
400Malformed ID, an unknown _eventType, or an out-of-range or non-integer paging value.
403When the caller cannot read the conversation.
404When the conversation does not exist. Note that a conversation that exists but has no archived trace because it predates the feature, or its trace has aged out, will return a 200 error with an empty _list not a 404 error.

Javascript Platform API​

To facilitate the archiving feature, two new methods have been added to the IafAISvc module in the Javascript API:

  • IafAISvc.getConversationTrace
  • IafAISvc.getTurnTrace

See code example below.

Javascript API code example​

// Whole conversation, filtered to tool activity.
// _eventType accepts an array, which IafHelper.addCriteria expands into a repeated
// query parameter — ?_eventType=tool_invoked&_eventType=tool_result. A single string
// value is sent as one occurrence of the parameter.
const page = await IafAISvc.getConversationTrace(conversationId, {
_eventType: ['tool_invoked', 'tool_result'],
_offset: 0,
_pageSize: 50
}, ctx);

// One turn
const turnTrace = await IafAISvc.getTurnTrace(conversationId, turnId, {}, ctx);