SDK do agente (versão prévia)

Encaminha cargas de atividade do SDK do Bot Framework/Microsoft Agents para um ponto de extremidade de agente fornecido pelo usuário. A URL do ponto de extremidade do agente é fornecida por chamada como um parâmetro de entrada. A autenticação é selecionada ao criar a conexão: sem autenticação, uma chave de API estática ou Microsoft Entra ID OAuth (client_credentials ou entrada do usuário). Quando o OAuth é selecionado, o público-alvo do token de portador (URL de recurso configurada na conexão) deve corresponder ao público-alvo esperado pelo agente de destino.

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

O conector do SDK do Agente encaminha cargas de atividade do SDK do Bot Framework/Microsoft Agents para um ponto de extremidade de agente fornecido pelo usuário. A URL do ponto de extremidade do agente é fornecida por chamada como um parâmetro de entrada. A conexão seleciona como o conector se autentica no agente: sem autenticação, uma chave de API estática, um token somente de aplicativo Microsoft Entra ID (credenciais do cliente) ou um token de usuário delegado Microsoft Entra ID (entrada do usuário). Para ambas as opções de Microsoft Entra ID, o público-alvo do token de portador (URL de recurso configurada na conexão) deve corresponder ao público-alvo esperado pelo agente de destino.

Pré-requisitos

