Note
Access to this page requires authorization. You can try signing in or changing directories.
Access to this page requires authorization. You can try changing directories.
The Agent Debugger is a diagnostic tool that helps you load a recorded conversation and inspect each decision an agent made. For every conversation turn, you can review the execution path, step timing, token usage, knowledge sources, step arguments, and the orchestrator's reasoning.
Agent Debugger supports two data sources:
- Conversation Transcript (Dataverse): When a conversation runs in Copilot Studio, the platform records an activity log as a Conversation Transcript in Dataverse. Agent Debugger queries those records directly, so any published agent with transcript data is immediately available.
- Copilot Studio snapshot (ZIP): The Copilot Studio test panel includes a Download snapshot option that exports the current test conversation as a ZIP file. Uploading that file to Agent Debugger gives you the full analysis view without a Dataverse connection. This method is useful for debugging preproduction conversations, reproducing issues offline, or sharing a failing session with a colleague.
Both data sources feed the same analysis interface. The panels, step details, and visualizations are the same regardless of how the data is loaded.
Prerequisites
To use Agent Debugger, ensure the following prerequisites are met:
- The agent is present in Agent Inventory and has at least one conversation transcript recorded against it. You can verify this condition by opening the Agent Inventory list view, selecting the agent, and selecting Show more to expand the additional fields. The Is Transcript Available field must be set to Yes. The Agent Inventory sync automatically sets this field when at least one conversation transcript exists for the agent in Dataverse.
- The signed-in user has the CSK - Administrator or System Administrator security role in the kit environment.
- The signed-in user has Read access on the
conversationtranscripts,bot, andbotcomponentstables in the target environment.
Note
If the agent you're debugging is in a different environment from where the kit is installed, you must authenticate the Dataverse connection in the remote environment with the same read permissions.
Select a conversation
When you open Agent Debugger, the filter bar provides the controls you need to locate a conversation to analyze.
| Filter | Description |
|---|---|
| Environment | Populated from the distinct environment names found in Agent Inventory. Selecting an environment narrows the Agent dropdown to agents registered in that environment. |
| Agent | Shows agents in the selected environment whose Is Transcript Available field is set to Yes. Selecting an agent loads the 50 most recent conversations within the selected time range into the Conversation ID dropdown. |
| Conversation ID | Shows the 50 most recent unique conversations for the selected agent within the configured time range. Typing in the box triggers a full search across all transcripts for that agent (up to 100,000 records), so you can find older or specific conversations regardless of the time range. |
| Time range | Narrows the Conversation ID list to a specific window. Choose from Last 30 minutes, Last hour, Last 4 hours, Last 24 hours, Last 7 days, or Custom range. When you select Custom range, date and time pickers appear to set a start and end timestamp. |
| Error conversations only | Filters the Conversation ID dropdown to conversations that contain at least one failed step or system error. Use this option when triaging incidents or reviewing agents with known reliability problems. |
After you select a Conversation ID, Analyze becomes available. Select it to open the analysis view.
Note
Typing a Conversation ID directly always searches all transcripts regardless of the active time range. The Error conversations only filter scans transcript content on the client side and takes longer than the standard query. Leave it off unless you specifically need to filter by errors.
Upload a snapshot from Copilot Studio
The Upload Snapshot tab provides an alternative entry point that doesn't require Dataverse access. Instead of selecting a live conversation from the dropdowns, you upload a snapshot ZIP file downloaded from the Copilot Studio test pane.
To download a snapshot from Copilot Studio:
- Open your agent in Copilot Studio and go to the Test your agent panel.
- Run or review a conversation.
- Select Download snapshot in the test panel toolbar.
Copilot Studio downloads a .zip file that contains:
dialog.json: All Bot Framework activities for the conversation (required).botContent.yml: The agent's full component and flow definitions, used to resolve step names (optional; if absent, raw schema names are shown).
To upload a snapshot to Agent Debugger:
- Switch to the Upload Snapshot tab in the Agent Debugger header.
- Drag and drop the
.zipfile onto the drop zone, or select to browse for it.
Agent Debugger validates the ZIP, extracts the files, and opens the analysis view. No environment, agent, or conversation selection is required. All general information metrics are derived from the uploaded file.
Use Upload Snapshot mode when you need to:
- Debug a conversation that happened in the test pane before the agent was published.
- Analyze a conversation from an environment you can't authenticate against.
- Reproduce issues offline or share a failing session with a colleague without granting Dataverse access.
- Validate agent behavior in a local development environment.
Analyze a conversation
The analysis view opens after you select Analyze or upload a snapshot. It contains a General information summary row at the top, a collapsible analysis section with four panels (Execution path, Performance timeline, Agent details, and Recommendations), and a two-panel layout that shows the Conversation preview alongside the Debug information panel.
General information
The general information row shows summary metric tiles for the conversation.
| Field | Description |
|---|---|
| Sessions | Number of conversation sessions. Multiple sessions occur when a user returns to the same conversation after inactivity. |
| Turns | Number of user messages in the conversation. |
| Outcome | Session outcome reported by the platform, such as Resolved, Escalated, Abandoned, or SystemError. |
| Duration | Total conversation duration from first to last activity. |
| Start Time | When the conversation began (local time). |
| Channel | Communication channel used, such as webchat or msteams. Shown when available. |
| Model | The AI model used by the agent's orchestrator for this conversation. |
When a live agent is loaded, an Open agent link appears in the general information header. The link opens the agent's configuration page in Copilot Studio.
Execution path
The execution path renders the full execution order across all conversation turns as a directed flow diagram. Steps flow left to right in execution order. Dashed vertical lines mark turn boundaries, and each user message starts a new section. Turn labels appear at the top of each section. Selecting a turn label scrolls the Conversation preview to that message.
Each step type uses a distinct color, and a legend at the bottom of the diagram maps colors to step categories such as Topic, Knowledge, Tool, Connector, Flow, Code, MCP, and Connected Agent. Each node shows the step name and execution duration. Failed steps are highlighted in red. Connected agents appear as container boxes that group the child steps they executed.
Performance timeline
The performance timeline shows a waterfall chart of step execution times grouped by conversation turn. Step bars are scaled to the turn's total duration to make relative timing visible. Color coding matches the execution path legend, and failed steps appear in red.
The panel includes the following features:
- Expand/Collapse All buttons toggle all turn sections at once. Each turn section is also collapsible individually.
- Per-turn statistics show step count, slowest step name and duration, and failure count.
- A global summary at the top shows total steps, total elapsed time, the slowest step across the entire conversation, and total failure count.
- Steps slower than 10 seconds are flagged with a warning indicator.
Agent details
The agent details panel shows the full configuration of the agent as it existed at the time the conversation was analyzed. The information is organized into six tabs.
| Tab | Description |
|---|---|
| Overview | KPI tiles for Topics, Tools, Knowledge, Child Agents, Orchestration mode, Language, Auth Mode, Model Knowledge, Semantic Search, and Latest Models. Each tile includes a tooltip that explains the setting. |
| Instructions | The agent's full system prompt as configured in Copilot Studio. |
| Topics | All topics with name, description, input/output variables, and Enabled/Disabled status. |
| Tools | All tools with name, description, type badge (MCP, Flow, Connector, Prompt), and Enabled/Disabled status. |
| Knowledge | All knowledge sources with name, type badge (SharePoint, Web, Dataverse, File), URL, and Enabled/Disabled status. |
| Agents | All connected child agents with name, relationship type, and Enabled/Disabled status. |
Recommendations
The recommendations panel automatically detects issues in the conversation and surfaces them as actionable cards with severity ratings.
| Severity | Description |
|---|---|
| High | Likely caused a failed or incorrect response. Investigate immediately. |
| Medium | Degraded experience or reliability risk. Review soon. |
| Low | Minor inefficiency or informational note. |
The following issue types are detected:
| Issue | Severity | Description |
|---|---|---|
| Failed step or error | High | A step returned an error or exception. |
| Responsible AI block | High | Content was filtered by the Responsible AI system. |
| Conversation escalation | High | The conversation was handed off to a human agent. |
| Conversation abandonment | High | The user left without a resolution. |
| Fallback topic triggered | High | The agent failed to route the user's message to a topic. |
| Slow step (>10s) | Medium | A step took more than 10 seconds to execute. |
| Knowledge search failure | Medium | A knowledge source was queried but returned no results. |
| Token limit approached | Medium | Token usage came close to the model's context window limit. |
| Code step error | High | A Python code step raised an exception. |
| MCP initialization failure | High | An MCP server failed to initialize during the conversation. |
Each recommendation card shows the severity icon and color, a category badge, the title and description of the detected issue, a suggestion for how to investigate or resolve it, and a Go to turn button that scrolls the Conversation preview to the relevant user message. When no issues are detected, the panel shows an empty state message.
Conversation preview
The conversation preview panel shows the full conversation exchange as it appeared to the user, including bot and user message bubbles, Adaptive Cards rendered inline, suggested action chips, and feedback prompts.
Selecting a user message bubble loads that turn's steps into the Debug information panel. The selected message is highlighted so you can track which turn is active. The panel is independently scrollable. Selecting View JSON in the conversation preview header opens the full transcript JSON dialog.
Debug information
The debug information panel shows step-level details for the selected user message turn. The panel includes a step list on the left and a step detail view that opens when you select a step.
The step list shows every orchestrator step executed for the selected turn, with a step icon and color that indicate the step type, the step name (resolved to a friendly display name where possible), the execution duration, and a success or failure indicator. Steps that belong to a connected agent are grouped inside a collapsible container card that shows the agent name and total execution time. A Load connected agent details button on the container loads the child agent's full transcript on demand.
The following step types are supported:
| Type | Description |
|---|---|
| Topic | A named topic in the agent's topic list. |
| System Topic | A built-in platform topic, such as Greeting, Fallback, or Escalate. |
| Knowledge | A knowledge source search step. |
| Tool / Action | A Power Automate flow or connector action. |
| Code | A Python code execution step. |
| Custom Prompt | A custom generative AI prompt step. |
| Reasoner | An internal reasoning step used by the orchestrator. |
| MCP Server | A Model Context Protocol tool invocation. |
| Connected Agent | Delegation to a connected child agent. |
Selecting a step opens a detail panel with the following sections, shown when the data is present in the transcript:
- Thought process: The orchestrator's reasoning text recorded before the step was invoked. Shows how the model decided to call this step and what it expected from it.
- Step type: Classified label for the step.
- Arguments: A collapsible JSON tree view of the input parameters passed to the step. Includes a copy option to capture the JSON for support tickets.
- Observation: The output or return value from the step. Also displayed as a collapsible JSON tree with copy support.
- Code preview: For Python code steps, the source code is shown with syntax highlighting.
- Token usage: Prompt token count, completion token count, and total for the step, together with the model name used.
- Knowledge sources: Sources that were searched, results returned (output), and sources actually cited in the final response. Each entry shows the source name, type, URL where available, and a link to open the source.
- MCP server info: For MCP steps, shows the server's protocol version, declared capabilities, and the list of tools the server provided during initialization.
- Error information: When a step failed, shows the error code, error message, and (for Responsible AI blocks) the content safety category that triggered the filter.
- Adaptive Cards: When the step produced an Adaptive Card response, the card is rendered inline in the detail panel exactly as the user would have seen it.
Transcript JSON
When you select View JSON in the conversation preview header, a dialog opens that shows the full raw transcript activities with syntax highlighting, full-text search within the JSON tree, and a copy-to-clipboard option for the entire payload.
Use this view when:
- You need to inspect an event type that isn't surfaced in the Debug information panel.
- You want to copy specific fields for a support ticket.
- You're investigating unexpected behavior in the parsed views.
Troubleshooting
The following sections describe common issues and how to resolve them.
Agent doesn't appear in the Environment or Agent dropdown
The agent isn't synced to Agent Inventory, or it doesn't have any conversation transcripts.
To resolve this issue:
- Run a manual Agent Inventory sync for the environment.
- Verify the agent record exists in the Agent Details table in Dataverse.
- Check that the Is Transcript Available column is set to Yes on the record. The sync sets this field when at least one transcript exists.
For more information, see Monitor agents using Agent Inventory in Copilot Agent Kit.
Conversation ID isn't found in the dropdown
For performance, the dropdown preloads only the 50 most recent conversations within the active time range. Older transcripts still exist in Dataverse but don't appear by default. Alternatively, the transcript might not be written yet if the conversation just ended.
To resolve this issue:
- Type the conversation ID directly into the Conversation ID field. Typing triggers a full search across all transcripts for that agent, ignoring the time range.
- If the time range is narrow (for example, Last 30 minutes), expand it or switch to a custom range that covers the conversation date.
- If the conversation just ended, wait 35-40 minutes for the transcript to be written to Dataverse, then refresh.
Analyze loads but no steps appear in the Debug information panel
The transcript exists but contains only message-type activities with no diagnostic trace events. This issue typically happens when the conversation came from a channel that doesn't emit trace data, such as certain custom channels or older schema versions.
To resolve this issue:
- Select View JSON in the conversation preview header to confirm activities are present.
- Look for
type: "trace"ortype: "event"entries. If they're absent, the channel might not emit trace data.
Access denied or blank page on load
Roles or permissions are missing in one or both environments.
To resolve this issue:
- In the kit environment, make sure the user has the CSK - Administrator or System Administrator role.
- In the target environment, make sure the signed-in user has read access to the
conversationtranscripts,bot, andbotcomponentstables.
Transcripts appear incomplete (missing early messages)
Long conversations are split across multiple Dataverse records (1 MB limit per record). If the retention policy purges some records, the merged transcript has gaps.
To resolve this issue:
- Dataverse purges conversation transcripts older than 30 days by default. If retention is the issue, update the bulk delete job schedule in Power Apps > Settings > Advanced settings > Data Management > Bulk Record Deletion.
- If retention isn't the cause, verify that all transcript records for the conversation exist in the
conversationtranscriptstable in Dataverse.
Steps show raw schema names instead of readable topic names
The botcomponents table lookup failed, or the component record was deleted.
To resolve this issue:
- Verify the signed-in user has read access to the
botcomponentstable in the target environment. - If the component was deleted from Copilot Studio, no matching record exists and Agent Debugger falls back to the raw schema name, such as
cr123_mytopic. This behavior is expected for deleted topics or actions.
Agent details panel shows no data
The agent configuration fetch failed, or the signed-in user's connection doesn't have read access to the bot and botcomponents tables in the target environment.
To resolve this issue:
- Verify read access to the
botandbotcomponentstables for the connection reference used by the app. - If the agent was deleted or unpublished after the conversation was recorded, its configuration records might no longer exist. In this case, the Agent details panel remains empty, but the transcript and debug panels are still fully functional.
Recommendations panel shows no issues but the conversation failed
Recommendations come from patterns in the transcript trace events. If the transcript lacks trace data, or if the failure occurs outside the conversation (for example, a silent network timeout that the transcript doesn't record), the system doesn't generate any recommendations.
To resolve this issue:
- Open the transcript JSON to look for raw error payloads that aren't surfaced as a recommendation.
- Check the execution path for any steps shown in red. These steps indicate failures that don't map to a known recommendation pattern.