How to Build a Custom Chat Experience in Power Pages Using the New Agent API

Howdy everyone, so Microsoft just dropped something pretty cool for Power Pages and I wanted to write about it as soon as I got my hands on it. The new Agent API basically lets you ditch the default chatbot widget and build your own fully custom chat interface that connects to your Copilot Studio agents. If you have been frustraited by the limitations of the out-of-the-box chat widget (like I have been for a while now), this one is for you.

I’ve been waiting for something like this honestly. The default widget works fine for basic stuff, but if you wanted to match your sites branding or do anything beyond a floating bubble in the corner, you were pretty much stuck. Not anymore.

Why Should You Care About the Agent API?

Before we dive into the how-to part, let me explain why this matters. I’ll give you a few scenarios that I think make this feature really worth looking into:

Full control over the look and feel: The default chatbot widget is fine, but lets be real, it looks the same on every Power Pages site. With the Agent API you can design your own chat UI with your own colors, fonts, layout, everything. It actually feels like part of your site instead of something that was just slapped on top.

Context-aware conversations: This is the big one for me. The Agent API lets you pass information about what page the user is currently on, what form they’re looking at, even what data they’ve entered so far. The agent can then use all of that context to give way better answers. Imagine someone is halfway through filling a support request form and they ask the agent for help, the agent actually knows what form they’re on and can assist accordingly.

Its not just for chat: This is something alot of people miss. The Agent API isn’t limited to building chat bubbles. You can use it to power all kinds of intelligent features on your site. Content summarization, form assistance, task execution, and more. Basically anywhere you want an agent to do something smart on your page, this API can help.

Prerequisites

Before you start, make sure you have the following ready. Trust me, its better to check these first than to get halfway through and realize something is missing.

Copilot Studio capacity: Your environment needs Copilot Studio capacity. The agents created from Power Pages initially start as trial agents, but after the trial period ends they will consume your available Copilot Studio capacity. So if your on a pay-as-you-go model or have M365 Copilot licenses, double check that everything is setup.

Power Pages site on Enhanced Data Model: The Agent API works with sites running the enhanced data model. If your still on the standard data model, you’ll need to migrate first. This is something Microsoft has been pushing for a while now so hopefully most of you are already there.

Tenant admin settings: The tenant admin needs to have the “Publish Copilots with AI features” setting turned on in the Power Platform admin center. Also make sure the HTTP connector is not blocked in your environment because agents created from Power Pages use the HTTP node to communicate with the site.

Permissions: You’ll need maker or admin access to the Power Pages design studio and also access to Copilot Studio if you want to customize the agent further.

Web roles configured: You need to have your web roles setup because the Agent API respects role-based access. You control which users can interact with which agents through web roles, same as you would control access to any other content on your site.

Step-by-Step: Setting Up the Agent

Alright lets get into it. First we need to make sure we have an agent provisioned on our Power Pages site.

Step 1: Enable a Site Agent

1. Sign in to Power Pages and open your site for editing.
2. Go to the Set up workspace and then select Agents.
3. Enable the Site agent by using the toggle switch. This creates the agent automatically.
4. After provisioning is done, Power Pages adds a new agent with your site name appended with “bot.” You’ll see it appear in the Agents section.
5. Select the three vertical dots next to the newly provisioned agent, and then select Edit.
6. Keep the Show in Chat Widget toggle set to On for now (we will hide the default widget later with CSS).
7. Select the web roles for users who should be able to interact with the agent. For testing, you can start with the Administrators role.
8. Copy the schema name — you will need this later when writing the custom code.

This is the important part that people forget. That schema name is what connects your custom UI to the right agent. Save it somewhere you wont lose it.

Step 2: Create the Page for Your Custom Chat

Now you need a page where your custom chat interface will live. You can put it on an existing page or create a new one, its up to you.

1. In the Power Pages design studio, go to Pages.
2. Create a new page or navigate to the page where you want the custom chat to appear.
3. Add a section to the page where you’ll place the custom chat component.

For this tutorial, I created a page called “Virtual Assistant” just to keep things clean and seperate from the rest of the site.

Step 3: Write the Custom Chat Code

Here’s where the fun begins. You’ll need to use the Visual Studio Code for the Web editor that’s built into Power Pages.

1. Open the Code Editor from the Power Pages design studio (you can find it in the toolbar area).
2. Navigate to the web template for the page you just created.
3. You’re going to write HTML, CSS, and JavaScript to build your chat interface.

The key piece of the puzzle is the $pages.agent client API. This is the object that lets you send messages to the agent and recieve responses back. The main method you’ll use is $pages.agent.SendActivity which sends a message from the user to the agent.

Here’s roughly how the flow works in your JavaScript:

• You create your chat UI elements (a text input, a send button, a message container).
• When the user types a message and clicks send, you call $pages.agent.SendActivity with the message text.
• The agent processes the message and returns a response.
• You display the response in your chat container.

