Adicionar ferramentas a agentes personalizados

As ferramentas são os blocos modulares que permitem ao seu agente interagir com sistemas externos. As ferramentas expandem a funcionalidade do seu agente, permitindo que este realize várias ações em resposta a pedidos dos utilizadores ou acionadores autónomos. Cada ferramenta representa uma capacidade específica que o seu agente pode desempenhar. Por exemplo, pode equipar o seu agente com ferramentas que fazem coisas como:

• Enviar e-mails utilizando o conector do Office 365 Outlook
• Verificar as condições meteorológicas atuais e as previsões meteorológicas
• Ler e escrever dados do Dataverse
• Ler e publicar mensagens no Teams

Mecanismos para adicionar ferramentas

Pode expandir as capacidades do seu agente personalizado adicionando uma ou mais ferramentas. O seu agente pode utilizar ferramentas para responder automaticamente aos utilizadores, utilizando orquestração generativa. Também pode chamar ferramentas explicitamente a partir de um tópico.

Com a orquestração generativa (ativa por predefinição), o seu agente pode selecionar automaticamente a ferramenta ou o tópico mais adequado, ou pesquisar na base de dados de conhecimento, para responder a um utilizador. Este modo de orquestração cria uma experiência de conversação mais dinâmica e inteligente.

No modo clássico (orquestração generativa desativada), um agente só pode usar tópicos para responder ao utilizador. No entanto, ainda pode estruturar o seu agente para chamar ferramentas explicitamente a partir de tópicos.

Existem vários mecanismos disponíveis para adicionar ferramentas ao seu agente:

• Conector: Ligue-se a APIs e serviços proprietários utilizando Conectores do Power Platform para solicitar dados ou realizar ações.
  • Conector pré-criado: escolha entre uma seleção de ligações predefinidas para milhares de APIs populares de serviços da Microsoft e não Microsoft.
  • Conector personalizado: defina uma ligação a um serviço ou sistema personalizado para possibilitar opções de ferramentas personalizadas utilizando Conectores do Power Platform. O conector precisa de permissões de visualização e partilha para a organização para que o agente utilize o conector.
• Fluxo de agente: defina um fluxo de agente, incluindo uma ou mais ações a realizar.
• Pedido: pedido baseado num modelo de turno único que pode fazer referência ao conhecimento fornecido e gerar código para analisar dados.
• API REST: defina uma ligação a uma API REST e selecione um ou mais pontos finais e métodos da API para adicionar como ferramentas.
• Protocolo de Contexto de Modelos: ligue-se a um servidor MCP para aceder a ferramentas e recursos.
• Utilização do computador: permite que o seu agente interaja com qualquer sistema que tenha uma interface gráfica, para sites e aplicações de computador, selecionando botões, escolhendo menus e introduzindo texto em campos no ecrã.

Existem dois outros mecanismos que pode utilizar para adicionar comportamento semelhante a ferramentas ao seu agente:

• Competências: Contentor para um conjunto de ferramentas relacionadas.
• Ferramenta cliente: enviar uma atividade de evento ao cliente para que este realize uma ação e devolva uma resposta.

Para obter mais informações sobre capacidades e ferramentas cliente, consulte as ligações na secção Conteúdo relacionado.

Criar e adicionar uma nova ferramenta ao nível do agente

A criação de novas ferramentas diretamente no Copilot Studio simplifica o processo de desenvolvimento e garante a integração adequada com o seu agente. As ferramentas adicionadas a um agente estão disponíveis para orquestração automática ao longo das conversações do seu agente.

1. Abra o seu agente escolhendo Agentes no painel de navegação esquerdo e selecionando o seu agente na lista.

2. Vá para a página Ferramentas do agente.

3. Selecione Adicionar uma ferramenta.

4. No painel Adicionar ferramenta, selecione Nova ferramenta.

5. Selecione o tipo de ferramenta que quer adicionar da lista que é apresentada:

   • Pedido
   • Fluxo do agente
   • Utilização de computadores
   • Conector personalizado
   • Protocolo de Contexto de Modelos
   • API REST

   

6. Execute os passos de configuração específicos para o tipo de ferramenta que selecionou. Por exemplo, se selecionar Pedido, deve executar os seguintes passos:

   • Definir o modelo do pedido e as instruções
   • Especificar parâmetros de entrada
   • Configurar origens de conhecimento
   • Definir formato de resposta e restrições

7. Selecione Guardar ou Publicar, conforme aplicável, para criar a nova ferramenta.

8. Selecione Adicionar e configurar. A ferramenta é adicionada ao seu agente. A página de configuração da sua ferramenta é apresentada. Pode ver e fazer alterações à configuração da sua ferramenta aqui.

Pode ver a nova ferramenta na página Ferramentas do agente.

Ver e fazer alterações à configuração da ferramenta

Pode ver e editar a configuração da sua ferramenta a qualquer momento: aceda à página Ferramentas do seu agente e selecione a ferramenta da lista de ferramentas.

A página de configuração da sua ferramenta é aberta. Os detalhes são apresentados em três secções:

• Detalhes
• Entradas
• Conclusão

