Adicionar ferramentas a agentes personalizados

Ferramentas são os blocos de construção que permitem ao agente interagir com sistemas externos. As ferramentas expandem a funcionalidade do agente, permitindo a ele realizar ações variadas em resposta a solicitações do usuário ou gatilhos autônomos. Cada ferramenta representa uma capacidade específica que o agente pode realizar. Por exemplo, você pode equipar o agente com ferramentas que fazem coisas como:

• Enviar emails usando o conector do Office 365 Outlook
• Verificar as condições e as previsões do tempo atuais
• Ler e gravar dados do Dataverse
• Ler e postar mensagens no Teams

Mecanismos para adicionar ferramentas

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 as ferramentas explicitamente de dentro de um tópico.

Com orquestração generativa (ativa por padrão), o agente pode selecionar automaticamente a ferramenta ou o tópico mais indicado, ou pesquisar o conhecimento, 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 projetar seu agente para chamar as ferramentas explicitamente de dentro dos tópicos.

Há vários mecanismos disponíveis para você adicionar ferramentas ao seu agente:

• Conector: conecte-se a APIs e serviços proprietários usando conectores do Power Platform para transferir dados ou realizar ações.
  • Conector predefinido: Escolha entre uma seleção de conexões predefinidas para milhares de APIs populares, de serviços Microsoft e não Microsoft.
  • Conector personalizado: Defina uma conexão com um serviço ou sistema personalizado para habilitar opções de ferramentas personalizadas usando conectores do Power Platform. O conector precisa de permissões de exibição e compartilhamento para que a organização do agente use 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 MCP: 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.

Há dois outros mecanismos que você pode usar para adicionar um comportamento semelhante a uma ferramenta ao seu agente:

• Habilidades: contêiner para um conjunto de ferramentas relacionadas.
• Ferramenta do cliente: envie uma atividade de evento para o cliente para que ele execute uma ação e retorne uma resposta.

Para obter mais informações sobre habilidades e ferramentas do cliente, consulte os links na seção Conteúdo relacionado.

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

A criação direta de novas ferramentas dentro do Copilot Studio simplifica o processo de desenvolvimento e garante a integração indevida ao 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. No painel Adicionar ferramenta, selecione Nova ferramenta.

5. Selecione o tipo de ferramenta que você deseja adicionar na lista exibida:

   • Solicitar
   • Fluxo de agente
   • Uso do computador
   • Conector personalizado
   • Protocolo de Contexto do Modelo
   • API REST

   

6. Realize as etapas de configuração específicas do tipo de ferramenta selecionado por você. Por exemplo, se selecionar Solicitação, você deverá realizar as seguintes etapas:

   • Definir o modelo de solicitação e as instruções
   • Especifique os parâmetros de entrada
   • Configurar fontes de conhecimento
   • Definir o formato da resposta e as restrições

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

8. Selecione Adicionar e configurar. A ferramenta é adicionada ao agente. A página de configuração da ferramenta é exibida. Você pode exibir e fazer alterações na configuração da ferramenta aqui.

Você pode ver a nova ferramenta na página Ferramentas do agente.

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

Você pode exibir e editar a configuração da ferramenta a qualquer momento: vá até a página Ferramentas do agente e selecione a ferramenta na lista.

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

• Detalhes
• Entradas
• Conclusão

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.

Detalhes

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

Aqui, você pode exibir e atualizar:

• Nome: o nome da ferramenta. Este nome é exibido na lista de ferramentas para o 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 o agente deve usar a ferramenta. Escreva descrições claras e específicas, inclusive o que a ferramenta faz e quando ela deve ser usada.

• Detalhes adicionais:

  • Permitir ao agente decidir dinamicamente quando usar a ferramenta: quando esta opção é selecionada, o agente pode usar orquestração generativa para determinar quando usar a ferramenta. Se essa opção não estiver selecionada, o agente só usará a ferramenta quando for explicitamente chamada de um tópico. (Por padrão, essa opção é selecionada quando a orquestração generativa está habilitada.)
  • Perguntar ao usuário final antes de executar: na experiência de chat 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 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 do usuário se aplica.
  • Descrição: você também pode adicionar uma descrição da ferramenta mostrada pelo agente ao usuário quando ele deseja executar a ferramenta. Esta descrição informa o usuário do que está sendo solicitado para se autenticar.

Entradas

Aqui, você pode exibir e configurar as entradas da ferramenta. As entradas são usadas para coletar informações do usuário a fim de preencher as entradas necessárias para a ferramenta. As informações são exibidas como uma tabela, uma linha para cada entrada.

