Nota
O acesso a esta página requer autorização. Pode tentar iniciar sessão ou alterar os diretórios.
O acesso a esta página requer autorização. Pode tentar alterar os diretórios.
Os agentes declarativos adaptam Microsoft 365 Copilot para atender às necessidades específicas de uma organização. Você pode adicionar ações personalizadas por meio de plug-ins de API. Para cenários pró-código suportados, recomenda-se o Work IQ Dev Tools . Essas integrações permitem que seu agente consulte e interaja com os dados de uma organização por meio de APIs; eles não são os arquivos de instrução reutilizáveis descritos em Habilidades como recursos de plugin.
Este artigo descreve a arquitetura do agente e fornece práticas recomendadas para escrever instruções para agentes declarativos que incluem plug-ins de API.
Principais componentes de agentes declarativos com plugins de API
Os agentes declarativos que chamam plug-ins de API incluem vários componentes que garantem integração e funcionalidade eficazes. Compreender esta arquitetura irá ajudá-lo a projetar o seu agente de forma eficaz. A arquitetura inclui os seguintes componentes:
- Manifesto do aplicativo - Descreve como o aplicativo é configurado e faz referência ao manifesto do agente declarativo.
- Manifesto do agente declarativo - Define a configuração do agente, incluindo instruções, recursos, iniciadores de conversa e ações. Referencia o manifesto do plugin.
- 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 pontos de extremidade 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 MCP e API para agentes declarativos
- Como tornar um documento OpenAPI eficaz para expandir as capacidades do Copilot
Mapeamento de funções no manifesto do plug-in
No manifesto do plugin, cada função deve mapear para um operationId correspondente na especificação OpenAPI. Isso garante que quando o agente invoca uma função (por exemplo, createTask), o agente sabe qual ponto de extremidade da 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:
Melhores práticas para instruções do agente
Escrever instruções eficazes é essencial para garantir que 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 habilitar interações mais avançadas e teste e refine iterativamente o comportamento do 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 e exemplos claros que definam a resposta esperada do agente para cada uma.
- Exemplos de utilização Forneça exemplos claros para orientar o comportamento do agente. Por exemplo:
Entrada do usuário: Qual é o tempo em Praga? Chamada do agente: getWeather(location="Praga") Entrada do utilizador: "Preciso de um guarda-chuva amanhã?" Chamada do agente: getWeather(location=user_location, forecast="tomorrow")
Reveja e teste as instruções. Instruções de teste em vários cenários para verificar se o agente faz as chamadas de função corretas. Se no teste você achar 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 estrutura para conversas com vários turnos. Ao integrar plug-ins de API, projete suas instruções para que o agente lide com conversas de vários turnos.
Por exemplo, se a função requer 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 de meteorologia para conversas de vários turnos e o fluxo de agente resultante.
| Instruções para o agente | Fluxo de agente |
|---|---|
| Se o usuário perguntar sobre o tempo: - Pergunte ao usuário para a localização. - Peça ao usuário o dia da previsão. - Peça ao usuário o sistema da unidade. - Só ligue para getWeather quando recolher todos os valores. |
Utilizador: "Qual é o clima?" Agente: "Qual é a sua localização?" Usuário: "London" Agente: "Você prefere as informações meteorológicas em unidades métricas ou imperiais?" Utilizador: "Metric" Agente: "Precisa do tempo para hoje ou da previsão para amanhã?" Usuário: "Hoje" Agente: "Vou marcar o tempo para Londres para hoje" O agente chama: getWeather(location="London", forecast="today", system="Metric") |
Para obter práticas recomendadas gerais para instruções de agente, consulte Escrever instruções eficazes.
Encadeando chamadas de função em plug-ins de API
As chamadas de função de encadeamento permitem que agentes declarativos combinem várias ações de API em um fluxo contínuo. As secções seguintes descrevem padrões comuns e como escrever instruções para cada um.
Encadeando chamadas de função com saída como parâmetro de entrada
Utilize o resultado de uma chamada de API como entrada para outra. Isto é útil quando o resultado da primeira função é necessário para executar a segunda função. Isto pode funcionar em vários plugins.
No exemplo seguinte, um agente declarativo com a API de Meteorologia e a API de Tarefas cria uma tarefa a fazer com dados da previsão meteorológica.
| Instruções para o agente | Fluxo de agente |
|---|---|
| Para obter a previsão meteorológica, utilize sempre a ação obterMeteorologia , crie uma tarefa com o título "temperatura em" e, em seguida, adicione a localização e a temperatura mencionadas na meteorologia ao título da tarefa. |
Utilizador: "Get the weather in Prague" Agent: Calls getWeather (location="Prague", forecast="today") Agent: Usa os dados da primeira chamada para criar uma tarefa de tarefas createTask (title ="{weather output}") |
Encadeamento com base no histórico de conversas dentro de um agente
Quando você usa o encadeamento com base no histórico de conversa, o agente usa respostas anteriores para lidar com ações de acompanhamento. Esta abordagem utiliza o histórico de conversações para manter o contexto.
No exemplo a seguir, um agente exclui uma tarefa pelo nome.
| Instruções para o agente | Fluxo de agente |
|---|---|
| 1. Quando o utilizador pedir para listar todas as tarefas, chame getTasks para obter a lista de tarefas com título e ID. 2. Depois de listar as tarefas, se o usuário pedir para excluir uma tarefa, use o ID da resposta para chamar deleteTask. |
Utilizador: "Mostrar todas as tarefas na pasta Tarefas?" Agente: alls getTasks (folderId="Tasks") e exibe todas as tarefas com IDs. Utilizador: "Delete TaskMaster Pro to-do" Agent: usa as informações do histórico de conversas para encontrar o ID para a tarefa e exclui a tarefa chamando deleteTask. |
Encadeamento com conhecimentos do SharePoint
Encadear chamadas de API permite que um agente combine fontes de conhecimento e ações para projetar fluxos de trabalho mais complexos.
No exemplo seguinte, um agente obtém dados de status de projetos a partir do SharePoint e cria tarefas correspondentes no Microsoft To-Do para controlo.
| Instruções para o agente | Fluxo de agente |
|---|---|
| - Para obter status do projeto, use o conhecimento do Sharepoint ProjectDeadlines. - Crie sempre uma tarefa para cada projeto usando status atualização para o título. |
Usuário: "Você pode fornecer uma atualização sobre o status de todos os projetos?" Agente: Obtém dados de status de projeto do SharePoint e, em seguida, utiliza createTask para gerar uma tarefa a fazer 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 seguinte, um agente cria um gráfico com base nos dados nas tarefas pendentes.
| Instruções para o agente | Fluxo de agente |
|---|---|
| Quando o utilizador pedir para listar todas as tarefas, chame getTasks para obter a lista de tarefas com título e ID e desenhe também o gráfico para o resultado. |
Utilizador: "Recuperar todas as tarefas em Tarefas" Agent: chama o getTasks (folderId="Tasks") e exibe todas as tarefas com IDs. Agente: Interpretador de código de chamadas para iniciar a geração de gráficos com base na saída da primeira chamada. |
Este exemplo também executa várias ações ao mesmo tempo. É útil para iniciar uma série de ações relacionadas que não exigem múltiplas entradas do utilizador.
Quando o interpretador de código gera um ficheiro (como uma imagem de gráfico ou uma folha de cálculo), o Copilot apresenta automaticamente uma ligação de transferência na resposta, permitindo aos utilizadores guardar o ficheiro localmente. Para obter mais informações, consulte Gerar arquivos para download.