The important thing to rememebr is that you need to wait for the $pages client API to be ready before you try to use it. If you try to call $pages.agent.SendActivity before the API is loaded, it wont work and you’ll get errors in the console.

Step 4: Hide the Default Chat Widget

Since we’re building our own chat interface, we dont want the default floating bot widget showing up on the same page. That would be confusing for users to have two chat experiences on one page.

To hide it, add the following CSS to your page’s header template:

/* Hide the default floating bot widget */
.pva-floating-style {
    display: none !important;
}

This CSS rule targets the default widget’s container class and hides it. Simple but effective.

Step 5: Configure the Agent Schema

In your custom JavaScript code, you need to set the agent schema name to the one you copied earlier in Step 1. This is what tells the Agent API which specific agent your custom chat should connect to.

You’ll have a variable in your code something like:

const AGENT_SCHEMA = "your_agent_schema_name_here";

Replace that placeholder with the actual schema name from your agent configuration. Save the file in the VS Code editor.

Step 6: Sync and Preview

1. Go back to the Power Pages designer.
2. In the dialog that says “You’re editing code in Visual Studio Code for the Web”, follow the instructions and click the Sync button to push your changes.
3. Click Preview and choose Desktop.
4. Sign in with a user account that has been assigned the web role you configured earlier.
5. Navigate to the page where you placed your custom chat.
6. Test it out! Type a message and see if the agent responds.

If everything is wired up correctly, you should see your custom chat interface talking to the Copilot Studio agent, but now it looks exactly how you designed it.

Going Beyond Basic Chat

Ok so here’s where it gets really interesting and what makes the Agent API different from just embedding the regular widget.

Passing Page Context to the Agent

You can use the $pages client API to detect what page the user is on, what form they’re interacting with, and even what data is currently on the screen. When you send a message to the agent, you can package this contextual metadata alongside the user’s question.

This means the agent doesn’t just answer generic questions anymore. It can say things like “I see you’re on the Event Registration form, would you like help completing the remaining fields?” This is a massive improvment over the old approach where the agent had no idea what the user was actually looking at.

Using the Agent for Form Assistance

One of the most practical use cases I’ve seen is combining the Agent API with the “create agent from form” feature. You can have an agent that understands the data model behind a form and can help users fill it out through a conversational interface. The agent can even parse uploaded documents like PDFs and suggest values for form fields.

Think about a scenario where a user needs to submit a detailed application form. Instead of staring at 20 empty fields, they can upload their CV or a document, and the agent extracts the relevant information and pre-fills the form. Thats a huge user experience win.

Inline Summarization

Another cool pattern is adding a “summarize” button next to long knowledge articles or content-heavy pages. When clicked, it sends the current page content to the agent through the Agent API, and the agent returns a short summary displayed in a card or popup. No need for users to read through pages of documentation when they just need the key points.

Things to Watch Out For

A few things I noticed during my testing that are worth mentioning:

Authentication setup can be tricky. If your site uses authenticated access with Microsoft Entra ID, there are some additional configuration steps for setting up app registrations and token exchange between the agent and the site. Make sure to follow the documentation on Entra ID configuration for agent authentication closely.

Quotas and limits. Remember that the agent uses Copilot Studio generative answers, and there are quotas and limits on how many messages can be processed. If your site has alot of traffic, keep an eye on your consumption in the Power Platform admin center.

Web API table access. If your agent needs to read or write data to Dataverse tables, you need to explicitly enable Web API access for those tables and columns. This is a security feature, not a bug. Only expose the tables and columns that the agent actually needs.

Testing with different web roles. Always test your custom chat with both authenticated and anonymous users (if you support anonymous access). The agent should respect the table permissions and web roles you’ve configured, but its always good to verify.

Common Issues

If your custom chat isn’t working, here are some things to check:

Make sure the $pages client API is loaded before you try to call any agent methods. Check the browser console for errors, usually it will tell you if the API isnt ready yet.

Verify that the schema name is correct and matches the agent you provisioned. A typo here will mean your chat connects to nothing.

Check that the web role assigned to the agent matches the role of the user your testing with. If the roles don’t match, the agent wont respond.

Make sure you clicked Sync in the Power Pages designer after making code changes. I’ve forgotten this step more than once and sat there wondering why nothing was updating on the live site.

Clear the server-side cache if needed by navigating to <YourPortalURL>/_services/about and clicking Clear cache.

Final Thoughts

The Agent API is honestly one of the more exciting updates to Power Pages in a while. It bridges the gap between the low-code ease of Power Pages and the kind of custom, branded experiences that pro developers want to build. The fact that you can pass page context to the agent and get truly relevant responses is a game changer for self-service portals.

I think this feature is still in its early days and Microsoft will keep expanding it, but even right now it opens up alot of possibilities. If you’ve been doing the standard chatbot widget approach, I’d really encourage you to give this a try. The difference in user experience is noticable.

Good luck, and feel free to drop a comment if you run into any issues or have questions!