• Um agente do SDK do Microsoft Agents/Bot Framework implantado pode ser acessado por HTTPS.
• Para Microsoft Entra ID (credenciais do cliente): um aplicativo Microsoft Entra ID registrado no locatário que hospeda o agente, configurado com a client_credentials concessão e a permissão para chamar o agente de destino.
• Para Microsoft Entra ID (entrada do usuário): o próprio aplicativo Microsoft Entra ID do agente (sua ID do aplicativo Microsoft) com um segredo do cliente, um escopo de API exposto ao qual os usuários podem consentir, o Microsoft Graph User.Read ("Entrar e ler perfil de usuário") deu permissão delegada com consentimento e https://global.consent.azure-apim.net/redirect/agentsdk foi adicionada como um URI de redirecionamento da Web.
• Para as opções de chave de API e credenciais de cliente, o público de token esperado do agente (normalmente a ID do aplicativo Microsoft do agente, por exemploapi://<appId>, ou o GUID da ID do Aplicativo). Para entrar no usuário, o público-alvo deve ser o GUID da ID do Aplicativo (veja abaixo).

Obter suas credenciais

Microsoft Entra ID (credenciais do cliente)

O conector envia um token somente de aplicativo. Para autenticar suas solicitações de API, você precisará de:

1. A ID do locatário do aplicativo Microsoft Entra ID.
2. A ID do cliente (ID do aplicativo) do aplicativo Microsoft Entra ID.
3. O Segredo do Cliente para esse aplicativo.
4. A URL de Recurso que corresponde ao público-alvo esperado pelo agente de destino (padrão de autenticação de habilidade do Bot Framework).

Forneça esses valores ao criar uma conexão. Crie uma conexão por agente se o público-alvo for diferente.

Microsoft Entra ID (entrada do usuário)

O conector envia o token delegado da conta conectada à conexão, para que o agente possa trocá-lo em nome dessa conta (por exemplo, com o manipulador de SDK de Agentes do Microsoft 365ConnectorUserAuthorization). Você precisará de:

1. A ID do locatário do aplicativo Microsoft Entra ID do agente.
2. A ID do cliente: a própria ID do aplicativo Microsoft do agente. O SDK de Agentes do Microsoft 365 troca o token em nome do usuário somente quando o token foi emitido para o próprio aplicativo do agente.
3. O Segredo do Cliente para esse aplicativo.
4. A URL do Recurso: o GUID (ID do aplicativo Microsoft) do agente, o mesmo valor que a ID do cliente. Como o próprio aplicativo do agente é o cliente e o recurso, Microsoft Entra requer o GUID aqui (AADSTS90009 caso contrário); api://<appId> não há suporte para essa opção.

Forneça esses valores ao criar uma conexão e, em seguida, entre e consenta com o escopo exposto do agente. Crie uma conexão por agente.

O aplicativo também precisa da permissão delegada Microsoft Graph User.Read ("Entrar e ler perfil de usuário") com consentimento; sem ele, a entrada falha com AADSTS90008.

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

Limitações e problemas conhecidos

• A agentEndpoint entrada deve ser uma URL HTTPS completa (por exemplo, https://my-agent.azurewebsites.net). O conector acrescenta /api/messages e encaminha o conteúdo da Atividade.
• O conector encaminha o conteúdo da atividade as-is e não define deliveryMode. O agente responde de forma assíncrona (entrega normal) ao enviar atividades de resposta de volta ao serviceUrl fornecido na atividade de entrada (o chamador, por exemplo, Microsoft Copilot Studio, fornece um retorno serviceUrlde chamada com chave SAS).
• Uma conexão Microsoft Entra ID (entrada do usuário) sempre envia o token delegado da conta conectado à conexão, para cada chamada feita com essa conexão, incluindo chamadas em nome de outras pessoas conversando com o agente. Ele não envia um token separado para cada chamador, portanto, o usuário da from atividade pode diferir do usuário no token. Autorize solicitações apenas como a conta no token validado e não trate os cabeçalhos da atividade ou da from solicitação como a autoridade da pessoa que está conversando. Se o agente precisar agir como cada pessoa conversando com ele, não use esse tipo de conexão.
• Se o consentimento da conta de entrada for revogado ou sua sessão não puder mais ser atualizada, entre na conexão novamente.
• Esse conector está em versão prévia. A disponibilidade e os recursos estão sujeitos a alterações.

Criando uma conexão

O conector dá suporte aos seguintes tipos de autenticação:

chave de API

ID de autenticação: apiKey

Aplicável: todas as regiões

Autentique com uma chave de API estática que o agente de destino espera em um cabeçalho HTTP personalizado. Especifique o nome do cabeçalho (por exemplo, x-api-key) e seu valor.

Essa não é uma conexão compartilhável. Se o aplicativo de energia for compartilhado com outro usuário, outro usuário será solicitado a criar uma nova conexão explicitamente.

Microsoft Entra ID (credenciais do cliente)

ID de autenticação: oauthClientCredentials

Aplicável: todas as regiões

Tokens de portador do Mint OAuth de um aplicativo Microsoft Entra ID usando o fluxo de client_credentials. O público-alvo do token de portador (URL do recurso) deve corresponder ao público-alvo esperado pelo agente de destino.

Essa não é uma conexão compartilhável. Se o aplicativo de energia for compartilhado com outro usuário, outro usuário será solicitado a criar uma nova conexão explicitamente.

Microsoft Entra ID (entrada do usuário)

ID de autenticação: oauthAuthorizationCode

Aplicável: todas as regiões

Entre por meio do aplicativo Microsoft Entra ID do agente de destino (fluxo de código de autorização) e envie o token de portador delegado da conta de entrada. Cada chamada feita com essa conexão usa a conta conectado à conexão, não a pessoa que conversa com o agente. Para trocar o token em nome do usuário, o agente precisa de suas permissões delegadas downstream e consentimento configurados.

Essa não é uma conexão compartilhável. Se o aplicativo de energia for compartilhado com outro usuário, outro usuário será solicitado a criar uma nova conexão explicitamente.

Sem autenticação

ID de autenticação: anônimo

Aplicável: todas as regiões

Chame o ponto de extremidade do agente de destino sem nenhum cabeçalho de autenticação. Use isso apenas com agentes que aceitam explicitamente chamadas anônimas.

Essa é 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 do Connectors para aplicativos de tela – Power Apps | Microsoft Docs

Padrão [PRETERIDO]

Aplicável: todas as regiões

Essa 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.

Essa não é uma conexão compartilhável. Se o aplicativo de energia 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

Definições

objeto