Foundry Agent Troubleshoot
Troubleshoot and debug Foundry agents by collecting Hosted Agent logs with azd, discovering observability connections, and querying Application Insights telemetry.
Quick Reference
| Property | Value |
|---|---|
| MCP servers | azure |
| Hosted Agent CLI | azd ai agent show, sessions, monitor |
| Related skills | trace (telemetry analysis) |
| Preferred query tool | monitor_resource_log_query (Azure MCP) — preferred over azure-kusto for App Insights |
| CLI references | azd ai agent show, azd ai agent sessions, azd ai agent monitor, az cognitiveservices account connection |
When to Use This Skill
- Agent is not responding or returning errors
- Hosted agent version is not becoming active
- Need to view hosted-agent session logs
- Diagnose latency or timeout issues
- Query Application Insights for agent traces and exceptions
- Investigate agent runtime failures
Workflow
Step 1: Collect Agent Information
Use the project endpoint and agent name from the project context (see Common Project Context Resolution). Ask the user only for values not already resolved:
- Project endpoint — Microsoft Foundry project endpoint URL
- Agent name — Name of the agent to troubleshoot
Step 2: Identify a Hosted Agent
Treat an azure.yaml service with host: azure.ai.agent as Hosted. Run:
azd ai agent show --output jsonIf azd returns Hosted Agent details, proceed to Step 3. If the command fails for an identified Hosted Agent, diagnose the reported error instead of proceeding to Step 4. Proceed to Step 4 only when azure.yaml has no Hosted Agent service.
Step 3: Retrieve Logs (Hosted Agents Only)
Hosted Agent logs are scoped to sessions. Use azd for session discovery and log retrieval.
invocations_wsagents: use the client-suppliedagent_session_idfrom the WebSocket upgrade URL. It is not created byazd ai agent invoke. Pass it toazd ai agent monitor --session-id. See the invocations-ws skill for the URL contract.
Check agent version status. Use the result from Step 2 and verify that the deployed version is
active.Read logs from the current session.
monitorautomatically reuses the session saved by the last azd invoke:azd ai agent monitor --tail 100Select another session when needed. If no session is saved or the user needs a different one, run:
azd ai agent sessions list --output table azd ai agent monitor --session-id <session-id> --tail 100In multi-agent projects, add
--agent-name <service-name>tosessions listand pass the service name positionally tomonitor. Pass the same--user-identityused for invoke when header-based isolation is enabled.Choose the log stream. Use
--followfor live logs and--type systemfor container events:azd ai agent monitor --session-id <session-id> --follow azd ai agent monitor --session-id <session-id> --type systemInterpret the logs. Review
stdout,stderr, and system events. Highlight errors and warnings.
If no session exists, use azd ai agent invoke to trigger the Hosted Agent only when remote invocation is within the user's request.
Step 4: Discover Observability Connections
List the project connections to find Application Insights or Azure Monitor resources using the Azure CLI command documented at: az cognitiveservices account connection
Refer to the documentation above for the exact command syntax and parameters. Look for connections of type ApplicationInsights or AzureMonitor in the output.
If 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.
Step 5: Query Application Insights Telemetry
Use 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.
⚠️ Always pass
subscriptionexplicitly to Azure MCP tools likemonitor_resource_log_query— they don't extract it from resource IDs.
Use * contains "<response_id>" or * contains "<agent_name>" filters to narrow down results to the specific agent instance.
Step 6: Summarize Findings
Present a summary to the user including:
- Agent status — Hosted Agent version status when available
- Log errors — key errors from hosted-agent session logs
- Telemetry insights — exceptions, failed requests, latency trends
- Recommended actions — specific steps to resolve identified issues
Error Handling
| Error | Cause | Resolution |
|---|---|---|
| Agent not found | Invalid agent name or project endpoint | Verify the azure.yaml service name and run azd ai agent show |
| Hosted Agent not active | Hosted Agent is still provisioning or failed | Check deployment status, identity permissions, and system logs, then recheck status |
| Session logs unavailable | The session does not exist or has not been invoked | Run azd ai agent sessions list; invoke with azd when authorized, then retry monitor |
| No saved session ID | azd has not persisted an invoke session | Select one from azd ai agent sessions list and pass --session-id |
| No observability connection | Application Insights not configured for the project | Suggest configuring Application Insights for the Foundry project |
| Kusto query failed | Invalid cluster/database or insufficient permissions | Verify Application Insights resource details and reader permissions |
| No telemetry data | Agent not instrumented or too recent | Check if Application Insights SDK is configured; data may take a few minutes to appear |