Observação
O acesso a essa página exige autorização. Você pode tentar entrar ou alterar diretórios.
O acesso a essa página exige autorização. Você pode tentar alterar os diretórios.
Os agentes declarativos adaptam o Microsoft 365 Copilot para atender às necessidades específicas de uma organização. Ao criar agentes declarativos com o Microsoft 365 Agents Toolkit, você pode adicionar habilidades ao seu agente por meio de plug-ins de API. Os plug-ins de API permitem que seu agente consulte e interaja com os dados de uma organização por meio de APIs.
Este artigo descreve a arquitetura do agente e fornece as práticas recomendadas para escrever instruções para agentes declarativos que incluem plug-ins de API.
Principais componentes de agentes declarativos com plug-ins de API
Os agentes declarativos que chamam plug-ins de API incluem vários componentes que garantem integração e funcionalidade eficazes. Entender essa arquitetura ajudará você a projetar seu agente com eficiência. A arquitetura inclui os seguintes componentes:
- Manifesto do aplicativo - Descreve como seu aplicativo está configurado e faz referência ao manifesto do agente declarativo.
- Manifesto declarativo do agente - Define a configuração do agente, incluindo instruções, recursos, iniciadores de conversa e ações. Faz referência ao manifesto do plug-in.
- Manifesto do plug-in - Descreve a configuração do plug-in, incluindo as funções disponíveis e uma referência à especificação OpenAPI.
- Especificação OpenAPI - Fornece definições detalhadas de endpoints de API, incluindo caminhos, parâmetros, formatos de solicitação e resposta e autenticação.
Juntos, esses arquivos definem o comportamento do agente e como ele interage com a API subjacente.
Para obter mais informações sobre plug-ins de API, consulte:
- Plug-ins de API para Microsoft 365 Copilot
- Como tornar um documento OpenAPI eficaz na extensão dos recursos do Copilot
Mapeamento de função no manifesto do plug-in
No manifesto do plug-in, cada função deve mapear para uma operationId correspondente na especificação OpenAPI. Isso garante que, quando o agente invocar uma função (por exemplo, createTask), o agente saiba qual endpoint de API chamar.
Os exemplos a seguir mostram o mapeamento no manifesto do plug-in e a função mapeada na especificação OpenAPI.
"functions": [
{
"name": "createTask",
"description": "Creates a new task in the specified task list."
}
]
paths:
/me/todo/lists/{listId}/tasks:
post:
operationId: createTask
summary: Create a new task
description: Creates a new task in the specified task list.
parameters:
Práticas recomendadas para instruções de agente
Escrever instruções eficazes é essencial para garantir que os agentes declarativos com plug-ins de API sejam bem-sucedidos. Para otimizar seu agente, aplique o mapeamento de função correto, use o encadeamento para permitir interações mais ricas e teste e refine iterativamente o comportamento do seu agente.
Aplique as seguintes práticas recomendadas ao escrever instruções para agentes declarativos com plug-ins de API:
- Evite instruções ambíguas ou negativas. Instruções contrastantes ou negativas podem introduzir ambiguidade e confundir o modelo. Concentre-se na definição de casos de uso válidos com exemplos positivos. Se for importante distinguir entre consultas válidas e inválidas, forneça critérios claros e exemplos que definam a resposta esperada do agente para cada uma.
- Usar exemplos Forneça exemplos claros para orientar o comportamento do agente. Por exemplo:
Entrada do usuário: Qual é o clima em Praga? Chamada do agente: getWeather(location="Prague") Entrada do usuário: "Preciso de um guarda-chuva amanhã?" Chamada do agente: getWeather(location=user_location, forecast="tomorrow")
Examine e teste as instruções. Teste instruções em vários cenários para verificar se o agente faz as chamadas de função corretas. Se, no teste, você descobrir que o agente invoca funções inesperadamente, revise a descrição da função na especificação OpenAPI e esclareça as instruções do agente para melhorar o mapeamento de intenção.
Instruções de design para conversas com várias voltas. Ao integrar plug-ins de API, crie suas instruções para que o agente lide com conversas de vários turnos.
Por exemplo, se a função exigir vários parâmetros, além de definir os parâmetros necessários na especificação OpenAPI, instrua o agente a coletar todos os parâmetros antes de fazer a chamada à API. Isso garante que o agente colete todas as informações necessárias em uma sequência lógica.
O exemplo a seguir mostra como instruir um agente meteorológico para conversas de várias etapas e o fluxo de agente resultante.
| Instruções para o agente | Fluxo de agentes |
|---|---|
| Se o usuário perguntar sobre o clima: - Peça ao usuário a localização. - Peça ao usuário o dia da previsão. - Peça ao usuário o sistema da unidade. - Chame getWeather apenas quando coletar todos os valores. |
Usuário: "Qual é o clima?" Agente: "Qual é a sua localização?" Usuário: "Londres" Agente: "Você prefere as informações meteorológicas em unidades métricas ou imperiais?" Usuário: "Métrica" Agente: "Você precisa do tempo para hoje ou previsão para amanhã?" Usuário: "Hoje" Agente: "Vou marcar o tempo para Londres hoje" O agente chama: getWeather(location="Londres", previsão="hoje", sistema="Métrica") |
Para obter práticas recomendadas gerais para instruções de agente, consulte Escreva instruções efetivas.
Encadeamento de chamadas de função em plug-ins de API
As chamadas de função de encadeamento permitem que os agentes declarativos combinem várias ações de API em um fluxo contínuo. As seções a seguir descrevem padrões comuns e como escrever instruções para cada um.
Encadeamento de chamadas de função com saída como parâmetro de entrada
Use o resultado de uma chamada à API como entrada para outra. Isso é útil quando o resultado da primeira função é necessário para executar a segunda função. Isso pode funcionar em todos os plug-ins.
No exemplo a seguir, um agente declarativo com a API do Clima e a API de Tarefas Pendentes cria uma tarefa pendente com dados da previsão do tempo.
| Instruções para o agente | Fluxo de agentes |
|---|---|
| Para obter o clima, sempre use a ação getWeather e, em seguida, crie uma tarefa com o título "temperature in" e adicione o local e a temperatura mencionados no clima ao título da tarefa. |
Usuário: "Obter o tempo em Praga" Agente: Chama getWeather (location="Praga", forecast="today") Agente: Usa os dados da primeira chamada para criar uma tarefa pendente createTask (title ="{weather output}") |
Encadeamento com base no histórico de conversas em um agente
Quando você usa o encadeamento com base no histórico de conversas, o agente usa respostas anteriores para lidar com ações de acompanhamento. Essa abordagem usa o histórico da conversa para manter o contexto.
No exemplo a seguir, um agente exclui uma tarefa pendente por nome.
| Instruções para o agente | Fluxo de agentes |
|---|---|
| 1. Quando o usuário pedir para listar todas as tarefas pendentes, chame getTasks para recuperar a lista de tarefas pendentes com título e ID. 2. Depois de listar as tarefas, se o usuário pedir para excluir uma tarefa, use a ID da resposta para chamar deleteTask. |
Usuário: "Mostrar todas as tarefas na pasta Tarefas?" Agent: alls getTasks (folderId="Tasks") e exibe todas as tarefas com IDs. Usuário: "Excluir tarefa do TaskMaster Pro" Agente: Usa as informações do histórico de conversas para encontrar o ID da tarefa pendente e exclui a tarefa chamando deleteTask. |
Encadeamento com conhecimento do SharePoint
O encadeamento de chamadas à API permite que um agente combine fontes de conhecimento e ações para criar fluxos de trabalho mais complexos.
No exemplo a seguir, um agente recupera dados de status do projeto do SharePoint e cria tarefas correspondentes no Microsoft To-Do para acompanhamento.
| Instruções para o agente | Fluxo de agentes |
|---|---|
| - Para obter os status do projeto, use o conhecimento do Sharepoint ProjectDeadlines. - Sempre crie uma tarefa para cada projeto usando a atualização de status para o título. |
Usuário: "Você pode fornecer uma atualização sobre o status de todos os projetos?" Agente: Extrai dados de status do projeto do SharePoint e usa createTask para gerar uma tarefa pendente para cada projeto. |
Encadeamento com interpretador de código
Também é possível encadear chamadas de API e integrar recursos adicionais, como um interpretador de código. Isso permite que um agente processe saídas de API dinamicamente para habilitar fluxos de trabalho mais avançados.
No exemplo a seguir, um agente cria um gráfico com base nos dados das tarefas pendentes.
| Instruções para o agente | Fluxo de agentes |
|---|---|
| Quando o usuário pedir para listar todas as tarefas, chame getTasks para recuperar a lista de tarefas pendentes com título e ID e também plote o gráfico para a saída. |
Usuário: "Recuperar todas as tarefas em Tarefas" Agente: Chama o getTasks (folderId="Tasks") e exibe todas as tarefas com IDs. Agente: Chama o interpretador de código para iniciar a geração do gráfico com base na saída da primeira chamada. |
Este exemplo também executa várias ações ao mesmo tempo. Isso é útil para iniciar uma série de ações relacionadas que não exigem várias entradas do usuário.
Quando o interpretador de código gera um arquivo (como uma imagem de gráfico ou uma planilha), o Copilot apresenta automaticamente um link de download na resposta, permitindo que os usuários salvem o arquivo localmente. Para obter mais informações, consulte Gerar arquivos para download.