Agentes do Microsoft Copilot com Plugins: Ordem de Invocação de Ações

Ao criar um agente do Copilot que usa vários plugins, a ordem em que as ações são invocadas pode gerar resultados inesperados ou erros. O Copilot nem sempre executa as ações dos plugins na sequência definida no manifesto ou no fluxo da conversa. Em vez disso, o orquestrador avalia dependências, intenção do usuário e pontuações de confiança para decidir qual ação chamar primeiro. Este artigo explica por que a ordem de invocação de ações é importante, como o Copilot a determina e o que você pode controlar para obter um comportamento previsível do seu agente.

Como o Copilot Decide Qual Ação do Plugin Invocar Primeiro

O Copilot usa um orquestrador central para processar solicitações dos usuários. Quando um prompt do usuário corresponde a várias ações de plugins, o orquestrador não as executa simplesmente na ordem em que aparecem no manifesto. Em vez disso, ele constrói um grafo de dependências com base em três fatores:

Resolução de Dependências

Se a Ação B requer um valor de saída que a Ação A produz, o orquestrador executa a Ação A primeiro. Por exemplo, um plugin que pesquisa um banco de dados por um ID de cliente deve ser concluído antes que um plugin que recupera o histórico de pedidos desse cliente possa ser executado. O orquestrador lê as seções outputs e inputs da descrição OpenAPI de cada ação para encontrar essas dependências automaticamente.

Correspondência de Intenção do Usuário

O orquestrador pontua cada ação em relação à solicitação em linguagem natural do usuário. A ação com a maior pontuação de confiança é executada primeiro, mesmo que apareça depois no manifesto. Isso pode causar efeitos colaterais se uma ação modificar dados dos quais outra ação depende.

Contexto da Conversa

Se o usuário já forneceu informações na mesma conversa, o orquestrador pode pular uma ação que normalmente seria executada primeiro. Por exemplo, se o usuário disse “Mostrar meus pedidos” e depois “Cancelar o último”, o orquestrador pode chamar a ação de cancelamento diretamente sem reexecutar a ação de pesquisa, usando o ID do pedido da rodada anterior.

Passos para Definir e Testar a Ordem de Invocação de Ações

Você não pode forçar uma ordem sequencial estrita para todos os cenários, mas pode aumentar a previsibilidade configurando dependências e gatilhos corretamente. Siga estes passos para configurar e verificar a ordem de invocação dos plugins do seu agente do Copilot.

1. Abra o manifesto do plugin no Copilot Studio
   Vá para Copilot Studio > Agentes > selecione seu agente > Plugins > selecione o plugin que deseja configurar. O arquivo de manifesto está listado na guia Ações. Clique no nome da ação para ver sua descrição OpenAPI.
2. Defina esquemas de entrada e saída para cada ação
   Na descrição OpenAPI, adicione uma seção outputs com uma propriedade nomeada que outra ação possa referenciar. Por exemplo, uma ação chamada searchCustomer pode gerar customerId. Em seguida, em createOrder, adicione uma seção inputs que exija customerId. O orquestrador detectará essa dependência e executará searchCustomer primeiro.
3. Adicione restrições de invocação ao manifesto
   No JSON do manifesto do plugin, localize o array triggers. Para cada ação, você pode adicionar um objeto constraints com um campo after que lista o nome da ação que deve vir antes. Exemplo: "constraints": { "after": ["searchCustomer"] }. Isso informa ao orquestrador para executar a ação atual somente após searchCustomer ser concluída.
4. Teste a sequência com uma simulação de conversa
   No Copilot Studio, abra o painel de Teste e digite um prompt que acione ambas as ações. Observe os logs no painel de Diagnóstico. Os logs mostram cada invocação de ação em tempo real com um carimbo de data/hora. Se a ordem estiver errada, os logs também mostrarão uma mensagem de erro como Ação 'createOrder' falhou porque a entrada necessária 'customerId' não foi fornecida.
5. Ajuste os limites de confiança para ações iniciais
   Se o orquestrador continuar pulando uma ação pré-requisito, reduza o limite de confiança para essa ação. Vá para as configurações da ação no Copilot Studio e diminua a Pontuação mínima de confiança de 0,8 para 0,6. Isso faz com que o orquestrador tenha mais probabilidade de corresponder à ação mesmo quando a formulação do usuário for imprecisa.
6. Use uma ação pai para forçar uma sequência
   Se dependências e restrições ainda produzirem a ordem errada, crie uma única ação pai que chame as ações filhas na ordem necessária. A ação pai é executada como uma única ação de plugin e executa as etapas filhas sequencialmente dentro de seu próprio código. Isso contorna completamente o orquestrador para essa sequência.

Problemas Comuns com a Ordem de Invocação de Ações

Ação Executa Antes de Sua Ação Pré-requisito Ser Concluída

Isso acontece quando o esquema de saída da ação pré-requisito está ausente ou nomeado incorretamente. Verifique se o nome da propriedade de saída na ação pré-requisito corresponde exatamente ao nome da propriedade de entrada na ação dependente. Os nomes diferenciam maiúsculas de minúsculas. Verifique também se ambas as ações pertencem ao mesmo grupo de plugins no Copilot Studio. Ações de grupos diferentes não podem referenciar as saídas umas das outras.

Orquestrador Executa uma Ação Que Deveria Ser Pulada

Se a intenção do usuário corresponder a várias ações com pontuações de confiança semelhantes, o orquestrador pode invocar uma ação que não é necessária. Adicione frases de gatilho mais específicas ao manifesto da ação. Por exemplo, em vez de um gatilho genérico “pesquisar”, use “pesquisar cliente por e-mail”. O orquestrador dará maior confiança à ação mais específica, reduzindo invocações falsas.

Ordem de Invocação de Ações Difere Entre Teste e Produção

O orquestrador usa comportamento de cache diferente no modo de teste versus produção. Em produção, o orquestrador armazena em cache os resultados das ações durante a duração da conversa. Se uma ação pré-requisito já foi executada em uma rodada anterior, o orquestrador pode pulá-la em uma rodada posterior, mesmo que seu manifesto diga que ela deve ser executada novamente. Para forçar uma nova invocação, adicione uma propriedade cacheTTL ao manifesto da ação com valor 0.

Invocação de Ação do Agente Copilot: Ordem Padrão vs. Ordem Restrita

Item	Ordem Padrão do Orquestrador	Ordem Restrita com Manifesto
Lógica de execução	Grafo de dependências + pontuação de confiança	Campos explícitos after e requires
Controle de sequência	Nenhum — o orquestrador decide	Controle total sobre a sequência de ações
Erro por entrada ausente	Orquestrador tenta encontrar a entrada em qualquer ação anterior	Falha imediatamente se a ação pré-requisito não foi executada
Desempenho	Mais rápido porque o orquestrador pode pular ações desnecessárias	Mais lento porque todas as ações são executadas mesmo se não forem necessárias
Caso de uso	Consultas simples com uma ou duas ações	Fluxos de trabalho complexos com dependências estritas de dados

Agora você sabe como o orquestrador do Copilot determina qual ação do plugin invocar primeiro e como influenciar essa ordem usando esquemas de dependência, restrições de invocação e ações pai. Comece revisando seus manifestos de plugin em busca de propriedades de saída ausentes e, em seguida, adicione restrições after para forçar a sequência em fluxos de trabalho críticos. Para o controle mais confiável, considere criar uma ação pai que execute etapas filhas em uma ordem fixa dentro de seu próprio código.