Adicionar aplicativos lógicos como plug-ins
Muitas vezes, em uma empresa, você já tem um conjunto de fluxos de trabalho que executam trabalho real em aplicativos lógicos. Eles podem ser usados por outros serviços de automação ou aplicativos front-end de energia com os quais os seres humanos interagem. No Kernel Semântico, você pode adicionar exatamente os mesmos fluxos de trabalho como plug-ins para que seus agentes também possam usá-los.
Tomemos como exemplo os fluxos de trabalho de Aplicativos Lógicos usados pela equipe do Kernel Semântico para responder a perguntas sobre novos PRs. Com os fluxos de trabalho a seguir, um agente tem tudo o que precisa para recuperar alterações de código, pesquisar arquivos relacionados e verificar logs de falha.
- Pesquisar arquivos – para encontrar trechos de código que são relevantes para um determinado problema
- Obter arquivo – para recuperar o conteúdo de um arquivo no repositório GitHub
- Obter detalhes de RP – para recuperar os detalhes de um RP (por exemplo, o título, a descrição e o autor de RP)
- Obter arquivos PR – para recuperar os arquivos que foram alterados em um PR
- Obter falhas de compilação e teste – para recuperar as falhas de compilação e teste para uma determinada execução de ação do GitHub
- Obter arquivo de log – para recuperar o arquivo de log para uma determinada execução de ação do GitHub
Aproveitar os plug-ins do Logic Apps for Semantic Kernel também é uma ótima maneira de aproveitar os mais de 1.400 conectores disponíveis no Logic Apps. Isso significa que você pode se conectar facilmente a uma ampla variedade de serviços e sistemas sem escrever nenhum código.
Importante
Hoje, você só pode adicionar aplicativos lógicos padrão (também conhecidos como aplicativos lógicos de locatário único) como plugins. Aplicativos lógicos de consumo estão chegando em breve.
Importando aplicativos lógicos como plug-ins
Para adicionar fluxos de trabalho de Aplicativos Lógicos ao Kernel Semântico, você usará os mesmos métodos de carregamento em especificações OpenAPI. Abaixo está um código de exemplo.
await kernel.ImportPluginFromOpenApiAsync(
pluginName: "openapi_plugin",
uri: new Uri("https://example.azurewebsites.net/swagger.json"),
executionParameters: new OpenApiFunctionExecutionParameters()
{
// Determines whether payload parameter names are augmented with namespaces.
// Namespaces prevent naming conflicts by adding the parent parameter name
// as a prefix, separated by dots
EnablePayloadNamespacing = true
}
);
Configurando aplicativos lógicos para kernel semântico
Antes de importar um Aplicativo Lógico como um plug-in, você deve primeiro configurar o Aplicativo Lógico para ser acessível pelo Kernel Semântico. Isso envolve habilitar pontos de extremidade de metadados e configurar seu aplicativo para Easy Auth antes de finalmente importar o Logic App como um plug-in com autenticação.
Habilitar pontos de extremidade de metadados
Para uma configuração mais fácil, você pode habilitar o acesso não autenticado aos pontos de extremidade de metadados para seu Logic App. Isso permitirá que você importe seu Logic App como um plug-in para o Semantic Kernel sem precisar criar um cliente HTTP personalizado para lidar com a autenticação para a importação inicial.
O arquivo host.json abaixo criará dois pontos de extremidade não autenticados. Você pode fazer isso no portal azure indo para o console kudu e editando o arquivo host.json localizado em C:\home\site\wwwroot\host.json.
{
"version": "2.0",
"extensionBundle": {
"id": "Microsoft.Azure.Functions.ExtensionBundle.Workflows",
"version": "[1.*, 2.0.0)"
},
"extensions": {
"http": {
"routePrefix": ""
},
"workflow": {
"MetadataEndpoints": {
"plugin": {
"enable": true,
"Authentication":{
"Type":"Anonymous"
}
},
"openapi": {
"enable": true,
"Authentication":{
"Type":"Anonymous"
}
}
},
"Settings": {
"Runtime.Triggers.RequestTriggerDefaultApiVersion": "2020-05-01-preview"
}
}
}
}
Configure seu aplicativo para Easy Auth
Agora você deseja proteger seus fluxos de trabalho do Aplicativo Lógico para que apenas usuários autorizados possam acessá-los. Você pode fazer isso ativando o Easy Auth em seu aplicativo lógico. Isso permitirá que você use o mesmo mecanismo de autenticação que seus outros serviços do Azure, facilitando o gerenciamento de suas políticas de segurança.
Para obter um passo a passo detalhado sobre como configurar o Easy Auth, consulte este tutorial intitulado Trigger workflows in Standard logic apps with Easy Auth.
Para aqueles que já estão familiarizados com o Easy Auth (e já têm um aplicativo cliente Entra que você deseja usar), esta é a configuração que você desejará postar no gerenciamento do Azure.
#!/bin/bash
# Variables
subscription_id="[SUBSCRIPTION_ID]"
resource_group="[RESOURCE_GROUP]"
app_name="[APP_NAME]"
api_version="2022-03-01"
arm_token="[ARM_TOKEN]"
tenant_id="[TENANT_ID]"
aad_client_id="[AAD_CLIENT_ID]"
object_ids=("[OBJECT_ID_FOR_USER1]" "[OBJECT_ID_FOR_USER2]" "[OBJECT_ID_FOR_APP1]")
# Convert the object_ids array to a JSON array
object_ids_json=$(printf '%s\n' "${object_ids[@]}" | jq -R . | jq -s .)
# Request URL
url="https://management.azure.com/subscriptions/$subscription_id/resourceGroups/$resource_group/providers/Microsoft.Web/sites/$app_name/config/authsettingsV2?api-version=$api_version"
# JSON payload
json_payload=$(cat <<EOF
{
"properties": {
"platform": {
"enabled": true,
"runtimeVersion": "~1"
},
"globalValidation": {
"requireAuthentication": true,
"unauthenticatedClientAction": "AllowAnonymous"
},
"identityProviders": {
"azureActiveDirectory": {
"enabled": true,
"registration": {
"openIdIssuer": "https://sts.windows.net/$tenant_id/",
"clientId": "$aad_client_id"
},
"validation": {
"jwtClaimChecks": {},
"allowedAudiences": [
"api://$aad_client_id"
],
"defaultAuthorizationPolicy": {
"allowedPrincipals": {
"identities": $object_ids_json
}
}
}
},
"facebook": {
"enabled": false,
"registration": {},
"login": {}
},
"gitHub": {
"enabled": false,
"registration": {},
"login": {}
},
"google": {
"enabled": false,
"registration": {},
"login": {},
"validation": {}
},
"twitter": {
"enabled": false,
"registration": {}
},
"legacyMicrosoftAccount": {
"enabled": false,
"registration": {},
"login": {},
"validation": {}
},
"apple": {
"enabled": false,
"registration": {},
"login": {}
}
}
}
}
EOF
)
# HTTP PUT request
curl -X PUT "$url" \
-H "Content-Type: application/json" \
-H "Authorization: Bearer $arm_token" \
-d "$json_payload"
Use aplicativos lógicos com kernel semântico como um plug-in
Agora que você tem seu Logic App protegido e os pontos de extremidade de metadados ativados, você concluiu todas as partes difíceis. Agora você pode importar seu Logic App como um plug-in para o Semantic Kernel usando o método de importação OpenAPI.
Ao criar seu plug-in, você desejará fornecer um cliente HTTP personalizado que possa lidar com a autenticação para seu aplicativo lógico. Isso permitirá que você use o plugin em seus agentes de IA sem precisar se preocupar com a autenticação.
Abaixo está um exemplo em C# que aproveita a autenticação interativa para adquirir um token e autenticar o usuário para o aplicativo lógico.
string ClientId = "[AAD_CLIENT_ID]";
string TenantId = "[TENANT_ID]";
string Authority = $"https://login.microsoftonline.com/{TenantId}";
string[] Scopes = new string[] { "api://[AAD_CIENT_ID]/SKLogicApp" };
var app = PublicClientApplicationBuilder.Create(ClientId)
.WithAuthority(Authority)
.WithDefaultRedirectUri() // Uses http://localhost for a console app
.Build();
AuthenticationResult authResult = null;
try
{
authResult = await app.AcquireTokenInteractive(Scopes).ExecuteAsync();
}
catch (MsalException ex)
{
Console.WriteLine("An error occurred acquiring the token: " + ex.Message);
}
// Add the plugin to the kernel with a custom HTTP client for authentication
kernel.Plugins.Add(await kernel.ImportPluginFromOpenApiAsync(
pluginName: "[NAME_OF_PLUGIN]",
uri: new Uri("https://[LOGIC_APP_NAME].azurewebsites.net/swagger.json"),
executionParameters: new OpenApiFunctionExecutionParameters()
{
HttpClient = new HttpClient()
{
DefaultRequestHeaders =
{
Authorization = new AuthenticationHeaderValue("Bearer", authResult.AccessToken)
}
},
}
));
Próximos passos
Agora que você sabe como criar um plugin, agora você pode aprender como usá-los com seu agente de IA. Dependendo do tipo de funções que você adicionou aos seus plugins, existem diferentes padrões que você deve seguir. Para funções de recuperação, consulte o artigo Usando funções de recuperação. Para funções de automação de tarefas, consulte o artigo Usando funções de automação de tarefas.