Adicionar ferramentas a agentes personalizados

As ferramentas são blocos de construção que permitem ao seu agente interagir com sistemas externos. As ferramentas expandem o que o seu agente pode fazer, e o seu agente pode realizar várias ações em resposta a pedidos dos utilizadores ou a gatilhos 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 realizam tarefas como:

• Envie emails usando o conector Office 365 Outlook
• Verifique as condições e previsões meteorológicas atuais
• Ler e gravar dados do Dataverse
• Ler e publicar mensagens no Teams

Mecanismos para adicionar ferramentas a agentes

Você pode estender os recursos do seu agente personalizado adicionando uma ou mais ferramentas. Seu agente pode usar ferramentas para responder aos usuários automaticamente, usando orquestração generativa. Também pode chamar ferramentas explicitamente a partir de dentro de um tema.

Ao usar orquestração generativa (ativa por defeito), o seu agente pode selecionar automaticamente a ferramenta ou tema mais apropriado, ou pesquisar entre conhecimentos, 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 usuário. No entanto, ainda pode estruturar o seu agente para chamar ferramentas explicitamente a partir de tópicos.

Pode usar os seguintes mecanismos para adicionar ferramentas ao seu agente:

• Conector: Ligue-se a APIs e serviços proprietários usando os Power Platform Connectors para recolher dados ou realizar ações.
  • Conector pré-configurado: escolha entre uma seleção de ligações predefinidas para milhares de APIs populares, de serviços da Microsoft e de outros fornecedores.
  • Conector personalizado: Defina uma ligação a um serviço ou sistema personalizado para permitir opções de ferramentas personalizadas utilizando Power Platform Connectors. 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ã.

Também pode usar os seguintes mecanismos para adicionar comportamento semelhante a uma ferramenta ao seu agente:

• Azure Bot Service competências: Contentor para um conjunto de ferramentas relacionadas disponibilizadas através do Azure Bot Service.
• Ferramentas do cliente: Enviar uma atividade de evento ao cliente para que este realize uma ação e devolva uma resposta.

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

Criar 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 seu agente escolhendo Agentes no painel de navegação esquerdo e selecionando seu agente na lista.

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

3. Selecione Adicionar uma ferramenta.

4. Selecione o tipo de ferramenta que quer adicionar da lista:

   • Fluxo do agente
   • Prompt
   • Protocolo de contexto do modelo
   • Utilização do computador

   Para mostrar a lista completa, selecione Ver tudo. Surgem mais opções:

   • API REST
   • Conector personalizado

   Ver todas as alterações para Ver menos.

   

   Note

   Se a sua organização bloqueou uma ferramenta devido a políticas de dados, não pode selecioná-la. Saiba mais em Ferramentas bloqueadas pelas políticas da sua organização.

5. Execute as etapas de configuração específicas para o tipo de ferramenta selecionada. Por exemplo, se selecionar Prompt, execute os seguintes passos:

   • Defina as instruções do prompt
   • Selecione um modelo
   • Especificar parâmetros de entrada (selecionando + Adicionar conteúdo)

   Também pode obter ajuda digitando o campo Assistente de Prompts .

   Como alternativa, pode usar um modelo pré-definido para criar um prompt selecionando o modelo de prompt.

6. Selecione Salvar para criar a nova ferramenta.

7. Selecione Adicionar e configurar. A ferramenta é adicionada ao seu agente. A página de configuração da sua ferramenta é apresentada. Veja e faça alterações à configuração da sua ferramenta aqui.

A sua nova ferramenta aparece na página de Ferramentas do agente.

Ferramentas bloqueadas pelas políticas da sua organização

A sua organização pode usar políticas de governação para restringir que ferramentas e conectores estão disponíveis no Copilot Studio.

Quando uma política de dados bloqueia uma ferramenta, a ferramenta aparece desativada no painel de Adicionar ferramentas e não pode selecioná-la. Selecione o ícone junto à ferramenta desativada para ver por que motivo a ferramenta não está disponível.

A mensagem identifica a restrição de política que impede a utilização da ferramenta. Se precisar de acesso a uma ferramenta bloqueada, contacte o seu administrador.

Saiba mais em Configurar políticas de dados para agentes.

Visualize e faça alterações na configuração da ferramenta

Pode visualizar e editar a configuração da sua ferramenta a qualquer momento. Vai à página de Ferramentas do teu agente e seleciona 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
• Insumos
• Completion

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

Utilize a secção Detalhes para configurar os detalhes básicos da sua ferramenta.

Consulte e atualize as seguintes informações:

• 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 usada.

• Detalhes adicionais:

  • Permitir que o agente decida dinamicamente quando usar a ferramenta: Ao selecionar esta opção, o agente pode usar orquestração generativa para determinar quando usar a ferramenta. Se não selecionares esta opção, o agente só usa a ferramenta quando é explicitamente chamada a partir de um tópico. (Por predefinição, esta opção é selecionada quando a orquestração generativa está ativada.)
  • Pergunte ao usuário final antes de executar: na experiência de bate-papo do usuário final, peça confirmação ao agente antes de executar a ferramenta. Esta opção é definida como Não por padrã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, adicione uma descrição da ferramenta que o agente mostra ao utilizador quando quiser executar a ferramenta. Esta descrição permite ao utilizador saber o que lhe é pedido para autenticar.

