Agent SDK (Preview)

Forwards Bot Framework / Microsoft Agents SDK Activity payloads to a user-supplied agent endpoint. The agent endpoint URL is supplied per call as an input parameter. Authentication is selected when creating the connection: no authentication, a static API key, or Microsoft Entra ID OAuth (client_credentials or user sign-in). When OAuth is selected, the bearer token audience (Resource URL configured on the connection) must match the audience expected by the target agent.

This connector is available in the following products and regions:

The Agent SDK connector forwards Bot Framework / Microsoft Agents SDK Activity payloads to a user-supplied agent endpoint. The agent endpoint URL is supplied per call as an input parameter. The connection selects how the connector authenticates to the agent: no authentication, a static API key, a Microsoft Entra ID app-only token (client credentials), or a Microsoft Entra ID delegated user token (user sign-in). For both Microsoft Entra ID options, the bearer token audience (Resource URL configured on the connection) must match the audience expected by the target agent.

Prerequisites

• A deployed Microsoft Agents SDK / Bot Framework agent reachable over HTTPS.
• For Microsoft Entra ID (client credentials): a Microsoft Entra ID application registered in the tenant hosting the agent, configured with the client_credentials grant and permission to call the target agent.
• For Microsoft Entra ID (user sign-in): the agent's own Microsoft Entra ID application (its Microsoft App ID) with a client secret, an exposed API scope that users can consent to, the Microsoft Graph User.Read ("Sign in and read user profile") delegated permission with consent, and https://global.consent.azure-apim.net/redirect/agentsdk added as a Web redirect URI.
• For the API key and client credentials options, the agent's expected token audience (typically the agent's Microsoft App ID, for example api://<appId> or the App ID GUID). For user sign-in, the audience must be the App ID GUID (see below).

Get your credentials

Microsoft Entra ID (client credentials)

The connector sends an app-only token. To authenticate your API requests, you will need:

1. The Tenant ID of the Microsoft Entra ID application.
2. The Client ID (Application ID) of the Microsoft Entra ID application.
3. The Client Secret for that application.
4. The Resource URL matching the audience expected by the target agent (Bot Framework skill auth pattern).

Provide these values when you create a connection. Create one connection per agent if audiences differ.

Microsoft Entra ID (user sign-in)

The connector sends the delegated token of the account signed in to the connection, so the agent can exchange it on behalf of that account (for example, with the Microsoft 365 Agents SDK ConnectorUserAuthorization handler). You will need:

1. The Tenant ID of the agent's Microsoft Entra ID application.
2. The Client ID: the agent's own Microsoft App ID. The Microsoft 365 Agents SDK exchanges the token on behalf of the user only when the token was issued to the agent's own application.
3. The Client Secret for that application.
4. The Resource URL: the agent's Microsoft App ID (GUID), the same value as the Client ID. Because the agent's own application is both the client and the resource, Microsoft Entra requires the GUID here (AADSTS90009 otherwise); api://<appId> isn't supported for this option.

Provide these values when you create a connection, and then sign in and consent to the agent's exposed scope. Create one connection per agent.

The application also needs the Microsoft Graph User.Read ("Sign in and read user profile") delegated permission with consent; without it, sign-in fails with AADSTS90008.

To exchange the token for a downstream API, configure that API's delegated permissions on the agent's application and obtain the required user or administrator consent. Exposing a scope on the agent's own API doesn't grant downstream permissions.

Known issues and limitations

• The agentEndpoint input must be a full HTTPS URL (for example, https://my-agent.azurewebsites.net). The connector appends /api/messages and forwards the Activity payload.
• The connector forwards the Activity payload as-is and does not set deliveryMode. The agent replies asynchronously (normal delivery) by POSTing reply activities back to the serviceUrl supplied on the inbound activity (the caller, e.g. Microsoft Copilot Studio, provides a SAS-keyed callback serviceUrl).
• A Microsoft Entra ID (user sign-in) connection always sends the delegated token of the account signed in to the connection, for every call made with that connection, including calls on behalf of other people chatting with the agent. It doesn't send a separate token for each caller, so the activity's from user can differ from the user in the token. Authorize requests only as the account in the validated token, and don't treat the activity's from or request headers as the chatting person's authority. If the agent must act as each person chatting with it, don't use this connection type.
• If the signed-in account's consent is revoked or its session can no longer be refreshed, sign in to the connection again.
• This connector is in preview. Availability and capabilities are subject to change.

Creating a connection

The connector supports the following authentication types:

API key

Auth ID: apiKey

Applicable: All regions

Authenticate with a static API key the target agent expects in a custom HTTP header. Specify both the header name (for example, x-api-key) and its value.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Microsoft Entra ID (client credentials)

Auth ID: oauthClientCredentials

Applicable: All regions

Mint OAuth bearer tokens from a Microsoft Entra ID application using the client_credentials flow. The bearer token audience (Resource URL) must match the audience expected by the target agent.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Microsoft Entra ID (user sign-in)

Auth ID: oauthAuthorizationCode

Applicable: All regions

Sign in through the target agent's Microsoft Entra ID application (authorization code flow) and send the signed-in account's delegated bearer token. Every call made with this connection uses the account signed in to the connection, not the person chatting with the agent. To exchange the token on behalf of the user, the agent needs its downstream delegated permissions and consent configured.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

No authentication

Auth ID: anonymous

Applicable: All regions

Call the target agent endpoint without any authentication header. Only use this with agents that explicitly accept anonymous calls.

This is shareable connection. If the power app is shared with another user, connection is shared as well. For more information, please see the Connectors overview for canvas apps - Power Apps | Microsoft Docs

Default [DEPRECATED]

Applicable: All regions

This option is only for older connections without an explicit authentication type, and is only provided for backward compatibility.

This is not shareable connection. If the power app is shared with another user, another user will be prompted to create new connection explicitly.

Actions

Send activity to agent

Definitions

object