Debug chat interactions

When an agent behaves unexpectedly, inspect the evidence from the affected chat session before changing your prompt or configuration. This article helps you select a diagnostic view, trace what happened, and verify whether a change resolves the issue.

Choose a diagnostic tool

VS Code provides complementary tools for different questions:

For account, connectivity, or feature-availability problems, start with Troubleshoot AI in VS Code instead.

Before you start

Prepare logging before you reproduce the issue:

• For local chat sessions in the main VS Code window, enable the experimental github.copilot.chat.agentDebugLog.fileLogging.enabled Open in VS Code Open in VS Code Insiders setting and reload the window before you use /troubleshoot.
• For sessions that run on the Agent Host, enable the experimental chat.agentHost.agentDebugLog.enabled Open in VS Code Open in VS Code Insiders setting before the activity that you want to inspect.
• Reproduce the issue and note the affected session. Capture is not retroactive.

Investigate common scenarios

The AI ignores workspace files

If the response is generic or does not use the expected code:

1. Open the Chat Debug view and inspect the Context section for the affected request.
2. If a file is absent, confirm that you opened the correct workspace and that workspace indexing is available.
3. Add the relevant file or code as explicit chat context, and then repeat the request.
4. Reopen the Chat Debug view and verify that the expected context is present.

An MCP tool is not being invoked

If the model does not call an expected tool:

1. Run MCP: List Servers from the Command Palette and verify that the server is running.
2. Open the Chat Debug view and check whether the tool appears in the available tool definitions.
3. If the tool is absent, troubleshoot the MCP server.
4. If the tool is available, check the Agent Debug Logs for tool calls and errors.
5. State the tool name and the action it should perform in your prompt, and then repeat the request.

The AI response is incomplete

If a response stops early or omits part of the task:

1. Check the Agent Debug Logs for model request errors and token usage.
2. Check the Response and Tool responses sections in the Chat Debug view to determine whether the model response or a tool result is incomplete.
3. If the conversation contains unrelated or outdated context, use /compact or start a new session and repeat the request.
4. If the logs show an error, include that error when you report the issue.

Instructions or a prompt file are not applied

Custom instructions and prompt files enter a request in different ways:

1. Open the chat customization diagnostics view to check whether an instructions file was discovered and whether it has errors.
2. For a *.instructions.md file, verify that its applyTo pattern matches the file you are working on.
3. For a prompt file, verify that you invoked it manually. Agents that run on the Agent Host do not use prompt files. For details, see Use prompt files.
4. Check Discovery events in the Agent Debug Logs to see whether a customization was loaded, skipped, or rejected.
5. In the Chat Debug view, inspect the System prompt for custom instructions and the User prompt for an invoked prompt file.
6. Correct the discovery or applicability issue, repeat the request, and verify the corresponding prompt content again.

Agent Debug Logs panel

The Agent Debug Logs panel shows a chronological record and aggregate metrics for chat sessions. It also provides a flow chart for agent orchestration and access to the Cache Explorer.

Open the panel in either of these ways:

• Select the ellipsis (...) menu in the Chat view, and then select Show Agent Debug Logs.
• Run Developer: Open Agent Debug Logs from the Command Palette.

The panel includes current and historical sessions. Persisted logs are stored locally.

Logs view

The Logs view lists session events with their timestamp, type, and summary. Expand an event to inspect details such as the system prompt for a model request or the input and output for a tool call.

Switch between a flat list and a tree grouped by subagent. Use the filters to focus on events such as model requests, tool calls, discovery, or errors.

Summary view

The Summary view reports aggregate information such as tool calls, token usage, errors, and total duration. Use these metrics to identify which part of a session needs deeper investigation.

To open the Summary view:

1. Open the Agent Debug Logs panel for the affected session.
2. Select the session description in the breadcrumb at the top of the panel.

From the Summary view, select View Logs, Agent Flow Chart, or Cache Explorer to open the corresponding view.

Agent flow chart view

The Agent flow chart view visualizes the sequence of interactions between agents and subagents. Use it to identify which agent delegated an action and where a workflow stopped.

To open the flow chart:

1. Open the Summary view for the affected session.
2. Select Agent Flow Chart.
3. Pan or zoom the chart, and select a node to inspect that event.

Cache Explorer view

The Cache Explorer compares consecutive model requests and marks their first divergence. Use it only after the Summary view reports low cache reuse together with unexpected duration or input token usage.

For interpretation and verification steps, see Diagnose prompt caching with the Cache Explorer.

Analyze debug events with chat

Attach a snapshot of the current session events to chat when you want the AI to answer a focused question about token usage, loaded customizations, tool calls, errors, or duration.

1. Open the Logs view for the affected session.
2. Select the sparkle icon in the upper-right corner of the Agent Debug Logs panel.
3. Ask a focused question about the attached events.

Alternatively, enter /troubleshoot followed by a question. For example:

/troubleshoot Which customizations were loaded, and did any fail?

For a session in the Agents window, enter /troubleshoot #session, select the local or remote session, and then add your question.

Export and import sessions

Export a session to an OpenTelemetry JSON file in OTLP format when you need to retain the evidence or analyze it with another supported tool.

To export a session:

1. Open the Agent Debug Logs panel and select the session.
2. Select the Export icon in the upper-right toolbar.
3. Choose a location for the JSON file.
4. Review the exported content before sharing it.

To inspect a previously exported session:

1. Select the Import icon in the upper-right toolbar.
2. Select an exported Agent Debug Log JSON file.
3. Use the Summary and Logs views to inspect the imported session.

Chat Debug view

The Chat Debug view shows the request and response details for each model interaction. Use it to verify which instructions, context, messages, and tool definitions reached the model.

Open the Chat Debug view

Open the view in either of these ways:

• Select the overflow menu in the Chat view, and then select Show Chat Debug View.
• Run Developer: Show Chat Debug View from the Command Palette.

Read the debug output

Each interaction contains expandable sections:

Verify the diagnosis

After you identify a likely cause:

1. Change one relevant condition, such as a file pattern, server configuration, context attachment, or tool selection.
2. Repeat a comparable request.
3. Inspect the same event or request section.
4. Confirm that both the diagnostic evidence and the user-visible result changed as expected.

If the evidence does not change, restore the previous configuration and investigate the next likely cause.

Related resources

• Troubleshoot AI in VS Code
• Add context to chat
• Security considerations for using AI