Por padrão, o valor da coluna Preencher usando de 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 nenhum valor indicado for encontrado, uma pergunta será gerada para solicitar um valor ao usuário. Selecione Personalizar para acessar personalizações mais refinadas para coleta e preenchimento de entradas:

• Nome de exibição e Descrição: como a entrada é exibida para o usuário.
• Identificar como: a maneira 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 não identificar uma entidade na instrução do usuário, o agente poderá refazer a pergunta.
• 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 com um valor explícito, em vez de deixar o agente extraí-la. 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 uma entrada for substituída, o agente não solicitará um valor do usuário.

Conclusão

Aqui, você pode selecionar o que quer que aconteça quando a execução da ferramenta terminar.

Você pode fazer o agente gerar automaticamente uma resposta contextual para um usuário, baseada na consulta dele e no resultado da ferramenta.

Você também pode optar por criar uma resposta formatada específica para a ferramenta retornar. Você pode inserir referências para variáveis de saída da ferramenta usando o seletor de variáveis. Você também pode usar fórmulas Power Fx para formatar a resposta.

Em Após a execução, selecione uma das várias opções de como a ferramenta deve responder ao usuário após sua execução:

• Não responder (padrão): o agente incorpora a saída da ferramenta à resposta
• Escrever a resposta com IA generativa: deixe a IA criar uma resposta contextual usando as saídas de ferramenta
• Enviar resposta específica: criar um modelo de resposta com inserção de variável
• Enviar um cartão adaptável: criar respostas avançadas e interativas com botões e ações

Você também pode configurar quais variáveis de saída disponibilizar para o agente e outras ferramentas.

Seleção de ferramentas e coleção de entradas

Ao definir uma ferramenta no Copilot Studio, você também fornece informações que descrevem a finalidade. Essas informações permitem ao agente 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 processa a coleção de entradas para você em runtime.

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 da mensagem
• Entradas e saídas disponíveis
• Uso anterior da ferramenta na conversa

Durante o uso do modo generativo, por padrão, as ferramentas retornam às informações ao agente. Com a resposta da ferramenta, o agente pode gerar uma resposta contextual para a consulta do usuário. Você também pode instruir a ferramenta a sempre responder imediatamente, gerando uma mensagem ou criando uma mensagem explícita.

Chamar uma ferramenta existente dentro de um tópico

Você pode chamar explicitamente uma ferramenta de dentro de um tópico. Dependendo do caso de uso, convém usar a ferramenta como parte de um tópico mais abrangente, que usa mais nós. Ou, como no exemplo sobre o clima, a adição de um nó a um tópico pode ser tudo aquilo de que você precisa.

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

1. No Copilot Studio, acesse a página Tópicos do agente que você quer editar.

2. Crie um novo tópico e dê a ele um nome, por exemplo, Obter clima.

3. Adicione frases de gatilho indicadas. 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. Selecione a ferramenta dentre as disponíveis. Existem três guias mostrando diferentes tipos de ferramentas:

   • Ferramentas básicas
   • Conector
   • Ferramenta

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

5. Selecione Salvar.

Informações do conector MCP

Para o conector MCP, você pode exibir os nomes e as descrições das ferramentas e dos recursos MCP disponibilizados pelo conector MCP. As informações das ferramentas e dos recursos são exibidas em uma tabela, uma linha para cada ferramenta.

Considerações sobre autenticação para ferramentas

Algumas ferramentas exigem autenticação para funcionar corretamente, como a Solicitação dinâmica ou outras que chamam uma API do Dataverse. A configuração de autenticação indicada garante segurança enquanto mantém uma experiência de usuário tranquila.

As ferramentas são sempre executadas em runtime do agente no contexto do usuário e não podem ser executadas, a menos que a autenticação esteja habilitada. Dois tipos de métodos de autenticação são suportados:

• Credenciais de usuário final: o agente usa as credenciais do usuário para se autenticar com o serviço. Esse método garante que os usuários só acessem os dados para os quais tenham autorização para 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.

Testar sua ferramenta

Com orquestração generativa, o orquestrador seleciona a 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.

Ligue ou desligue uma ferramenta no 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 permanece ligada por padrão.

Para desligar uma ferramenta em um agente:

1. Vá até o agente e selecione a página Ferramentas do 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, desligue a ferramenta usando a alternância Habilitado.
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 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 do agente. Para excluir uma ferramenta do agente:

1. Vá até o agente e selecione a página Ferramentas do 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.

Conteúdo relacionado

• Usar conectores
• Usar solicitações
• Usar fluxos de agente com o agente
• Protocolo MCP
• Adicionar ferramentas de uma API REST
• Usar habilidades
• Ferramentas de cliente
• Uso do computador (versão preliminar)