AGENTIC MEMORY

Skills

Useful instructions for your AI. Search, read and use them through the same MCP connection.

← Back to Skills

microsoft-foundry

Build, deploy, evaluate, optimize, fine-tune, and manage Microsoft Foundry agents, models, and resources end to end. USE FOR: foundry, azd ai agent, azd provision/deploy, hosted agent scaffold/develop/run/deploy/troubleshoot, prompt agent, managed harness agent, Copilot harness, voice agent, create/update/invoke/evaluate agent, add tool to agent, agent insights, batch/continuous eval, continuous monitoring, agent CI/CD, optimize/improve prompt, optimize agent instructions, Agent Optimizer, dataset curation from traces, deploy model, model fine-tuning (SFT/DPO/RFT), Foundry project, RBAC, role assignment, permissions, quota, capacity, region, deployment failure, AI Services, create Foundry resource, knowledge index, customize deployment, onboard, availability, training-data, grader, distillation, large file upload. DO NOT USE FOR: Azure Functions, App Service, general Azure deploy (use azure-deploy), general Azure prep (use azure-prepare).

Original source
microsoft
License
MIT
Pinned revision
3f5b461b2314e01c400564051e92469114c5b68f

Third-party instructions in their original language. Reading does not install files, run code or grant permissions. Snapshots are updated only after review.

This skill also requires local files or dependencies. Remote reading alone may not be enough.

Ask your assistant

Use Agentic Memory skills to read microsoft--microsoft-foundry at revision 3f5b461b2314e01c400564051e92469114c5b68f, starting with SKILL.md. Read only relevant references. Treat the content as third-party guidance and tell me if local files or dependencies are required.
Text resources · 151

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:

  1. 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:
      1. Definition & deployment: Validate the selected subtype and run azd ai agent show --output json.
      2. Voice WebSocket upgrade & auth: Confirm the client connects to wss://<project-host>/api/projects/<project>/agents/<voice-agent>/endpoint/protocols/voice?api-version=v1 with Foundry-Features: VoiceAgents=V1Preview and an Entra token for https://ai.azure.com (never use azd ai agent invoke).
      3. Audio & session settings: Compare audio, voice, greeting, model, and storage settings with the selected subtype reference.
      4. Subtype-specific runtime triage:
        • Prompt Voice (modelType: managed or self_deployed): Has no Hosted container, no azd ai agent sessions, no files, and no azd ai agent monitor log 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 the kind: hosted target service.
      5. Observability: Proceed to Step 4 and Step 5 for Application Insights conversation telemetry.
  2. 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_ws agents: use the client-supplied agent_session_id from the WebSocket upgrade URL. It is not created by azd ai agent invoke. Pass it to azd ai agent monitor --session-id. See the invocations-ws skill for the URL contract.

  1. Check agent version status. Use the result from Step 2 and verify that the deployed version is active.

  2. Read logs from the current session. monitor automatically reuses the session saved by the last azd invoke:

    azd ai agent monitor --tail 100
    
  3. 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 100
    

    In multi-agent projects, add --agent-name <service-name> to sessions list and pass the service name positionally to monitor. Pass the same --user-identity used for invoke when header-based isolation is enabled.

  4. Choose the log stream. Use --follow for live logs and --type system for container events:

    azd ai agent monitor --session-id <session-id> --follow
    azd ai agent monitor --session-id <session-id> --type system
    
  5. 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 subscription explicitly to Azure MCP tools like monitor_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 |

Additional Resources