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). 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; Os tokens OAuth são cunhados pela plataforma a partir das credenciais de aplicação Microsoft Entra ID fornecidas pelo utilizador, configuradas na ligação e injetados como um token Bearer em cada pedido de saída. 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.
  • Uma aplicação Microsoft Entra ID registada no inquilino que aloja o agente, configurada com a client_credentials concessão e permissão para ligar para o agente alvo.
  • O público token esperado do agente (tipicamente o ID da Microsoft App do agente, api://<appId>por exemplo).

Obtenha as suas credenciais

Para autenticar os seus pedidos de API, precisará de:

  1. O ID do Tenant da aplicação Microsoft Entra ID.
  2. O ID do Cliente (ID da Aplicação) da aplicação Microsoft Entra ID.
  3. O Segredo do Cliente para essa aplicação.
  4. 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.

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).
  • 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
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

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

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.

Parâmetros

Name 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

Devoluções

response
object

Definições

objecto

Este é o tipo 'objeto'.