Adicionar ferramentas a agentes personalizados

2025-06-17

As ferramentas são os blocos de construção que permitem que seu agente interaja com sistemas externos. As ferramentas expandem a funcionalidade do agente, permitindo que ele execute várias ações em resposta a solicitações de usuário 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 fazem coisas como:

Enviar emails usando o conector do Outlook do Office 365
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

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 a orquestração generativa (ativa por padrão), seu agente pode selecionar automaticamente a ferramenta ou o tópico mais apropriado, ou pesquisar em todo 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 só pode usar tópicos para responder ao usuário. No entanto, você ainda pode criar seu agente para chamar ferramentas explicitamente de dentro dos tópicos.

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

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 do Power Platform.
Fluxo do agente: defina um fluxo de agente, incluindo uma ou mais ações a serem executadas.
Solicitação: solicitação baseada em modelo de uma única vez que pode referenciar o conhecimento oferecido por você.
Conexão da API REST: defina uma conexão com uma API REST e selecione um ou mais pontos de extremidade de API e métodos a serem adicionados como ferramentas.
Ferramenta MCP (Protocolo de Contexto de Modelo): conecte-se a um servidor MCP para acessar ferramentas.
Agente de uso do computador (versão prévia): permite que seu agente interaja 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.

Quando falamos sobre ferramentas neste artigo e nesta seção da documentação, queremos dizer um dos mecanismos neste grupo. Esses tipos de ferramentas podem ser adicionados ao seu agente e configurados de maneiras semelhantes.

Há dois outros mecanismos que você pode usar para adicionar comportamento semelhante ao de uma ferramenta ao seu agente.

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

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

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.

Abra seu agente escolhendo Agentes no painel de navegação esquerdo e selecionando seu agente na lista.
Vá até a página Ferramentas do agente.
Selecione Adicionar uma ferramenta.
No painel Adicionar ferramentas , selecione Nova ferramenta.
Selecione o tipo de ferramenta que você deseja adicionar na lista que aparece:
- Prompt: criar ferramentas de análise e geração de texto habilitadas para IA
- Fluxo do agente: criar processos de várias etapas com lógica condicional
- Uso do computador: habilitar a automação de GUI para sistemas herdados
- Conector personalizado: conectar-se a APIs e serviços proprietários
- API REST: integração direta com serviços Web
Execute as etapas de configuração específicas para o tipo de ferramenta selecionada. Por exemplo, se você selecionar Prompt, deverá executar as seguintes etapas:
- Definir o modelo de prompt e as instruções
- Especificar parâmetros de entrada
- Configurar fontes de conhecimento
- Definir o formato e as restrições de resposta
Teste a configuração da ferramenta usando o painel de visualização para garantir que ela funcione conforme o esperado.
Selecione Salvar para criar a nova ferramenta.
Selecione Adicionar ao agente para adicionar a ferramenta ao seu agente. 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á para a página Ferramentas do agente e selecione a ferramenta na lista de ferramentas.

A página de detalhes da Ferramenta é aberta, mostrando a configuração da ferramenta. Os detalhes são exibidos em três seções:

Detalhes
Entradas
Conclusão (Ferramentas para conectores MCP)

Detalhes

A seção Detalhes permite que você configure detalhes básicos sobre sua ferramenta.

Aqui, você pode exibir e atualizar:

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: quando essa opção é selecionada, o agente pode usar a orquestração generativa para determinar quando usar a ferramenta. Se essa opção não estiver selecionada, o agente usará apenas a ferramenta quando ela for explicitamente chamada a partir de 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 as credenciais do usuário ou do criador devem ser usadas para a ferramenta. Por padrão, a autenticação de usuário se aplica.
- Descrição: opcionalmente, você pode adicionar uma descrição da ferramenta que é mostrada ao usuário quando a ferramenta é executada. Essa descrição permite que o usuário saiba o que precisa autenticar.

Entradas

Aqui, você pode exibir e configurar as entradas para sua ferramenta. As entradas são usadas para coletar informações do usuário para 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 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 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 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 uma entrada for substituída, o agente não solicitará um valor ao usuário.

Conclusão

Aqui, você pode selecionar o que deseja que aconteça quando a ferramenta terminar de ser executada.

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. Você pode inserir referências a variáveis de saída da ferramenta usando o seletor de variáveis. Você também pode usar fórmulas do Power Fx para formatar a resposta.

Depois de executar, selecione uma das poucas opções diferentes de como a ferramenta deve responder ao usuário após a execução da ferramenta:

Não responda (padrão): o agente incorpora a saída da ferramenta em sua resposta
Escreva a resposta com IA gerativa: permitir que a IA crie uma resposta contextual usando as saídas da ferramenta
Enviar resposta específica: criar uma resposta com modelo 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 coleta de dados

Ao definir uma ferramenta no Copilot Studio, você também fornece informações que descrevem sua finalidade. Essas informações permitem que o agente identifique quando usar a ferramenta e também use a IA generativa para gerar perguntas. Essas perguntas são usadas para coletar informações para preencher as entradas necessárias para executar 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. A coleta de entrada é manipulada para você em tempo de execução.

O agente usa vários 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 de ferramenta anterior na conversa

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

Dica

Ao usar perguntas geradas de uma ferramenta, informe aos usuários que parte da conversa é gerada pela IA.

Por exemplo, adicione uma mensagem extra no tópico do sistema Início da Conversa . Este tópico determina a mensagem mostrada aos usuários quando uma nova conversa é iniciada.

Chamar uma ferramenta existente de 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 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:

No Copilot Studio, acesse a página Tópicos do agente que você quer editar.
Crie um novo tópico e nomeie-o como Obter clima.
Adicione as seguintes Frases de gatilho:
- vai chover
- previsão de hoje
- obter clima
- como está o clima
Selecione Adicionar nó (+) e, em seguida, escolha Adicionar uma ferramenta. Selecione a ferramenta nas ferramentas disponíveis. Há três guias mostrando diferentes tipos de ferramentas:
- Ferramentas básicas
- Conector
- Ferramenta
O nó Ação agora foi adicionado ao tópico.
Selecione Salvar.

Ferramentas (somente conectores MCP)

Em Ferramentas, você pode exibir os nomes e descrições das ferramentas disponíveis para o conector MCP. As ferramentas são exibidas em uma tabela, uma linha para cada ferramenta. Para cada ferramenta, você pode ver:

Nome e versão da ferramenta
Parâmetros de entrada e saída
Tempo de execução estimado
Estatísticas de uso

Considerações de autenticação para ferramentas

Algumas ferramentas exigem autenticação para funcionar corretamente, como o Prompt Dinâmico ou outras 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.

As ferramentas são sempre executadas no 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:

Autenticação do usuário: 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.
Autenticação do autor do Copilot: o agente usa as credenciais do autor do copiloto para se autenticar com o serviço. Use esse modo de autenticação para recursos compartilhados ou quando os usuários não precisarem de acesso individual.

Teste sua ferramenta

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

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

Compartilhar via