Práticas recomendadas para a ferramenta Microsoft Foundry Agent Service

Quando você cria agentes no serviço Microsoft Foundry Agent, as ferramentas estendem o que seu agente pode fazer: recuperar informações, chamar APIs e conectar-se a serviços externos. Este artigo ajuda você a configurar as ferramentas com eficiência, controlar quando o agente as chama e manter seus dados seguros.

Dica

Nas instruções do agente, descreva para que serve cada ferramenta e quando usá-la. Por exemplo:

When you need information from my indexed documents, use File Search. When you need to call an API, use the OpenAPI tool. When a tool call fails or returns no results, explain what happened and ask a follow-up question.

Pré-requisitos

  • Acesso a um projeto do Foundry no portal do Foundry com a função Azure Desenvolvedor de IA ou permissões equivalentes.
  • Um modelo implantado no mesmo projeto.
  • Todas as conexões necessárias configuradas para as ferramentas que você planeja usar (por exemplo, Pesquisa de IA do Azure , SharePoint ou Bing Grounding).
  • Um modelo e uma região de projeto que dão suporte à ferramenta. Consulte o suporte à Ferramenta por região e modelo.

Configurar e validar o uso da ferramenta

Melhorar a confiabilidade de invocação de ferramentas

Chamada de ferramenta de controle com tool_choice

Use tool_choice para obter o controle mais determinístico sobre a chamada da ferramenta.

  • auto: o modelo decide se as ferramentas devem ser chamadas.
  • required: o modelo deve chamar uma ou mais ferramentas.
  • none: o modelo não chama as ferramentas.

Para obter detalhes, consulte tool_choice a referência REST do projeto Foundry.

Escrever instruções de ferramenta eficazes

  • Mantenha instruções específicas e consistentes com a configuração da ferramenta.
  • Informe ao modelo para que serve cada ferramenta.
  • Se você tiver várias ferramentas que se sobrepõem, adicione uma regra de decisão (por exemplo, "Usar pesquisa de arquivo antes da pesquisa na Web para conteúdo interno").

Uso seguro da ferramenta

As ferramentas enviam e recebem dados fora do modelo. Reduza os riscos de segurança e privacidade com estas práticas:

  • Trate as saídas da ferramenta como entrada não confiável e valide valores críticos antes de agir sobre elas.
  • Valide saídas estruturadas em relação a um esquema esperado, permita apenas campos e operações conhecidos e exija aprovação do usuário antes das ações conseqüentes.
  • Envie apenas as informações necessárias para concluir a tarefa.
  • Não inclua chaves, tokens ou outras credenciais em prompts.
  • Evite registrar informações confidenciais em rastreamentos ou nos logs da aplicação.
  • Se você se conectar a serviços que não sejam da Microsoft (por exemplo, servidores MCP de terceiros), revise as considerações sobre o tratamento de dados em Criar e gerenciar uma caixa de ferramentas no Foundry.
  • Se você precisar de roteamento centralizado e aplicação de políticas para ferramentas MCP, consulte Governança de ferramentas com o AI Gateway (versão preliminar).

Solucionando problemas

Use estas verificações para resolver problemas comuns:

  • Seu agente não chama uma ferramenta:
    • Confirme se a ferramenta está anexada ao agente.
    • Confirme se o modelo dá suporte à ferramenta.
    • Se você precisar de um comportamento determinístico, defina tool_choice como required.
    • Examine os rastreamentos para confirmar se o modelo produziu uma chamada de ferramenta.
  • As chamadas de ferramenta retornam resultados vazios ou irrelevantes:
    • Melhore as descrições de ferramentas e as instruções para agentes.
    • Para as ferramentas de recuperação, verifique se os dados são absorvidos e se são pesquisáveis.
  • As chamadas de ferramenta falham:
    • Verifique a configuração e a autenticação da ferramenta.
    • Para ferramentas MCP e OpenAPI, valide se o ponto de extremidade é acessível e retorna as respostas esperadas.
  • A Foundry retorna um erro de "ferramenta sem suporte", embora as tabelas mostrem suporte:
    • A disponibilidade da ferramenta requer suporte do modelo e da região. Verifique a tabela de disponibilidade da região para sua região e a tabela de suporte do modelo para seu modelo. Se uma das tabelas for exibida No, a ferramenta não poderá ser executada, mesmo que a outra tabela mostre Yes.
    • Confirme se o modelo está realmente implantado no projeto e na região que você está direcionando. Um modelo que dá suporte a uma ferramenta em geral pode não ser implantado em todas as regiões.
    • Experimente uma região diferente ou uma implantação de modelo diferente que dê suporte à ferramenta. Por exemplo, o interpretador de código não é executado em regiões que mostram no para o Interpretador de Código (como southcentralus e spaincentral), independentemente de qual modelo você usa.

perguntas frequentes

Como fazer para validar se uma ferramenta foi chamada?

Examine os rastreamentos para confirmar se o agente chamou uma ferramenta e inspecionar entradas e saídas da ferramenta. Para obter diretrizes de configuração, consulte Configurar o rastreamento para agentes do Foundry.

Como tornar o uso de ferramentas mais confiável?

Comece com instruções de ferramentas claras. Se você precisar de uma chamada de ferramenta determinística, use tool_choice. Para obter detalhes, consulte chamada da ferramenta de controle com tool_choice.

Conteúdo relacionado

Gerenciamento de ferramentas

Ferramentas de recuperação e pesquisa

Ferramentas de integração e dados

Ferramentas de automação e geração

  • Last updated on