Para servidores MCP ligados como ferramentas de agente, a página de configuração é diferente dos outros tipos de ferramentas. A secção Detalhes é semelhante, mas em vez de Entradas e Conclusão, existem secções Ferramentas e Recursos com informações sobre as ferramentas e os recursos disponíveis para o servidor MCP. Para obter mais informações, consulte Ver ferramentas e recursos num servidor MCP existente.

Detalhes

A secção Detalhes permite configurar detalhes básicos sobre a sua ferramenta.

Aqui, pode ver e atualizar:

• Nome: o nome da ferramenta. Este nome aparece na lista de ferramentas para o seu agente. Escolha um nome que indique claramente a função da ferramenta.

• Descrição: uma descrição da ferramenta. A orquestração generativa baseia-se nesta descrição para determinar quando é que o seu agente deve utilizar a ferramenta. Escreva descrições claras e específicas, incluindo o que a ferramenta faz e quando deve ser utilizada.

• Detalhes adicionais:

  • Permitir que o agente decida de forma dinâmica quando utilizar a ferramenta: quando esta opção está selecionada, o agente pode utilizar a orquestração generativa para determinar quando deve utilizar a ferramenta. Se esta opção não estiver selecionada, o agente só utiliza a ferramenta quando esta é explicitamente chamada a partir de um tópico. (Por predefinição, esta opção é selecionada quando a orquestração generativa está ativada.)
  • Perguntar ao utilizador final antes de executar: na experiência de chat do utilizador final, peça confirmação ao agente antes de executar a ferramenta. Por predefinição, esta opção está definida como Não.
  • Autenticação: selecione se quer utilizar as credenciais do utilizador (Utilizador final) ou do criador (fornecidas pelo criador) para a ferramenta. Por predefinição, aplica-se a autenticação do utilizador.
  • Descrição: opcionalmente, pode adicionar uma descrição da ferramenta que o agente mostra ao utilizador quando pretende executar a ferramenta. Esta descrição permite ao utilizador saber o que lhe é pedido para autenticar.

Entradas

Aqui, pode ver e configurar as entradas para a sua ferramenta. As entradas são utilizadas para recolher informação do utilizador para preencher as entradas necessárias para a ferramenta. A informação é apresentada como uma tabela, uma linha para cada entrada.

Por predefinição, o valor da coluna Preencher utilizando para cada entrada está definido como Preencher dinamicamente com IA. O agente tenta extrair o valor do contexto disponível — por exemplo, da mensagem do utilizador. Se não for encontrado um valor adequado, gera uma pergunta para pedir um valor ao utilizador. Selecione Personalizar para aceder a personalizações mais detalhadas para recolha e preenchimento de entradas:

• Nome a apresentar e Descrição: a forma como a entrada é apresentada ao utilizador.
• Identificar como: a forma como a resposta do utilizador é interpretada, por exemplo, como uma cadeia de texto ou mapeada para uma entidade predefinida.
• Lógica de repetição: se o agente não identificar uma entidade na instrução do utilizador, pode fazer a pergunta novamente.
• Validação de entrada: configure um comportamento de validação extra na entrada do utilizador além da predefinição para o tipo de entidade.

Também pode optar por substituir uma entrada com um valor explícito em vez de deixar que o agente o extraia. Para definir uma substituição, defina Preencher utilizando como Valor personalizado e introduza um valor, selecione uma variável ou use uma fórmula Power Fx. Se uma entrada for substituída, o agente não pede um valor ao utilizador.

Conclusão

Aqui, pode selecionar o que quer que aconteça quando a ferramenta concluir a sua execução.

Pode fazer com que o agente gere automaticamente uma resposta contextual para um utilizador, com base na consulta e no resultado da ferramenta.

Em alternativa, pode optar por criar uma resposta específica e formatada para a sua ferramenta devolver. Pode inserir referências a variáveis de saída a partir da ferramenta utilizando o seletor de variáveis. Também pode utilizar fórmulas Power Fx para formatar a resposta.

Em Após a execução, selecione uma das opções diferentes para a forma como a ferramenta deve responder ao utilizador após a execução da ferramenta:

• Não responder (predefinição): o agente incorpora a saída da ferramenta na resposta
• Escrever a resposta com IA generativa: deixar a IA criar uma resposta contextual utilizando as saídas da ferramenta
• Enviar resposta específica: criar uma resposta baseada num modelo com inserção de variáveis
• Enviar um cartão adaptativo: criar respostas ricas e interativas com botões e ações

Também pode configurar quais as variáveis de saída a disponibilizar ao agente e a outras ferramentas.

Seleção de ferramentas e recolha de entradas

Quando define uma ferramenta no Copilot Studio, também fornece informações que descrevem o seu propósito. Esta informação permite ao agente identificar quando deve utilizar a ferramenta. A descrição da ferramenta também ajuda o orquestrador a utilizar IA generativa para gerar perguntas, conforme necessário, para recolher entradas. O agente pode utilizar perguntas para recolher informações que preencham as entradas necessárias para utilizar a ferramenta. Como resultado, não precisa de criar manualmente nós de questões para reunir todas as entradas necessárias, como entradas num fluxo. O orquestrador de agentes trata da recolha de entradas por si em runtime.

