SDK do Agente (Pré-visualização)

Encaminha cargas úteis do Framework Bot / Microsoft Agents SDK Activity para um endpoint agente fornecido pelo utilizador. A URL do endpoint do agente é fornecida por chamada como parâmetro de entrada. A autenticação é selecionada ao criar a ligação: sem autenticação, uma chave API estática ou Microsoft Entra ID OAuth (client_credentials ou login do utilizador). Quando o OAuth é selecionado, a audiência do token portador (URL de recurso configurada na ligação) deve corresponder à audiência esperada pelo agente-alvo.

Este conector está disponível nos seguintes produtos e regiões:

Serviço	Class	Regions
Estúdio Copiloto	Standard	Todas as regiões Power Automate exceto as seguintes: - Governo dos EUA (CCG) - Governo dos EUA (GCC High) - China Cloud operado pela 21Vianet - Departamento de Defesa dos EUA (DoD)
Aplicações Lógicas	Standard	Todas as regiões do Logic Apps , exceto as seguintes: - Regiões do Azure Government - Regiões Azure China - Departamento de Defesa dos EUA (DoD)
Power Apps	Standard	Todas as regiões Power Apps exceto as seguintes: - Governo dos EUA (CCG) - Governo dos EUA (GCC High) - China Cloud operado pela 21Vianet - Departamento de Defesa dos EUA (DoD)
Power Automate	Standard	Todas as regiões Power Automate exceto as seguintes: - Governo dos EUA (CCG) - Governo dos EUA (GCC High) - China Cloud operado pela 21Vianet - Departamento de Defesa dos EUA (DoD)

Contact
Nome	Microsoft
URL	https://support.microsoft.com

Metadados do conector
Editor	Microsoft
Sítio Web	https://www.microsoft.com
Política de privacidade	https://privacy.microsoft.com/
Categorias	Productivity

O conector Agent SDK encaminha cargas úteis Bot Framework / Microsoft Agents SDK Activity para um endpoint agente fornecido pelo utilizador. A URL do endpoint do agente é fornecida por chamada como parâmetro de entrada. A ligação seleciona como o conector se autentica junto do agente: sem autenticação, uma chave API estática, um token exclusivo da aplicação Microsoft Entra ID (credenciais do cliente) ou um token de utilizador delegado pelo Microsoft Entra ID (login do utilizador). Para ambas as opções do Microsoft Entra ID, a audiência do token portador (URL de recurso configurada na ligação) deve corresponder à audiência esperada pelo agente-alvo.

Pré-requisitos

