Adicionar ferramentas a agentes personalizados

Ferramentas são blocos de construção que permitem que seu agente interaja com sistemas externos. As ferramentas ampliam o que seu agente pode fazer, e ele pode realizar várias ações em resposta a solicitações de usuários ou gatilhos autônomos. Cada ferramenta representa uma funcionalidade específica que seu agente pode executar. Por exemplo, você pode equipar seu agente com ferramentas que realizam tarefas como:

• Envie e-mails usando o conector Office 365 Outlook
• Verificar as previsões e as condições climáticas atuais
• Ler e gravar dados do Dataverse
• Ler e postar mensagens no Teams

Mecanismos para adicionar ferramentas aos agentes

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

Ao usar orquestração generativa (ativa por padrão), seu agente pode selecionar automaticamente a ferramenta ou tema mais apropriado, ou pesquisar entre conhecimentos, para responder a um usuário. Esse modo de orquestração cria uma experiência de conversa mais dinâmica e inteligente.

No modo clássico (orquestração generativa desativada), um agente pode usar apenas tópicos para responder ao usuário. No entanto, você ainda pode configurar seu agente para invocar ferramentas explicitamente dentro dos tópicos.

Você pode usar os seguintes mecanismos para adicionar ferramentas ao seu agente:

• Conector: Conecte-se a APIs e serviços proprietários usando os Power Platform Connectors para captar dados ou realizar ações.
  • Conector predefinido: escolha entre uma seleção de conexões predefinidas para milhares de APIs populares de serviços da Microsoft e não da Microsoft.
  • Conector personalizado: Defina uma conexão com um serviço ou sistema personalizado para habilitar opções de ferramentas personalizadas usando conectores Power Platform. O conector precisa de permissões de exibição e compartilhamento na organização para que o agente possa usar o conector.
• Fluxo do agente: defina um fluxo do agente, inclusive uma ou mais ações a serem realizadas.
• Solicitação: solicitação baseada em modelo de turno único capaz de referenciar o conhecimento oferecido e gerar o código para analisar dados.
• API REST: defina uma conexão com uma API REST, e selecione um ou mais pontos de extremidade e métodos de API a serem adicionados como ferramentas.
• Protocolo de Contexto de Modelo: conecte-se a um servidor MCP para ter acesso a ferramentas e recursos.
• Uso do computador: permite ao agente interagir com qualquer sistema que tenha uma interface gráfica do usuário, para sites e aplicativos da área de trabalho, selecionando botões, escolhendo menus e inserindo texto em campos na tela.

Você também pode usar os seguintes mecanismos para adicionar comportamentos semelhantes a ferramentas ao seu agente:

• Habilidades do Azure Serviço de Bot: Container para um conjunto de ferramentas relacionadas disponibilizado por meio do Azure Serviço de Bot.
• Ferramentas do cliente: Envie uma atividade de evento ao cliente para que o cliente execute uma ação e retorne uma resposta.

Criar e adicionar uma nova ferramenta no 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 seu agente. As ferramentas adicionadas a um agente estão disponíveis para orquestração automática ao longo das conversas do agente.

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

2. Vá até a página Ferramentas do agente.

3. Selecione Adicionar uma ferramenta.

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

   • Fluxo de agente
   • Prompt
   • Protocolo de contexto de modelo
   • Uso do computador

   Para mostrar a lista completa, selecione Ver tudo. Mais opções aparecem:

   • REST API
   • Conector personalizado

   Veja todas as mudanças para Veja menos.

   

   Note

   Se sua organização bloqueou uma ferramenta devido a políticas de dados, você 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 você selecionar Prompt, execute os seguintes passos:

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

   Você também pode receber ajuda digitando no campo Prompt assistant.

   Como alternativa, você pode usar um modelo predefinido para criar um prompt ao selecionar 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 ferramenta é exibida. Veja e faça alterações na configuração da sua ferramenta aqui.

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

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

Sua organização pode usar políticas de governança para restringir quais ferramentas e conectores estão disponíveis no Copilot Studio.

