Deploy an agent to the demo website and a web app

  • 7 minutes

Websites put an agent in front of two audiences: testers who review it before rollout, and the employees or customers who use it on a site your organization runs. In this unit, you learn how to publish an agent to the Copilot Studio demo website for tester review, add it to a custom web app, and protect web channel access with Direct Line secrets and tokens.

Share the demo website with testers

The demo website is a prebuilt website for testing and demonstrating your agent. It fills a different role from the test chat you use while you build:

  • Preview pane: Lets you test the draft as you build it.
  • Demo website: Lets teammates and stakeholders try the published agent and give feedback before you roll it out to its users.

Because testers reach the published version, the demo website shows them what users get, not your latest draft. Depending on who you want to reach the demo website, you might need to change the agent's authentication option before you publish to it.

To publish the agent to the demo website:

  1. With the agent open, select the chevron next to Publish.
  2. In the Publish agent dialog, select Demo website in the list of available channels, and then publish the agent.
  3. When Copilot Studio displays the demo website URL, copy it and send it to your testers.

When you send the URL, tell testers what to try and which version they're reviewing. When their feedback leads to changes in the draft, testers see those changes only after you publish again. The version in the agent's greeting tells you which release each piece of feedback refers to.

Add the agent to a custom web app

The demo website is for review, but a custom website or web app is where users reach the agent in production. The site can be external, such as a support site that hosts a help agent for customers, or internal, such as an intranet portal for employees.

The Web app channel embeds the agent in a custom web application by using an iframe, an HTML element that displays one web page inside another. Adding the agent to the site involves two roles:

  • Maker: Publishes the agent to the Web app channel and gives the web developer what the site needs to connect to the agent.
  • Web developer: Adds the agent to the website or web app.

You publish to the Web app channel the same way you publish to the demo website: in the Publish agent dialog, select Web app in the list of available channels, and then select Publish.

Protect web channel access with secrets

A site that connects to the agent through code, rather than a shared link, needs a way to prove that its requests are allowed. Web channel security provides that proof for Direct Line, the channel that connects a web page or app to the agent. The agent's secrets authenticate requests from your web channel, and they're required for compatibility with the Direct Line API.

Each agent has two secrets, Secret 1 and Secret 2. To copy a secret for your web application:

  1. With the agent open, select the three dots (…) in the agent designer toolbar, and then select Settings.
  2. In the Agent settings dialog, select the Safety & access tab, and then select Web channel security.
  3. Next to Secret 1 or Secret 2, select Copy.

Treat each secret like a password. Anyone who has it can authenticate requests to the agent as your site.

Keep secrets out of the browser

Where your site's code runs determines whether it can use a secret directly:

  • Service-to-service app: When your own service calls the agent, the service can put the secret in the authorization header of each request.
  • Browser or mobile app: When code runs in a web browser or mobile app, users can see it. That code must use a token instead of the secret.

Warning

Don't expose a secret in any code that runs in the browser, whether you hard-code it or send it through a network call.

Your service code, the part of your app that runs on a server, exchanges the secret for a token. It sends the secret in the authorization header of a request like this one:

POST https://directline.botframework.com/v3/directline/tokens/generate
Authorization: Bearer <SECRET>

The response contains a token and an expires_in value, which is the number of seconds until the token expires. A token works for a single conversation. To keep a token usable, your code refreshes it before it expires. Your code can refresh a token any number of times, but it can't refresh an expired token.

For example, suppose employees reach your HR benefits agent on the HR intranet portal. You copy a secret and give it to the portal's web developer, who keeps it in the portal's service code. For each conversation, that code requests a token and passes only the token to the employee's browser. The secret never reaches the browser. If someone copies a token from the page, it works for only one conversation and expires unless the portal refreshes it.

Replace a secret without downtime

Secrets need replacing from time to time, such as when someone who had access to a secret leaves the project. Both secrets work at the same time, so you can move your site from one secret to the other without downtime. After all clients connect with the new secret, select Regenerate next to the old secret to replace it.

Warning

Regenerating a secret disconnects users who connect with the original secret or with a token obtained from it.