Insumos

Visualiza e configura os inputs da tua ferramenta. Utilize os campos para recolher informações do utilizador e preencher os campos obrigatórios da ferramenta. A informação é apresentada como uma tabela, com uma linha para cada entrada.

Por padrão, o valor da coluna Preencher usando para cada entrada é definido como Preencher dinamicamente com IA. O agente tenta extrair o valor do contexto disponível — por exemplo, da mensagem do usuário. Se o agente não encontrar um valor apropriado, gera uma pergunta para pedir esse valor ao utilizador. Selecione Personalizar para acessar personalizações mais refinadas para coleta e preenchimento de entradas:

• Nome para exibição e Descrição: Como a entrada aparece para o usuário.
• Identificar como: Como a resposta do usuário é interpretada, por exemplo, como 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 usuário, ele poderá fazer a pergunta novamente.
• Validação de entrada: configure um comportamento de validação extra na entrada do usuário além do padrão para o tipo de entidade.

Você também pode optar por substituir uma entrada por um valor explícito em vez de permitir que o agente a 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 sobrescreveres uma entrada, o agente não pede um valor ao utilizador.

Completion

Seleciona o que queres que aconteça quando a ferramenta terminar de funcionar.

Você pode fazer com que o agente gere automaticamente uma resposta contextual para um usuário, com base em sua consulta e no resultado da ferramenta.

Como alternativa, você pode optar por criar uma resposta específica e formatada para que sua ferramenta retorne. Use o seletor de variáveis para inserir referências às variáveis de saída da ferramenta. Você também pode usar fórmulas Power Fx para formatar a resposta.

Em Após a execução, selecione como a ferramenta deve responder ao utilizador após a execução:

• Não responda (padrão): O agente incorpora a saída da ferramenta na sua resposta.
• Escreva a resposta com IA generativa: a IA cria uma resposta contextual usando os resultados da ferramenta.
• Enviar resposta específica: Criar uma resposta modelo com inserção de variáveis.
• Envie um cartão adaptativo: Crie respostas ricas e interativas com botões e ações.

Configure quais as variáveis de saída para disponibilizar ao agente e a outras ferramentas.

Seleção de ferramentas e recolha de entradas

Quando defines uma ferramenta no Copilot Studio, também forneces informação que descreve o seu propósito. Esta informação ajuda o agente a identificar quando deve usar 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ódulos de perguntas para agregar 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 atual da conversa
• Intenção do usuário derivada de sua mensagem
• Entradas e saídas disponíveis
• Utilização anterior da ferramenta na conversação

Ao usar o modo generativo, por padrão, as ferramentas retornam a informação ao agente. Com a resposta da ferramenta, o agente pode gerar uma resposta contextual à consulta do utilizador. Como alternativa, você pode instruir sua ferramenta a sempre responder imediatamente, gerando uma mensagem ou criando uma mensagem explícita.

Chamar uma ferramenta existente de dentro de um tópico

Você pode chamar uma ferramenta explicitamente de dentro de um tópico. Dependendo do teu caso de uso, podes usar a tua ferramenta como parte de um tópico mais amplo que utiliza múltiplos nós. Ou, como no exemplo seguinte, adicionar um único nó de ação (ferramenta) a um tema pode ser tudo o que precisa.

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

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

2. Cria um novo tema e dá-lhe um nome, como Obter o 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ões de hoje
   • Obter Meteorologia
   • Qual é o tempo

4. Selecione Adicionar nó (+) e, em seguida, selecione Adicionar uma ferramenta.

5. Selecione a ferramenta de entre as ferramentas disponíveis. Três separadores mostram diferentes tipos de ferramentas:

   • Ferramentas básicas
   • Connector
   • Tool

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

6. Selecione Guardar.

Informações do conector MCP

Para o conector MCP, pode consultar os nomes e descrições das ferramentas e recursos MCP que o conector MCP disponibiliza. A informação das ferramentas e recursos aparece numa tabela, com uma linha para cada ferramenta.

Considerações de autenticação para ferramentas

Algumas ferramentas requerem autenticação para funcionar corretamente, como o Dynamic Prompt ou outras ferramentas que chamam uma API Dataverse. Uma configuração adequada da autenticação garante a segurança, mantendo uma experiência de utilizador tranquila.

O agente executa ferramentas no respetivo ambiente de execução em contexto de utilizador. Não podes executar ferramentas a menos que a autenticação esteja ativada. O agente suporta dois tipos de métodos de autenticação:

• Credenciais do utilizador final: O agente utiliza as credenciais do utilizador para se autenticar com o 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.

Teste a sua ferramenta

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

Como alternativa, você pode chamar uma ferramenta existente de dentro de um tópico.

Ativar ou desativar uma ferramenta em seu 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 adicionas uma ferramenta a um agente, a ferramenta é ativada por defeito.

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, desligue a ferramenta usando a opção Ativar .
4. Selecione Guardar para aplicar as alterações.

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.

Limitações das ferramentas nos agentes

• Quando usas orquestração generativa, o orquestrador suporta até 128 ferramentas por agente. Para melhor desempenho e resultados, limite o número de ferramentas no seu agente a 25 a 30.
• Quando utiliza a orquestração multiagente com agentes subordinados, cada agente subordinado tem a sua própria orquestração e pode gerir o seu conjunto de até 128 ferramentas.