Quando uma política de dados bloqueia uma ferramenta, ela aparece desativada no painel de Adicionar ferramenta e você não pode selecioná-la. Selecione o ícone ao lado da ferramenta desativada para ver por que a ferramenta não está disponível.

A mensagem identifica a restrição de política que impede o uso da ferramenta. Se precisar de acesso a uma ferramenta bloqueada, entre em contato com seu administrador.

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

Exibir e fazer alterações na configuração da ferramenta

Você pode visualizar e editar a configuração da sua ferramenta a qualquer momento. Vá até a página de Ferramentas do seu agente e selecione a ferramenta na lista de ferramentas.

A página de configuração da ferramenta abre. Os detalhes são exibidos em três seções:

• Details
• Entradas
• Completion

Para servidores MCP conectados como ferramentas de agente, a página de configuração é diferente de outros tipos de ferramenta. A seção Detalhes é semelhante, mas, em vez de Entradas e Conclusão, há seções Ferramentas e Recursos com informações sobre ferramentas e recursos disponíveis para o servidor MCP. Para obter mais informações, consulte Exibir ferramentas e recursos em um servidor MCP existente.

Details

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

Veja e atualize as seguintes informações:

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

• Descrição: uma descrição da ferramenta. A orquestração generativa depende dessa descrição para determinar quando seu agente deve usar a ferramenta. Escreva descrições claras e específicas, incluindo o que a ferramenta faz e quando ela deve ser usada.

• Detalhes adicionais:

  • Permitir que o agente decida dinamicamente quando usar a ferramenta: Ao selecionar essa opção, o agente pode usar orquestração generativa para determinar quando usar a ferramenta. Se você não selecionar essa opção, o agente só usa a ferramenta quando ela é explicitamente chamada em um tópico. (Por padrão, essa opção é selecionada quando a orquestração generativa está habilitada.)
  • Pergunte ao usuário final antes de executar: na experiência de chat do usuário final, peça ao agente a confirmação antes de executar a ferramenta. Essa opção é definida como Não por padrão.
  • Autenticação: selecione se você deseja usar as credenciais do usuário (usuário final) ou do fabricante (fornecidas pelo fabricante) para a ferramenta. Por padrão, a autenticação de usuário se aplica.
  • Descrição: Opcionalmente, adicione uma descrição da ferramenta que o agente mostra ao usuário quando quiser executar a ferramenta. Essa descrição permite que o usuário saiba o que precisa autenticar.

Entradas

Visualize e configure as entradas da sua ferramenta. Use as entradas para coletar informações do usuário e preencher as entradas necessárias para a ferramenta. As informações são exibidas 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, ele gera uma pergunta para pedir ao usuário um valor. Selecione Personalizar para acessar personalizações mais refinadas para coleta e preenchimento de entrada:

• Nome de exibição e Descrição: como a entrada aparece para o usuário.
• Identifique como: como a resposta do usuário é interpretada, por exemplo, como cadeia de caracteres 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 o 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 usando como Valor personalizado e insira um valor, selecione uma variável ou use uma fórmula do Power Fx. Se você sobrescreve uma entrada, o agente não pede um valor ao usuário.

Completion

Selecione o que você quer que aconteça quando a ferramenta terminar de rodar.

Você pode fazer o agente gerar automaticamente uma resposta contextual para um usuário, baseada na consulta dele 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 do Power Fx para formatar a resposta.

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

• Não responda (padrão): o agente incorpora a saída da ferramenta em sua resposta.
• Escreva a resposta com IA generativa: a IA cria uma resposta contextual usando os resultados da ferramenta.
• Enviar resposta específica: Elabore 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 variáveis de saída disponibilizar ao agente e outras ferramentas.

Seleção de ferramentas e coleta de dados

Ao definir uma ferramenta no Copilot Studio, você também fornece informações que descrevem sua finalidade. Essas informações ajudam o agente a identificar quando usar a ferramenta. A descrição da ferramenta também ajuda o orquestrador a usar IA generativa para gerar perguntas, conforme necessário, para coletar entradas. O agente pode usar perguntas para coletar informações e preencher as entradas necessárias para usar a ferramenta. Como resultado, não é necessário criar nós de pergunta manualmente para reunir todas as entradas necessárias, como as entradas em um fluxo. O orquestrador do agente realiza a coleta de dados para você em tempo de execução.

