foundry-agent/troubleshoot/troubleshoot.md
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 the Agent Type (Hosted, Voice, Managed Harness Agent, or Prompt)
Inspect azure.yaml (host: azure.ai.agent) and classify the service in order:
- Voice Agent (apply the top-level compatibility classification for legacy manifests):
- Read common Voice invariants and the selected subtype reference from create-voice.
- Triage in this exact order:
- Definition & deployment: Validate the selected subtype and run
azd ai agent show --output json. - Voice WebSocket upgrade & auth: Confirm the client connects to
wss://<project-host>/api/projects/<project>/agents/<voice-agent>/endpoint/protocols/voice?api-version=v1withFoundry-Features: VoiceAgents=V1Previewand an Entra token forhttps://ai.azure.com(never useazd ai agent invoke). - Audio & session settings: Compare audio, voice, greeting, model, and storage settings with the selected subtype reference.
- Subtype-specific runtime triage:
- Prompt Voice (
modelType: managedorself_deployed): Has no Hosted container, noazd ai agent sessions, nofiles, and noazd ai agent monitorlog stream. Skip Step 3 and proceed to Step 4 (Application Insights telemetry). - Hosted Voice (
conversationEngine.type: hosted_agent): Separate wrapper configuration/endpoint failures from target Bridge, startup, model, and RBAC failures. Use Hosted Voice Bridge troubleshooting, then inspect logs on thekind: hostedtarget service.
- Prompt Voice (
- Observability: Proceed to Step 4 and Step 5 for Application Insights conversation telemetry.
- Definition & deployment: Validate the selected subtype and run
kind: hosted(Hosted Agent or Hosted Voice target): Run:
azd ai agent show --output json
If 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.
3. kind: prompt (Managed Harness Agent or ordinary Prompt Agent): Has no Hosted container session logs; skip Step 3 and proceed to Step 4.
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 100 -
Select 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 system -
Interpret 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 |
| session.rejected (protocol_mismatch) on Hosted Voice startup | Hosted target does not satisfy the selected Bridge contract | Follow Hosted Voice Bridge troubleshooting, redeploy the target, and retest |
| azd ai agent invoke fails on Voice Agent | azd ai agent invoke does not support the Voice protocol | Use the Voice WebSocket smoke-test script (smoke-test-voice.sh / smoke-test-voice.ps1) or Foundry Voice playground |