O agente considera vários fatores para determinar a seleção da ferramenta:

• Nome e descrição da ferramenta
• O contexto da conversação atual
• Intenção do utilizador derivada da sua mensagem
• Entradas e saídas disponíveis
• Utilização anterior da ferramenta na conversação

Quando se utiliza o modo generativo, por predefinição, as ferramentas devolvem as suas informações ao agente. Com a resposta da ferramenta, o agente pode gerar uma resposta contextual à consulta do utilizador. Em alternativa, pode instruir a sua ferramenta a responder sempre imediatamente, seja gerando uma mensagem ou criando uma mensagem explícita.

Chamar uma ferramenta existente a partir de um tópico

Pode chamar uma ferramenta explicitamente a partir de um tópico. Dependendo do seu caso de utilização, pode utilizar a sua ferramenta como parte de um tópico mais amplo, que utiliza mais nós. Ou, como no exemplo da meteorologia, adicionar um nó a um tópico pode ser tudo o que necessita.

Para chamar uma ferramenta a partir de um tópico:

1. No Copilot Studio, vá para a página Tópicos do agente que pretende editar.

2. Crie um novo tópico e dê-lhe um nome, por exemplo, Obter tempo.

3. Adicione Expressões acionadoras adequadas. Para continuar com o mesmo exemplo meteorológico do passo anterior, as expressões acionadoras podem incluir:

   • vai chover
   • previsão para hoje
   • obter meteorologia
   • como está o tempo

4. Selecione Adicionar nó (+) e, em seguida, selecione Adicionar uma ferramenta. Selecione a ferramenta de entre as ferramentas disponíveis. Existem três separadores que mostram diferentes tipos de ferramentas:

   • Ferramentas básicas
   • Conector
   • Ferramenta

   O seu nó de Ação foi agora adicionado ao seu tópico.

5. Selecione Guardar.

Informações do conector MCP

Para o conector MCP, pode ver os nomes e as descrições das ferramentas e recursos MCP que são disponibilizados pelo conector MCP. As informações sobre as ferramentas e os recursos são apresentadas numa tabela, com uma linha para cada ferramenta.

Considerações de autenticação para ferramentas

Algumas ferramentas exigem autenticação para funcionar corretamente, como o Pedido Dinâmico ou outras que chamam uma API do Dataverse. Uma configuração adequada da autenticação garante a segurança, mantendo uma experiência de utilizador tranquila.

As ferramentas são sempre executadas no runtime do agente no contexto do utilizador e não podem ser executadas a menos que a autenticação esteja ativada. São suportados dois tipos de métodos de autenticação:

• Credenciais do utilizador final: o agente utiliza as credenciais do utilizador para se autenticar no serviço. Este método garante que os utilizadores apenas acedem aos dados que estão autorizados a ver.
• Credenciais fornecidas pelo criador: o agente utiliza as credenciais do seu autor para se autenticar no serviço. Utilize este modo de autenticação para recursos partilhados ou quando os utilizadores não precisam de acesso individual.

Testar a ferramenta

Com a orquestração generativa, o orquestrador seleciona a sua ferramenta quando a considera relevante para uma consulta do utilizador.

Alternativamente, pode chamar uma ferramenta existente a partir de um tópico.

Ativar ou desativar uma ferramenta no agente

Pode ativar ou desativar uma ferramenta para o seu agente a partir da página de configuração da ferramenta. Desativar uma ferramenta bloqueia o agente de a utilizar, mas a ferramenta ainda está ligada ao agente e pode ser ativada novamente mais tarde. Quando adiciona uma ferramenta a um agente, esta é ativada por predefinição.

Para desativar uma ferramenta num agente:

1. Aceda ao seu agente e selecione a página Ferramentas do seu agente.
2. Selecione a ferramenta para aceder à página de configuração da ferramenta.
3. No topo da página de configuração, desative a ferramenta utilizando o seletor Ativado.
4. Selecione Guardar para aplicar a alteração.

A ferramenta continua a aparecer na lista de ferramentas do agente, mas já não está ativada.

Eliminar uma ferramenta do seu agente

Desativar uma ferramenta bloqueia a sua utilização, mas também lhe dá a flexibilidade de voltar a ativá-la mais tarde. Também pode remover uma ferramenta de forma mais permanente do seu agente. Para eliminar uma ferramenta do seu agente:

1. Aceda ao seu agente e selecione a página Ferramentas do seu agente.
2. Encontre a ferramenta na lista de ferramentas e faça pairar o cursor sobre o nome da ferramenta. Selecione os três pontos (...).
3. Selecione Eliminar. Será apresentada uma janela de confirmação.
4. Selecione Eliminar para remover a ferramenta.

A ferramenta desaparece da lista de ferramentas do agente.

Conteúdos relacionados

• Utilizar conectores
• Utilizar pedidos
• Usar fluxos de agente com o seu agente
• Protocolo de Contexto de Modelos (MCP)
• Adicionar ferramentas a partir de uma API REST
• Utilizar competências
• Ferramentas cliente
• Utilização do computador (pré-visualização)