O agente leva em consideração diversos fatores para determinar a seleção da ferramenta:

• O nome e a descrição da ferramenta
• O contexto da conversa atual
• Intenção do usuário derivada de sua mensagem
• Entradas e saídas disponíveis
• Uso anterior da ferramenta na conversa

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

Chamar uma ferramenta existente dentro de um tópico

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

Para chamar uma ferramenta de dentro de um tópico:

1. No Copilot Studio, acesse a página Topics do agente que você deseja editar.

2. Crie um novo tema e dê um nome, como Get Weather.

3. Adicione frases de gatilho apropriadas. Para continuar com o mesmo exemplo do clima da etapa anterior, entre as frases de gatilho podem estar:

   • vai chover
   • previsão de hoje
   • obter clima
   • como está o clima

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

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

   • Ferramentas básicas
   • Conector
   • Tool

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

6. Clique em Salvar.

Informações do conector MCP

Para o conector MCP, você pode visualizar os nomes e descrições das ferramentas e recursos MCP que o conector MCP disponibiliza. As informações para as ferramentas e recursos aparecem em uma tabela, com uma linha para cada ferramenta.

Considerações sobre autenticação para ferramentas

Algumas ferramentas exigem autenticação para funcionar corretamente, como o Dynamic Prompt ou outras ferramentas que chamam uma API do Dataverse. A configuração de autenticação adequada garante a segurança, mantendo uma experiência suave do usuário.

O agente executa ferramentas em seu tempo de execução no contexto do usuário. Você não pode rodar ferramentas a menos que a autenticação esteja ativada. O agente suporta dois tipos de métodos de autenticação:

• Credenciais do usuário final: O agente usa as credenciais do usuário para autenticar com o serviço. Esse método garante que os usuários acessem apenas os dados que estão autorizados a ver.
• Credenciais fornecidas pelo criador: o agente usa as credenciais do autor para se autenticar usando o serviço. Use esse modo de autenticação para recursos compartilhados ou quando usuários não precisam de acesso individual.

Teste sua ferramenta

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

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

Ative ou desative uma ferramenta no seu agente

Você pode ligar ou desligar uma ferramenta para o agente na página de configuração da ferramenta. Desligar uma ferramenta bloqueia o uso do agente, mas a ferramenta ainda está conectada ao agente e poderá ser reativada depois. Quando você adiciona uma ferramenta a um agente, ela é ativada por padrão.

Para desativar uma ferramenta em um agente:

1. Vá até o seu agente e selecione a página Ferramentas do seu agente.
2. Selecione a ferramenta para ir até a página de configuração da ferramenta.
3. No topo da página de configuração, desative a ferramenta usando o alternador Enabled.
4. Selecione Salvar para aplicar a alteração.

A ferramenta continua sendo exibida na lista de ferramentas do agente, mas não está mais ligada.

Excluir uma ferramenta do seu agente

O desligamento de uma ferramenta bloqueia o uso, mas também lhe dá a flexibilidade para religá-la depois. Você também pode remover uma ferramenta de maneira mais permanente de seu sistema. Para excluir uma ferramenta do agente:

1. Vá até o seu agente e selecione a página Ferramentas do seu agente.
2. Encontre a ferramenta na lista e focalize o nome da ferramenta. Selecione os três pontos (...).
3. Selecione Excluir. Uma janela de confirmação é aberta.
4. Selecione Excluir para remover a ferramenta.

A ferramenta desaparece da lista de ferramentas do agente.

Limitações das ferramentas em agentes

• Quando você usa orquestração generativa, o orquestrador suporta até 128 ferramentas por agente. Para melhor desempenho e resultados, limite o número de ferramentas do seu corretor a 25 a 30.
• Quando você usa a orquestração multiagente com agentes filhos, cada agente filho tem sua própria orquestração e pode gerenciar seu próprio conjunto de até 128 ferramentas.