Copilot Chat: Debug Declarative Agents

Key insights

• Demo overview: A community demo by Sébastien Levert shows how to test and debug Microsoft 365 Copilot declarative agents using practical examples.
  It focuses on developer tools, diagnostics, and common troubleshooting steps.
• Developer Mode: Turn on developer mode with the -developer on command to get diagnostic output from Copilot during tests.
  Send prompts while enabled and turn it off with -developer off when finished.
• Debug Card: The debug card reveals what the agent used at runtime, including agent metadata, selected capabilities, matched functions, and executed actions.
  Use it to see why the agent chose a specific knowledge source or action.
• Agents Toolkit (VS Code) and Preview your app (F5): Start local testing with the Agents Toolkit in Visual Studio Code and use Preview your app (F5) to open a browser-based Copilot Chat session.
  Check the toolkit’s Debug panel to confirm a successful connection and to inspect richer diagnostics.
• Benefits: Testing in developer mode gives faster troubleshooting and clearer tuning of prompts, manifests, and action metadata.
  It also lets you validate behavior in the same Copilot Chat experience your users will see.
• Common issues and tips: Watch for unclear action or parameter descriptions, invalid host URLs, and OpenAPI definition errors; repeated failures often point to these problems.
  Also optimize message extensions for quick responses and use the debug output to refine function descriptions and parameters.

Microsoft 365 published a clear demonstration video that walks developers through testing and debugging a Copilot Chat declarative agent. The demo, presented by Sébastien Levert during the Microsoft 365 & Power Platform Community call on April 14, focuses on practical diagnostics and local development workflows. Consequently, it serves as a concise primer for teams building extensible agents for enterprise environments.

What the demo covers

First, the presenter shows how to enable Developer Mode and inspect the returned Debug card to see which knowledge sources, capabilities, and actions the orchestrator chose. Then, the walkthrough highlights the integration of the Agents Toolkit into Visual Studio Code, including the use of the Preview your app (F5) flow and the toolkit’s Debug panel for richer diagnostics. In addition, the talk addresses app versioning, environment files, sharing options, and practical troubleshooting for APIs and servers.

Moreover, the demo touches on harder-to-find issues such as grounding problems, instruction tuning, and problems returned by MCP servers. The presenter also points out how debug output surfaces mismatches in action selection, parameter parsing, and OpenAPI definitions. As a result, developers can see concrete examples of why an agent chose one route over another.

What’s new and why it matters

Importantly, Microsoft’s newer debugging experience provides a more structured view of runtime behavior instead of only showing pass/fail outcomes. The updated debug information includes agent metadata, matched and selected functions, executed capabilities, and detailed execution steps to help teams diagnose root causes faster. Therefore, development teams gain clearer visibility into how logic and enterprise data interact during a session.

However, this added detail comes with tradeoffs: while more data helps diagnose problems, it can also introduce noise and increase the effort needed to interpret results. Furthermore, teams must weigh the benefits of verbose diagnostics against privacy concerns when runtime traces include enterprise content. Consequently, sensible defaults and role-based access to debug output remain important considerations.

How to test and validate agents

To test locally, the recommended flow is straightforward: open the agent in Copilot Chat or launch it from the Agents Toolkit in Visual Studio Code, enable developer mode by sending -developer on, then run test prompts and review the debug card. If you run the agent from VS Code, use F5 to launch and confirm the browser connection in the toolkit’s Debug panel before deeper troubleshooting. After tests, turn off developer mode with -developer off to return to normal operation.

In addition, the demo emphasizes checking for common failure signals, such as missing debug cards when the orchestrator did not need enterprise data, and explicit errors in action selection or parameter mapping. Developers are also encouraged to simulate user prompts that exercise knowledge sources, skills, and actions to see how the orchestrator prioritizes them. Meanwhile, practical limits like recommended response time targets—especially for message extension plugins—remain important to meet user expectations.

Tradeoffs and engineering challenges

Balancing depth of diagnostics against usability is a recurring challenge for teams. On one hand, detailed traces make it easier to tune prompt templates, action descriptions, and manifests; on the other hand, too much diagnostic detail can overwhelm reviewers and obscure patterns. Therefore, teams should create focused test suites and logging filters that prioritize actionable events and failure modes.

Another key challenge lies in reproducing issues across environments. Local testing simplifies iteration, yet differences between development and production—such as environment variables, host URLs, or API behavior—can cause problems to appear only in deployment. As a result, versioning, environment files, and consistent manifests help reduce surprises and make fixes more reproducible when scaling up.

Practical tips and next steps

Start tests by ensuring the browser session connects successfully and that the debug card appears for meaningful prompts, because these two checks catch many basic problems early. Then, focus on whether the right action or function was selected; if it was not, refine your action and parameter descriptions, adjust manifest metadata, or improve grounding to guide the orchestrator. In addition, pay attention to OpenAPI definitions and host URLs, since repeated failures often point to schema or connectivity issues.

Finally, monitor latency and user-facing performance while you tune capabilities, because faster responses may require changes to how the agent selects data or calls services. In conclusion, the Microsoft demo provides a practical roadmap for developers to test, debug, and refine declarative agents, while also highlighting the tradeoffs between observability, privacy, and production fidelity. Editors and engineering leads should view this guidance as a useful playbook for improving agent reliability before broad rollout.

Keywords

Copilot Chat declarative agent testing, debugging Copilot Chat agents, Copilot declarative agent debugging, test Copilot Chat agents best practices, troubleshooting declarative agents Copilot, Copilot Chat testing tools, automated tests for Copilot agents, end-to-end testing Copilot Chat