Skip to main content

Providers

The Agent Providers page is an admin-only surface for connecting external AI agent platforms to the Beak AI Runtime and importing the agents hosted on those platforms. The page subtitle reads "Connect external agent platforms and import agents into the Runtime". Supported provider types include Copilot Studio, Amazon Bedrock, Agentforce, OpenAI Assistants, and any platform reachable via the A2A protocol.

Once a provider is registered, agents can be imported manually or discovered automatically through a sync operation. Imported agents appear in the agent grid available to end users throughout the Runtime.

Provider Card Grid​

Registered providers are shown in a responsive card grid. Clicking any card selects it and opens the provider detail panel below the grid.

Provider Card​

Each card displays the following.

  • Provider icon — A type-specific icon drawn from the provider type (cpu for Copilot Studio, zap for Agentforce, database for Bedrock, sparkles for OpenAI Assistants, link for A2A).
  • Display name — The human-readable name given to the provider at registration.
  • Provider type — The raw provider type identifier shown as secondary text below the name.
  • Health badge — A coloured pill showing the current health status. Statuses and their colours are:
    • healthy — success colour
    • degraded — warning colour
    • unreachable — error colour
    • auth_expired — error colour
    • unknown — muted secondary colour
  • Description — Optional free-text description of the provider instance.
  • Last sync date — The date of the most recent successful sync, or "Never synced" if no sync has completed.
  • Check Health button — Fires an immediate health probe against the provider endpoint and refreshes the health badge. The button shows Checking... while the probe is in flight.
  • Remove button — Permanently deletes the provider registration and all associated imported agents.

Add Provider Form​

Clicking the Add Provider button in the page header replaces the button with a form card titled Register New Provider. The form contains the following fields.

Common Fields​

  • Provider Type — Required. A dropdown populated from the available provider types. Selecting a type shows a note listing its supported execution modes.
  • Display Name — Required. The label used throughout the Runtime to identify this provider instance.
  • Description — Optional. A short description.

Copilot Studio Fields​

When Copilot Studio is selected, the form expands with Microsoft-specific connection fields.

  • Power Platform Base URL — The base URL for the Power Platform REST API; defaults to https://api.powerplatform.com.
  • Environment ID — The GUID of the target Power Platform environment, found in the Copilot Studio URL.
  • Microsoft Tenant ID — The Azure AD tenant GUID.
  • App Registration Client ID — The service-principal client_id from the Azure app registration used for API access.
  • App Registration Client Secret — The corresponding client_secret; stored encrypted and masked after saving.

Note: The app registration must be granted the Environment Admin role (or the equivalent Dataverse System Administrator role) on the target Power Platform environment in order for the Sync All operation to discover agents automatically. Service principals are added in the Power Platform admin center under Environments → Settings → Users + permissions.

Other Provider Fields​

For all non-Copilot-Studio provider types, a single API Key / Secret field is shown after the common fields. The value is stored encrypted and masked after saving.

The form footer contains Cancel and Register Provider buttons. Register Provider is disabled while the submission is in flight.

Provider Detail Panel​

Clicking a provider card in the grid opens a detail panel below the grid, showing the provider's display name as the panel title with two action buttons.

  • Import Agents — Opens the Import Agent form inline within the panel.
  • Sync All — Triggers an automatic discovery sync that queries the provider platform for all available agents and updates the Runtime's agent registry. The button shows Syncing... while the operation is in progress.

Import Agent Form​

The Import Agent form allows one or more agents to be registered manually. Rows can be added with + Add another agent and removed individually.

Each agent row contains.

  • Agent name — Required. The display name for the agent within the Runtime.
  • Description — Optional.

For Copilot Studio providers, each row also includes.

  • Bot ID — The GUID identifier of the specific Copilot Studio bot, found in the bot's URL.
  • Direct Line Secret — The secret from the bot's Web Channel Security page, used to authenticate the Runtime's streaming connection.
  • Execution Mode — A radio selector with two options:
    • Passthrough — The agent runs as the signed-in Microsoft 365 user via On-Behalf-Of (OBO) token exchange. No local conversation history is stored. Available only when the Runtime deployment has Microsoft SSO enabled.
    • Proxied — The agent uses the provider's shared service account. Full local conversation history and audit trail are maintained. This is the only available mode when Microsoft SSO is not configured.

Clicking Import Agents submits all rows with a non-empty name. A success toast confirms the number of agents imported.

Sync History​

When a provider has been synced at least once, a Sync History section shows the five most recent sync log entries. Each entry displays a health badge (healthy, degraded, or failed), the number of agents synced and updated, the sync type, the timestamp, and the duration in milliseconds.

Imported External Agents​

Below the provider grid and detail panel, a section titled Imported External Agents lists every agent that has been brought into the Runtime from any provider. Agents are displayed in a card grid. Each card shows the agent name, the provider it came from, and the execution mode. For Copilot Studio agents, two additional controls are available inline on the card.

Set Direct Line Secret​

Clicking Set Direct Line secret on a Copilot Studio agent card expands an inline input for updating the bot's Direct Line secret. The field is masked. Save commits the new secret; Cancel dismisses the input without saving.

Notification Templates​

Each Copilot Studio agent card has a collapsible Notification Templates section that manages webhook-based proactive notification templates for the agent. Clicking the section header toggles the list. Each saved template row shows the template key, an optional description, a Copy URL button (which copies the webhook endpoint to the clipboard), an Edit button, and a Delete button.

Clicking + Add template or Edit opens the template editor with the following fields.

  • Template Key — A URL-safe slug used as the final path segment of the webhook endpoint (for example freshdesk_ticket_event). The key is read-only when editing an existing template.
  • Description — Optional text describing when the template fires.
  • Recipient email path — A dot-path into the incoming webhook JSON body that resolves to the target recipient's email address (for example freshdesk_webhook.requester_email).
  • Mappings — A list of variable-name to JSON-dot-path pairs. Each row maps a template variable (left) to the path in the webhook body where its value is found (right). Rows can be added with + Add mapping and removed individually.
  • Body template — A multi-line text template using {{variable}} placeholders. The {{variable|html_to_text}} filter strips HTML from the resolved value. Lines whose placeholder resolves to an empty string are dropped from the final message.
  • Sample JSON / Preview — A monospace textarea for pasting a sample webhook payload. Clicking Save & Preview saves the template and renders a preview showing the resolved recipient address and the final message body.

Best Practices​

  • Run Check Health after any credential rotation — If the provider's API key or service-principal secret changes, the health badge will surface auth_expired and the Runtime will stop syncing until the credential is updated.
  • Prefer Sync All for Copilot Studio providers — Automatic sync keeps the agent registry in step with the bot catalogue without requiring manual Import Agents entries for each new bot.
  • Use Passthrough mode when Microsoft SSO is available — Passthrough runs each conversation as the signed-in user's identity in Microsoft 365, which satisfies most enterprise data-residency and audit requirements without maintaining a shared service account.
  • Add notification templates for webhook-triggered proactive agents — The Copy URL button in the template list gives the exact endpoint to register in external systems such as Freshdesk or Jira so agents can initiate conversations in response to business events.
  • Review the sync history before reporting a missing agent — A failed sync entry with an agent count of zero usually means the app registration lacks the required Power Platform permissions rather than the agent being absent from the environment.