Quando uma Chamada de Ferramenta de Agente se Torna um Pedido Real

1. Nada travou

Um recrutador pediu candidatos publicados desde uma data. O assistente respondeu com confiança, e a contagem que ele forneceu parecia plausível.

Esse foi o erro. A busca foi executada, os resultados retornaram, e nada travou. A restrição de data nunca sobreviveu à viagem da chamada da ferramenta do modelo para a consulta ao banco de dados, então o assistente contou o universo errado e falou como se tivesse feito o pedido exato.

Este é código de produção, não um protótipo. O caminho passa pelo Azure Artificial Intelligence (AI) Foundry, depois por uma ponte do Model Context Protocol (MCP), e então pelo meu serviço de aplicação sobre o Hypertext Transfer Protocol (HTTP). A ponte transforma uma chamada de ferramenta do modelo em um pedido de Application Programming Interface (API).

A fronteira aceita tudo o que o modelo emitiu e traduz para o contrato de serviço. Quando a tradução muda o significado, ela deve parar.

2. A ponte é a chamadora agora

O caminho é curto. O Foundry pede uma ferramenta. A ponte MCP recebe a chamada, analisa JavaScript Object Notation (JSON), alterna pelo nome da ferramenta, constrói um corpo de pedido, chama a aplicação e então retorna a saída da ferramenta através de submitToolOutputs.

O modelo não emitiu parâmetros tipados para a data. Ele emitiu uma string de filtro do Open Data Protocol (OData). O ponto final da aplicação não fala OData.

flowchart TD
recruiter[Recrutador]
agent[Agente Azure AI Foundry]
run[Execução do Foundry]
toolCall[Chamada de Ferramenta Com String de Filtro OData]
bridge[Ponte MCP]
parsedArgs[Argumentos Analisados E Data Extraída]
api[API da Aplicação]
typedRequest[Pedido HTTP Com Parâmetros Tipados]
results[Resultados da Busca E Contagem]
toolOutputs[Submeter Saídas da Ferramenta]
answer[Resposta Com Contagem]
recruiter --> agent
agent --> run
run --> toolCall
toolCall --> bridge
bridge --> parsedArgs
parsedArgs --> typedRequest
typedRequest --> api
api --> results
results --> bridge
bridge --> toolOutputs
toolOutputs --> run
run --> agent
agent --> answer
answer --> recruiter

A causa está em mcp-servers/azure-agent-mcp/src/services/azure-agent-client.ts, dentro de executeToolCall. Para a ferramenta de busca de candidatos, a ponte tenta resgatar a data com esta regex: args.filter.match(/date_published\s+ge\s+(\d{4}-\d{2}-\d{2})/). Se corresponder, dateFilter = dateMatch[1].

Então a ponte envia um corpo moldado para a aplicação: query padrão é *, location recua de um nome de argumento para outro, limit é limitado a Math.min(Number(args.top) || Number(args.limit) || 20, 50), o filtro bruto é passado, e a data extraída sai como um campo tipado quando a análise funcionou.

Esta é a forma normal do erro. A regex é um analisador para uma linguagem de consulta que o modelo nunca foi restringido a emitir corretamente.

Se o modelo formular o filtro de maneira diferente, a correspondência falha. dateFilter permanece null. O pedido ainda tem texto de consulta, um limite, inclusão de contagem, talvez uma string de filtro bruto, e forma suficiente para parecer legítimo.

Isso é o que vai pela rede. Valores anonimizados, estrutura inalterada:

{
  "query": "consultor de riqueza",
  "location": null,
  "designations": null,
  "min_experience": null,
  "min_aum": null,
  "min_production": null,
  "remote_only": null,
  "limit": 20,
  "include_count": true,
  "filter": "date_published gt 2026-01-14T00:00:00Z",
  "date_from": null
}

Nada sobre esse corpo parece errado. Ele está bem formado. Ele valida. A maioria desses nulos são honestos, porque ninguém pediu uma localização ou um mínimo de negócios.

Leia os últimos dois campos juntos, no entanto. filter diz que um limite de data foi solicitado. date_from diz que nenhum foi aplicado. O padrão aceita ge e o modelo escreveu gt, então um único operador de comparação é toda a distância entre uma busca limitada e uma não limitada. Colocar a data entre aspas, ou escrever date_published/gt, ou colocar a cláusula em segundo lugar em um filtro composto, tudo leva ao mesmo lugar.

Esses dois campos se contradizem dentro de um corpo de pedido, e nada de nenhum lado os compara.

Um filtro descartado não gera erro. Ele responde.

3. Respostas parciais têm um custo de silêncio

A mesma forma aparece dentro de app/agents/orchestrator.py. AgentOrchestrator.process roteia a consulta, executa o agente principal, inicia agentes extras em paralelo e então combina o que vem de volta. Ele também carrega um dicionário de tempo com router_ms, agent_ms e total_ms.

A ramificação paralela usa asyncio.gather(*secondary_tasks, return_exceptions=True). Apenas objetos AgentResponse bem-sucedidos entram em secondary_results através de secondary_results.append(resp.to_dict).

return_exceptions=true compra uma resposta parcial em vez de nenhuma resposta. Custa silêncio: nada registra a exceção, então um agente que falha toda vez parece idêntico a um que não tinha nada a acrescentar.

Um agente secundário começa a levantar exceções em cada chamada. As respostas continuam chegando, então nenhum alerta dispara. total_ms fica melhor, porque uma tarefa que levanta imediatamente termina mais rápido do que uma que faz trabalho real. O sistema parece mais saudável à medida que perde cobertura.

Então você vai verificar as estatísticas. get_agent_stats relata configured, e para cada agente um nome, um tools_count e um modelo. Essa é a configuração, tudo isso. Nada conta invocações. Nada conta falhas. Um agente que não retornou uma resposta utilizável em uma semana relata exatamente o que relatou no dia em que funcionou.

O filtro esconde mais uma distinção. isinstance(resp, AgentResponse) and resp.success descarta uma exceção levantada e uma resposta retornada, mas sem sucesso, no mesmo lugar. Uma falha e uma considerada "não tenho nada útil aqui" são o mesmo evento.