1# Foundry Agent Troubleshoot
2 
3Troubleshoot and debug Foundry agents by collecting hosted-agent session logs, discovering observability connections, and querying Application Insights telemetry.
4 
5## Quick Reference
6 
7| Property | Value |
8|----------|-------|
9| Agent types | Prompt (LLM-based), Hosted |
10| MCP servers | `azure` |
11| Key Foundry MCP tools | `agent_get` |
12| Related skills | `trace` (telemetry analysis) |
13| Preferred query tool | `monitor_resource_log_query` (Azure MCP) — preferred over `azure-kusto` for App Insights |
14| CLI references | `az cognitiveservices account connection`, `az rest`, `curl` |
15 
16## When to Use This Skill
17 
18- Agent is not responding or returning errors
19- Hosted agent version is not becoming active
20- Need to view hosted-agent session logs
21- Diagnose latency or timeout issues
22- Query Application Insights for agent traces and exceptions
23- Investigate agent runtime failures
24 
25## MCP Tools
26 
27| Tool | Description | Parameters |
28|------|-------------|------------|
29| `agent_get` | Get agent details to determine type and inspect agent/version status | `projectEndpoint` (required), `agentName` (optional) |
30 
31## Workflow
32 
33### Step 1: Collect Agent Information
34 
35Use the project endpoint and agent name from the project context (see [Common Project Context Resolution](../../SKILL.md#agent-common-project-context-resolution)). Ask the user only for values not already resolved:
36- **Project endpoint** — AI Foundry project endpoint URL
37- **Agent name** — Name of the agent to troubleshoot
38 
39### Step 2: Determine Agent Type
40 
41Use `agent_get` with `projectEndpoint` and `agentName` to retrieve the agent definition. Check the `kind` field:
42- `"hosted"` → Proceed to Step 3
43- `"prompt"` → Skip to Step 4 (Discover Observability Connections)
44 
45### Step 3: Retrieve Logs (Hosted Agents Only)
46 
47Hosted-agent logs are scoped to individual **sessions** (sandbox instances).
48 
49> ℹ️ **`invocations_ws` agents:** the `sessionId` used by these REST endpoints is the **client-supplied `agent_session_id`** that the WebSocket client put on the upgrade URL — not a value issued by `session_create`. If the user has the WS client logs, pull the `agent_session_id` from there and pass it as `sessionId` below. See the [invocations-ws skill](../invocations-ws/invocations-ws.md) for the WS URL contract.
50 
511. **Check agent version status** — Use `agent_get` to verify the agent version status is `active`. If it is not active, the agent may still be provisioning or may have failed to become active.
52 
532. **List sessions** — Hosted-agent logs require a `sessionId`. If the user does not have one, list available sessions:
54   ```bash
55   az rest --method GET \
56     --url "<projectEndpoint>/agents/<agentName>/sessions?api-version=2025-11-15-preview" \
57     --headers "Foundry-Features=HostedAgents=V1Preview" \
58     --resource "https://ai.azure.com"
59   ```
60 
613. **Retrieve session logs** — The log stream endpoint uses Server-Sent Events (SSE). Use `curl` with a timeout:
62   ```bash
63   TOKEN=$(az account get-access-token --resource "https://ai.azure.com" --query accessToken -o tsv)
64   curl -s --max-time 15 \
65     -H "Authorization: Bearer $TOKEN" \
66     -H "Accept: text/event-stream" \
67     -H "Foundry-Features: HostedAgents=V1Preview" \
68     "<projectEndpoint>/agents/<agentName>/sessions/<sessionId>:logstream?api-version=2025-11-15-preview"
69   ```
70 
71   > ⚠️ **404 is expected** if the session sandbox has not been created yet. Advise the user to send a message to the agent first to trigger sandbox creation, then retry.
72 
734. **Interpret the logs** — Each SSE frame is `event: log\ndata: {...}\n\n`:
74   - **Preamble** (first event): JSON with `session_state`, `session_id`, `agent`, `version`, `last_accessed`
75   - **Log lines** (subsequent events): JSON with `stream` (`stdout`/`stderr`/`status`), `message`, and `timestamp`
76   - **Error events**: `event: error` frames indicate server-side errors within the session sandbox
77 
78   Present the logs to the user and highlight any errors or warnings found.
79 
80### Step 4: Discover Observability Connections
81 
82List the project connections to find Application Insights or Azure Monitor resources using the Azure CLI command documented at:
83[az cognitiveservices account connection](https://learn.microsoft.com/en-us/cli/azure/cognitiveservices/account/connection?view=azure-cli-latest)
84 
85Refer to the documentation above for the exact command syntax and parameters. Look for connections of type `ApplicationInsights` or `AzureMonitor` in the output.
86 
87If no observability connection is found, inform the user and suggest setting up Application Insights for the project. Ask if they want to proceed without telemetry data.
88 
89### Step 5: Query Application Insights Telemetry
90 
91Use **`monitor_resource_log_query`** (Azure MCP tool) to run KQL queries against the Application Insights resource discovered in Step 4. This is preferred over delegating to the `azure-kusto` skill. Pass the App Insights resource ID and the KQL query directly.
92 
93> ⚠️ **Always pass `subscription` explicitly** to Azure MCP tools like `monitor_resource_log_query` — they don't extract it from resource IDs.
94 
95Use `* contains "<response_id>"` or `* contains "<agent_name>"` filters to narrow down results to the specific agent instance.
96 
97### Step 6: Summarize Findings
98 
99Present a summary to the user including:
100- **Agent type and status** — hosted or prompt; hosted agent version status when relevant
101- **Log errors** — key errors from hosted-agent session logs
102- **Telemetry insights** — exceptions, failed requests, latency trends
103- **Recommended actions** — specific steps to resolve identified issues
104 
105## Error Handling
106 
107| Error | Cause | Resolution |
108|-------|-------|------------|
109| Agent not found | Invalid agent name or project endpoint | Use `agent_get` to list available agents and verify name |
110| Hosted agent not active | Hosted agent is still provisioning or failed | Check that the ACR image was pushed correctly and agent identity permissions are assigned; wait and re-check status |
111| Session logs 404 | Session sandbox has not been created yet | The sandbox is created on first invocation — send a message to the agent to trigger sandbox creation, then retry |
112| SSE error event | Server-side error within the session sandbox | Check the error event `data` field for details |
113| No session ID | User does not know which session to troubleshoot | List sessions via REST API (see Step 3) |
114| No observability connection | Application Insights not configured for the project | Suggest configuring Application Insights for the Foundry project |
115| Kusto query failed | Invalid cluster/database or insufficient permissions | Verify Application Insights resource details and reader permissions |
116| No telemetry data | Agent not instrumented or too recent | Check if Application Insights SDK is configured; data may take a few minutes to appear |
117 
118## Additional Resources
119 
120- [Foundry Hosted Agents](https://learn.microsoft.com/azure/ai-foundry/agents/concepts/hosted-agents?view=foundry)
121- [Account Connection CLI Reference](https://learn.microsoft.com/en-us/cli/azure/cognitiveservices/account/connection?view=azure-cli-latest)
122- [KQL Quick Reference](https://learn.microsoft.com/azure/data-explorer/kusto/query/kql-quick-reference)
123- [Foundry Samples](https://github.com/microsoft-foundry/foundry-samples)
124