Search documentation
karat

+

K

User Documentation ↗
Version 2.0

Get Session Trace

GET/api/v2/aipAgents/agents/{agentRid}/sessions/{sessionRid}/sessionTraces/{sessionTraceId}
Warning

This endpoint is in preview and may be modified or removed at any time. To use this endpoint, add preview=true to the request query parameters.

Get the trace of an Agent response. The trace lists the sequence of steps that an Agent took to arrive at an answer. For example, a trace may include steps such as context retrieval and tool calls. Clients should poll this endpoint to check the realtime progress of a response until the trace is completed.

Third-party applications using this endpoint via OAuth2 must request the following operation scope: api:aip-agents-read.

Path parameters

agentRid
string

An RID identifying an AIP Agent created in AIP Agent Studio.

sessionRid
string

The Resource Identifier (RID) of the conversation session.

sessionTraceId
string

The unique identifier for the trace.

Query parameters

preview
boolean
optional

Enables the use of preview functionality.

Response body

SessionTrace
object
Hide child attributes

Hide child attributes

id
string

The unique identifier for the trace.

status
string (enum)

This indicates whether the Agent has finished generating the final response. Clients should keep polling the getSessionTrace endpoint until the status is COMPLETE.

Enum values: IN_PROGRESS, COMPLETE

contexts
object
optional

Any additional context which was provided by the client or retrieved automatically by the agent, grouped by context type. Empty if no additional context was provided or configured to be automatically retrieved. A present SessionExchangeContexts object with empty lists indicates that context retrieval was attempted but no context was found. Note that this field will only be populated once the response generation has completed.

Show child attributes

Show child attributes

toolCallGroups
list<ToolCallGroup>
optional

List of tool call groups that were triggered at the same point in the trace for the agent response generation. The groups are returned in the same order as they were triggered by the agent.

Show child attributes

Show child attributes

Examples

Request

Copied!
1 2 3 curl \ -H "Authorization: Bearer $TOKEN" \ "https://$HOSTNAME/api/v2/aipAgents/agents/ri.aip-agents..agent.732cd5b4-7ca7-4219-aabb-6e976faf63b1/sessions/ri.aip-agents..session.292db3b2-b653-4de6-971c-7e97a7b881d6/sessionTraces/12345678-1234-5678-1234-123456789abc?preview=true"

Response

Copied!
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 { "toolCallGroups": [ { "toolCalls": [ { "toolMetadata": { "name": "Object Query Tool", "type": "FUNCTION" }, "input": { "thought": "I need to find the customer with the name 'Titan Technologies'." } } ] } ], "id": "12345678-1234-5678-1234-123456789abc", "contexts": { "objectContexts": [ { "objectRids": [ "ri.phonograph2-objects.main.object.48668bf6-8878-48d2-b8f8-f0017593feb5" ], "propertyTypeRids": [ "ri.ontology.main.property.7899aeb4-a389-4f2e-a0fd-e7193a4f6cb1" ] } ] }, "status": "IN_PROGRESS" }

Error responses

Error Name
SessionTraceNotFoundError CodeNOT_FOUND
Status Code404
DescriptionThe given SessionTrace could not be found.
ParameterssessionTraceId, agentRid, sessionRid
SessionNotFoundError CodeNOT_FOUND
Status Code404
DescriptionThe given Session could not be found.
ParametersagentRid, sessionRid
AgentNotFoundError CodeNOT_FOUND
Status Code404
DescriptionThe given Agent could not be found.
ParametersagentRid