1# Search Traces — Conversation-Level Search
2 
3Search agent traces at the conversation level. Returns summaries grouped by conversation or operation, not individual spans.
4 
5## Prerequisites
6 
7- App Insights resource resolved (see [trace.md](../trace.md) Before Starting)
8- Selected agent root, metadata file, and environment confirmed from `.foundry/agent-metadata*.yaml`
9- Time range confirmed with user (default: last 24 hours)
10 
11## Search by Conversation ID
12 
13Keep the selected environment visible in the summary, and add the selected agent name or environment tag filters when the telemetry emits them.
14 
15```kql
16dependencies
17| where timestamp > ago(24h)
18| where customDimensions["gen_ai.conversation.id"] == "<conversation_id>"
19| project timestamp, name, duration, resultCode, success,
20    operation = tostring(customDimensions["gen_ai.operation.name"]),
21    model = tostring(customDimensions["gen_ai.request.model"]),
22    inputTokens = toint(customDimensions["gen_ai.usage.input_tokens"]),
23    outputTokens = toint(customDimensions["gen_ai.usage.output_tokens"]),
24    operation_Id, id, operation_ParentId
25| order by timestamp asc
26```
27 
28## Search by Response ID
29 
30Auto-detect the response ID format to determine agent type:
31- `caresp_...` → Hosted agent (AgentServer)
32- `resp_...` → Prompt agent (Foundry Responses API)
33- `chatcmpl-...` → Azure OpenAI chat completions
34 
35```kql
36dependencies
37| where timestamp > ago(24h)
38| where customDimensions["gen_ai.response.id"] == "<response_id>"
39| project timestamp, name, duration, resultCode, success,
40    operation = tostring(customDimensions["gen_ai.operation.name"]),
41    model = tostring(customDimensions["gen_ai.request.model"]),
42    inputTokens = toint(customDimensions["gen_ai.usage.input_tokens"]),
43    outputTokens = toint(customDimensions["gen_ai.usage.output_tokens"]),
44    operation_Id, id, operation_ParentId
45```
46 
47Then drill into the full conversation:
48 
49> ⚠️ **STOP — read [Conversation Detail](conversation-detail.md) before writing your own drill-down query.** It contains the correct span tree reconstruction logic, event/exception queries, and eval correlation steps.
50 
51Quick drill-down using the `operation_Id` from above:
52 
53```kql
54dependencies
55| where operation_Id == "<operation_id_from_above>"
56| project timestamp, name, duration, resultCode, success,
57    spanId = id, parentSpanId = operation_ParentId,
58    operation = tostring(customDimensions["gen_ai.operation.name"]),
59    model = tostring(customDimensions["gen_ai.request.model"]),
60    inputTokens = toint(customDimensions["gen_ai.usage.input_tokens"]),
61    outputTokens = toint(customDimensions["gen_ai.usage.output_tokens"]),
62    responseId = tostring(customDimensions["gen_ai.response.id"]),
63    errorType = tostring(customDimensions["error.type"]),
64    toolName = tostring(customDimensions["gen_ai.tool.name"])
65| order by timestamp asc
66```
67 
68Also check for eval results: see [Eval Correlation](eval-correlation.md).
69 
70## Search by Agent Name
71 
72> **Note:** For hosted agents, `gen_ai.agent.name` in `dependencies` refers to *sub-agents* (e.g., `BingSearchAgent`), not the top-level hosted agent. See "Search by Hosted Agent Name" below.
73 
74> 💡 **Hosted-agent versioning:** If you need the deployed version, use the hosted-agent pattern below and parse `gen_ai.agent.id` when it is emitted in `<agent-name>:<version>` format.
75 
76```kql
77dependencies
78| where timestamp > ago(24h)
79| where customDimensions["gen_ai.agent.name"] == "<agent_name>"
80| summarize
81    startTime = min(timestamp),
82    endTime = max(timestamp),
83    totalDuration = max(timestamp) - min(timestamp),
84    spanCount = count(),
85    errorCount = countif(success == false),
86    totalInputTokens = sum(toint(customDimensions["gen_ai.usage.input_tokens"])),
87    totalOutputTokens = sum(toint(customDimensions["gen_ai.usage.output_tokens"]))
88  by conversationId = tostring(customDimensions["gen_ai.conversation.id"]),
89     operation_Id
90| order by startTime desc
91| take 50
92```
93 
94## Search by Hosted Agent Name
95 
96For hosted agents, the Foundry agent name (e.g., `hosted-agent-022-001`) appears on `requests` and `traces` — NOT on `dependencies`. Use `requests` as the preferred entry point, materialize the matching request rows, then join downstream spans on `operation_Id`:
97 
98```kql
99let agentRequests = materialize(
100    requests
101| where timestamp > ago(24h)
102| extend
103    foundryAgentName = coalesce(
104        tostring(customDimensions["gen_ai.agent.name"]),
105        tostring(customDimensions["azure.ai.agentserver.agent_name"])
106    ),
107    agentId = tostring(customDimensions["gen_ai.agent.id"]),
108    agentNameFromId = tostring(split(agentId, ":")[0]),
109    agentVersion = iff(agentId contains ":", tostring(split(agentId, ":")[1]), ""),
110    conversationId = coalesce(
111        tostring(customDimensions["gen_ai.conversation.id"]),
112        tostring(customDimensions["azure.ai.agentserver.conversation_id"]),
113        operation_Id
114    )
115| where foundryAgentName == "<agent_name>"
116    or agentNameFromId == "<agent_name>"
117| project operation_Id, conversationId, agentVersion
118);
119dependencies
120| where timestamp > ago(24h)
121| where isnotempty(customDimensions["gen_ai.operation.name"])
122| join kind=inner agentRequests on operation_Id
123| summarize
124    startTime = min(timestamp),
125    endTime = max(timestamp),
126    spanCount = count(),
127    errorCount = countif(success == false),
128    totalInputTokens = sum(toint(customDimensions["gen_ai.usage.input_tokens"])),
129    totalOutputTokens = sum(toint(customDimensions["gen_ai.usage.output_tokens"]))
130  by conversationId, operation_Id, agentVersion
131| order by startTime desc
132| take 50
133```
134 
135If `gen_ai.agent.id` does not contain `:`, continue using the requests-scoped name fields for filtering and treat `agentVersion` as optional enrichment rather than a required key.
136 
137## Conversation Summary Table
138 
139Present results in this format:
140 
141| Conversation ID | Agent Version | Start Time | Duration | Spans | Errors | Input Tokens | Output Tokens |
142|----------------|---------------|------------|----------|-------|--------|-------------|---------------|
143| conv_abc123 | 3 | 2025-01-15 10:30 | 4.2s | 12 | 0 | 850 | 320 |
144| conv_def456 | 4 | 2025-01-15 10:25 | 8.7s | 18 | 2 | 1200 | 450 |
145 
146Highlight rows with errors in the summary. Offer to drill into any conversation via [Conversation Detail](conversation-detail.md).
147 
148## Free-Text Search
149 
150When the user provides a general search term (e.g., agent name, error message):
151 
152```kql
153union dependencies, requests, exceptions, traces
154| where timestamp > ago(24h)
155| where * contains "<search_term>"
156| summarize count() by operation_Id
157| order by count_ desc
158| take 20
159```
160 
161## After Successful Query
162 
163> 📝 **Reminder:** If this is the first trace query in this session, ensure App Insights connection info was persisted to the selected metadata file for the selected environment (see [trace.md — Before Starting](../trace.md#before-starting--resolve-app-insights-connection)).
164