Lately I’ve been testing some of the X++ features we can use to extend the Finance and Operations agent in Copilot Studio.

One of these features is the X++ AI tools (formerly called AI plugins), which allow us to create Copilot Studio tools that call X++ business logic.

Today’s post is a product of my lack of focus and my superpower of ignoring yellow notifications on PPAC. Also, thanks to Jared Hall for the hint about using Postman to troubleshoot Copilot Studio errors.

If you missed any of the first three posts in the series, you can read them now:

• Part 1: Copilot Studio 101: Extend Dynamics 365 F&O Copilots.
• Part 2: Build an X++ AI Tool for Copilot Studio in Dynamics 365 F&O.
• Part 3: Create X++ Client Plugins for Copilot Studio in Dynamics 365 F&O.

Context and scenario

First, let me give a bit of context and clarify a bit how all of this works at a high level, and also which was my scenario.

I’m preparing a session about extending the F&O Copilot with X++ and Copilot Studio. For my demo, I created an X++ AI tool that runs some business logic in X++. Something simple to show how it’s done.

Once we have the X++ AI tool, we deploy it to the environment, which creates a Dataverse custom API/Action (I’ll never stop being amazed at how much Microsoft loves name changes). This is the action that Copilot Studio uses to call the X++ logic.

I wasn’t able to troubleshoot the issue, neither debugging X++ nor debugging Copilot Studio (with messages), because that’s not an option if you don’t have the generative AI orchestration enabled.

How to troubleshoot Copilot Studio errors

When I tested it with my SysAdmin user, everything was OK. But I also wanted to test it with a user whose role only provided access to the X++ AI tool’s data.

And when I tested it, I got this error:

Sorry, the bot can't talk for a while. It's something the bot's owner needs to address. Error code: AIPluginRequestFailure.

It’s not very descriptive, right? I tested with F&O and Dataverse permissions, and I found that if I gave the user the System Administrator role in Dataverse, the agent worked. It had to be a Dataverse thing!

After much investigating and asking, Jared suggested calling the action via the Dataverse API to troubleshoot Copilot Studio, using Insomnia to see if I got any details. I used Postman because I’m more familiar with it, and I got this:

I had put the environment in Admin mode from PPAC to enable a configuration key in F&O and forgot to disable it.

Thanks to the better details I got from the API call, I could troubleshoot the Copilot Studio error! Let’s learn how to do this.

Calling X++ AI Tools in the Dataverse Web API with Postman

Calling the Dataverse Web API is similar to calling OData endpoints in F&O. First, you authenticate and get a token, and with that token you can call the endpoints.

I’ll show this in Postman, but you can use any tool of your choice.

Create an environment

This step is optional; you can create a request to get the token using an AppId and secret, but I’ll show something interesting that I’ve learned from the Web API docs that show how to do this with Insomnia.

Go to the Environments tab and create a new entry for your Dataverse environment. Add these variables:

Variable name	Value
url	https://YOUR_ENV.crmX.dynamics.com/
clientId	51f81489-12ee-4a9e-aaae-a2591f45987d
version	9.2
webapiurl	{{url}}/api/data/v{{version}}/
callback	https://localhost
authurl	https://login.microsoftonline.com/common/oauth2/authorize?resource={{url}}

Notice that the clientId is fixed? Am I just publishing one of my Entra ID App registrations here? Nope! This clientId is Microsoft’s and is used for OAuth authentication.

Once you have these variables configured, set the environment as active by clicking the checkbox on the right:

Calling the Dataverse API in Postman

Now, create a new request and go to the Authorization tab. In Auth Type, select OAuth 2.0 and give your token a name.

Scroll down until you see the Configure New Token section. In Callback URL, enter the {{callback}} variable from your environment. In Auth URL, enter {{authurl}}. And in Client ID {{clientId}}.

It should look like this:

Then scroll to the bottom until you see the Get New Access Token button and click it. A Microsoft sign-in window will open. Log in with your user:

A new dialog with your token will appear; click the Use Token button:

Now we’re ready to finalize the request!

Your X++ AI tool endpoint

So now we need to know what the endpoint name of your X++ AI tool is. That’s easy!

It’s your AI tool’s X++ class name preceded by mserp_! For example, if your class is called AASFabulousCopilotToolCustomAPI, your endpoint will be mserp_AASFabulousCopilotToolCustomAPI.

So in the URL you will be {{webapiurl}}/mserp_AASFabulousCopilotToolCustomAPI and the request must be a POST action.

Now, your X++ AI tool probably has some input parameters, which are data members in the class. For example, my fabulous tool has two: companyId and custAccount. You have to pass these as a JSON. What are the expected names?

Again, it’s easy; just add mserp_AASFabulousCopilotToolCustomAPI_ in front of the member names! So for companyId, it’ll be mserp_AASFabulousCopilotToolCustomAPI_companyId, and for custAccount, mserp_AASFabulousCopilotToolCustomAPI_custAccount.

You should have something like this:

Click the Send button, and your API will be called, and you should see the output.

And done! Now you can also launch the debugger and test your code, making the requests from Postman.

Conclusion

And that’s it! With these simple steps, you can troubleshoot Copilot Studio errors and test your X++ changes for Copilot Studio using Postman or any other API client of your choice!

Remember, when finding vague errors in the Copilot sidecar chat, the Dataverse Web API may provide better details and help you solve the exact issue quickly. Like finding out your environment was accidentally left in Admin mode! 🥴

So next time your bot decides to be mysteriously cryptic, don’t panic; open Postman, troubleshoot Copilot Studio errors, and relax!

Happy troubleshooting, and keep ignoring those yellow notifications at your own risk!