Um agente implantado do Microsoft Agents SDK / Bot Framework acessível via HTTPS.
Para o Microsoft Entra ID (credenciais do cliente): uma aplicação Microsoft Entra ID registada no tenant que aloja o agente, configurada com a client_credentials concessão e permissão para contactar o agente alvo.
Para o Microsoft Entra ID (login do utilizador): a aplicação Microsoft Entra ID do agente (o seu Microsoft App ID) com um segredo do cliente, um âmbito de API exposto ao qual os utilizadores podem consentir, o Microsoft Graph User. Read ("Iniciar sessão e ler o perfil do utilizador") delegou permissão com consentimento, e https://global.consent.azure-apim.net/redirect/agentsdk foi adicionado como URI de redirecionamento Web.
Para as opções de chave API e credenciais do cliente, o público esperado do token do agente (tipicamente o ID da Microsoft App do agente, por exemploapi://<appId>, ou o ID da App GUID). Para iniciar sessão do utilizador, o público deve ser o ID da Aplicação GUID (ver abaixo).

Obtenha as suas credenciais

Microsoft Entra ID (credenciais do cliente)

O conector envia um token exclusivo da aplicação. Para autenticar os seus pedidos de API, precisará de:

O ID do Tenant da aplicação Microsoft Entra ID.
O ID do Cliente (ID da Aplicação) da aplicação Microsoft Entra ID.
O Segredo do Cliente para essa aplicação.
A URL do recurso corresponde ao público esperado pelo agente-alvo (padrão de autenticação de habilidades do Bot Framework).

Dê estes valores quando criar uma ligação. Crie uma ligação por agente se o público for diferente.

O conector envia o token delegado da conta iniciada na ligação, para que o agente possa trocá-lo em nome dessa conta (por exemplo, com o handler do SDK de Agentes do Microsoft 365ConnectorUserAuthorization). Irá necessitar de:

O ID do Inquilino da aplicação Microsoft Entra ID do agente.
O ID do Cliente: o próprio ID da aplicação Microsoft do agente. O SDK de Agentes do Microsoft 365 troca o token em nome do utilizador apenas quando o token foi emitido para a própria aplicação do agente.
O Segredo do Cliente para essa aplicação.
A URL do Resource: o ID da Microsoft App (GUID) do agente, o mesmo valor do ID do Cliente. Como a aplicação do próprio agente é tanto o cliente como o recurso, Microsoft Entra requer o GUID aqui (AADSTS90009 caso contrário); api://<appId> não é suportado para esta opção.

Forneça estes valores quando criar uma ligação e depois faça login e consinta com o âmbito exposto do agente. Crie uma ligação por agente.

A aplicação também necessita da permissão delegada Microsoft Graph User.Read ("Iniciar sessão e ler o perfil de utilizador") com consentimento; sem ela, o início de sessão falha com AADSTS90008.

Para trocar o token por uma API a jusante, configure as permissões delegadas dessa API na aplicação do agente e obtenha o consentimento necessário do utilizador ou administrador. Expor um escopo na própria API do agente não concede permissões a jusante.

Problemas e limitações conhecidos

A agentEndpoint entrada deve ser uma URL HTTPS completa (por exemplo, https://my-agent.azurewebsites.net). O conector adiciona /api/messages e encaminha a carga útil da Atividade.
O conector encaminha a carga útil de Atividade as-is e não define deliveryMode. O agente responde de forma assíncrona (entrega normal) ao POSTar as atividades de resposta fornecidas serviceUrl na atividade de entrada (o chamador, por exemplo, Microsoft Copilot Studio, fornece um callback serviceUrlcom chave SAS).
Uma ligação Microsoft Entra ID (login de utilizador) envia sempre o token delegado da conta iniciada na ligação, para cada chamada feita com essa ligação, incluindo chamadas em nome de outras pessoas que conversam com o agente. Não envia um token separado para cada chamador, por isso o utilizador da from atividade pode diferir do utilizador no token. Autorize os pedidos apenas como a conta no token validado, e não trate os cabeçalhos da from atividade ou do pedido como autoridade da pessoa que está a conversar. Se o agente tiver de agir como cada pessoa que conversa com ele, não use este tipo de ligação.
Se o consentimento da conta iniciada for revogado ou a sua sessão já não puder ser atualizada, volte a iniciar sessão na ligação.
Este conector está em pré-visualização. A disponibilidade e as capacidades estão sujeitas a alterações.

A criar uma ligação

O conector suporta os seguintes tipos de autenticação:


Chave de API	Autenticar com uma chave de API estática que o agente alvo espera num cabeçalho HTTP personalizado. Especifique tanto o nome do cabeçalho (por exemplo, x-api-key) como o seu valor.	Todas as regiões	Não compartilhável
Microsoft Entra ID (credenciais do cliente)	Cunhe tokens portadores OAuth de uma aplicação Microsoft Entra ID usando o fluxo client_credentials. A audiência do token portador (URL de Recursos) deve corresponder à audiência esperada pelo agente-alvo.	Todas as regiões	Não compartilhável
Microsoft Entra ID (login do utilizador)	Inicie sessão através da aplicação Microsoft Entra ID do agente alvo (fluxo de código de autorização) e envie o token de portador delegado da conta iniciada. Todas as chamadas feitas com esta ligação usam a conta iniciada na ligação, não a pessoa que está a conversar com o agente. Para trocar o token em nome do utilizador, o agente precisa de configurar as permissões delegadas a jusante e o consentimento.	Todas as regiões	Não compartilhável
Sem autenticação	Chame o endpoint do agente de destino sem qualquer cabeçalho de autenticação. Usa isto apenas com agentes que aceitam explicitamente chamadas anónimas.	Todas as regiões	Compartilhável
Padrão [DEPRECATED]	Esta opção é apenas para conexões mais antigas sem um tipo de autenticação explícita e é fornecida apenas para compatibilidade com versões anteriores.	Todas as regiões	Não compartilhável

chave de API

ID de autenticação: apiKey

Aplicável: Todas as regiões

Autenticar com uma chave de API estática que o agente alvo espera num cabeçalho HTTP personalizado. Especifique tanto o nome do cabeçalho (por exemplo, x-api-key) como o seu valor.

Esta conexão não é compartilhável. Se o aplicativo avançado for compartilhado com outro usuário, outro usuário será solicitado a criar uma nova conexão explicitamente.

Nome	Tipo	Descrição	Obrigatório
Nome do cabeçalho da chave API	cadeia (de caracteres)	Nome do cabeçalho HTTP sobre o qual o agente alvo espera a chave API (por exemplo, x-api-key ou Ocp-Apim-Subscription-Key).	Verdade
Valor da chave API	securestring	Valor estático da chave API enviado em cada pedido para o endpoint do agente alvo.	Verdade

Microsoft Entra ID (credenciais do cliente)

ID de autenticação: oauthClientCredentials

Aplicável: Todas as regiões

Cunhe tokens portadores OAuth de uma aplicação Microsoft Entra ID usando o fluxo client_credentials. A audiência do token portador (URL de Recursos) deve corresponder à audiência esperada pelo agente-alvo.

Esta conexão não é compartilhável. Se o aplicativo avançado for compartilhado com outro usuário, outro usuário será solicitado a criar uma nova conexão explicitamente.

Nome	Tipo	Descrição	Obrigatório
Tenant	cadeia (de caracteres)	O ID de inquilino da aplicação Microsoft Entra ID	Verdade
ID de Cliente	cadeia (de caracteres)	ID de cliente (ou aplicação) da aplicação Microsoft Entra ID.	Verdade
Segredo do Cliente	securestring	Segredo do cliente da aplicação Microsoft Entra ID.	Verdade
URL do Recurso	cadeia (de caracteres)	Audiência para o token OAuth. Normalmente, o Microsoft ID da aplicação do agente alvo (por exemplo, api://< appID> ou o ID da aplicação).	Verdade

ID de Auth: oauthAuthorizationCode

Aplicável: Todas as regiões

Inicie sessão através da aplicação Microsoft Entra ID do agente alvo (fluxo de código de autorização) e envie o token de portador delegado da conta iniciada. Todas as chamadas feitas com esta ligação usam a conta iniciada na ligação, não a pessoa que está a conversar com o agente. Para trocar o token em nome do utilizador, o agente precisa de configurar as permissões delegadas a jusante e o consentimento.

Esta conexão não é compartilhável. Se o aplicativo avançado for compartilhado com outro usuário, outro usuário será solicitado a criar uma nova conexão explicitamente.

Nome	Tipo	Descrição	Obrigatório
Tenant	cadeia (de caracteres)	O ID do tenant da aplicação Microsoft Entra ID do agente alvo.	Verdade
ID de Cliente	cadeia (de caracteres)	O ID da aplicação Microsoft do agente alvo. Use a própria aplicação do agente para que este possa trocar o token delegado em nome do utilizador.	Verdade
Segredo do Cliente	securestring	Segredo do cliente da aplicação Microsoft Entra ID do agente alvo.	Verdade
URL do Recurso	cadeia (de caracteres)	Audiência para o token delegado. Deve ser o Microsoft App ID (GUID) do agente alvo, com o mesmo valor do ID do Cliente: o Microsoft Entra aceita apenas o GUID quando uma aplicação solicita um token para si própria.	Verdade

Sem autenticação

ID de autenticação: anónimo

Aplicável: Todas as regiões

Chame o endpoint do agente de destino sem qualquer cabeçalho de autenticação. Usa isto apenas com agentes que aceitam explicitamente chamadas anónimas.

Esta é uma conexão compartilhável. Se o aplicativo de energia for compartilhado com outro usuário, a conexão também será compartilhada. Para obter mais informações, consulte a Visão geral de conectores para aplicativos de tela - Power Apps | Documentos Microsoft

Padrão [DEPRECATED]

Aplicável: Todas as regiões

Esta opção é apenas para conexões mais antigas sem um tipo de autenticação explícita e é fornecida apenas para compatibilidade com versões anteriores.

Esta conexão não é compartilhável. Se o aplicativo avançado for compartilhado com outro usuário, outro usuário será solicitado a criar uma nova conexão explicitamente.

Ações

Enviar atividade para o agente

Encaminha um payload do Protocolo de Atividade para o endpoint do agente em {agentEndpoint}/api/messages. Quando a ligação utiliza o Microsoft Entra ID OAuth, a audiência do token (URL de recurso na ligação) deve igualar a audiência esperada pelo agente-alvo (padrão de autenticação de habilidades do Bot Framework); criar uma ligação por agente se as audiências diverrem. O conector encaminha a carga útil de Atividade as-is e não define o 'deliveryMode'; o agente responde de forma assíncrona (entrega normal) ao POSTar as atividades de resposta ao 'serviceUrl' fornecido na atividade de entrada.

Enviar atividade para o agente

ID da Operação:: SendActivity

Parâmetros

Nome	Chave	Obrigatório	Tipo	Descrição
URL do endpoint do agente	agentEndpoint	True	string	URL base do endpoint alvo do SDK dos Microsoft Agents / Bot Framework (por exemplo, https://my-agent.azurewebsites.net). O conector adiciona /api/messages.
			object

SDK do Agente (Pré-visualização)

Pré-requisitos

Obtenha as suas credenciais

Microsoft Entra ID (credenciais do cliente)

Microsoft Entra ID (login do utilizador)

Problemas e limitações conhecidos

A criar uma ligação

chave de API

Microsoft Entra ID (credenciais do cliente)

Microsoft Entra ID (login do utilizador)

Sem autenticação

Padrão [DEPRECATED]

Ações

Enviar atividade para o agente

Parâmetros

Devoluções

Definições

objecto