Boas práticas de ferramentas para o Microsoft Foundry Agent Service

Quando constrói agentes no Microsoft Foundry Agent Service, as ferramentas estendem o que o seu agente pode fazer — recuperar informação, chamar APIs e ligar-se a serviços externos. Este artigo ajuda-o a configurar ferramentas de forma eficaz, a controlar quando o agente as chama e a manter os seus dados seguros.

Dica

Nas instruções do teu agente, descreve para que serve cada ferramenta e quando a deves usar. 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 Foundry no portal Foundry com a função Azure AI Developer ou permissões equivalentes.
  • Um modelo implementado no mesmo projeto.
  • Quaisquer ligações necessárias configuradas para as ferramentas que planeias usar (por exemplo, Pesquisa de IA do Azure, SharePoint ou Bing grounding).
  • Um modelo e uma região de projeto que ambos suportam a ferramenta. Veja Suporte de ferramentas por região e modelo.

Configurar e validar a utilização da ferramenta

Melhorar a fiabilidade da invocação de ferramentas

Chamada de ferramenta de controlo com tool_choice

Utilize tool_choice para o controlo mais determinístico da invocação de ferramentas.

  • auto: O modelo decide se deve invocar ferramentas.
  • required: O modelo deve chamar uma ou mais ferramentas.
  • none: O modelo não invoca ferramentas.

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

Escrever instruções eficazes para ferramentas

  • Mantém as instruções específicas e consistentes com a configuração da tua ferramenta.
  • Diz ao modelo para que serve cada ferramenta.
  • Se tiver várias ferramentas com funções sobrepostas, adicione uma regra de decisão (por exemplo, "Use a File Search antes da Web Search para conteúdo interno.").

Utilização segura de ferramentas

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 das ferramentas como entradas não confiáveis e valide valores críticos antes de agir sobre elas.
  • Validar saídas estruturadas contra um esquema esperado, permitir apenas campos e operações conhecidas e exigir aprovação do utilizador antes das ações consequentes.
  • Envie apenas a informação necessária para completar a tarefa.
  • Não incluas chaves, tokens ou outras credenciais nos prompts.
  • Evite registar segredos em rastreios ou nos registos da aplicação.
  • Se se ligar a serviços que não sejam da serviços Microsoft (por exemplo, servidores MCP de terceiros), reveja as considerações de tratamento de dados no Create e gere uma caixa de ferramentas no Foundry.
  • Se precisar de encaminhamento centralizado e aplicação de políticas para ferramentas MCP, consulte Governação de ferramentas com AI Gateway (pré-visualização).

Resolução de problemas

Utilize estas verificações para resolver problemas comuns:

  • O seu agente não invoca uma ferramenta:
    • Confirme que a ferramenta está anexada ao agente.
    • Confirma se o modelo suporta a ferramenta.
    • Se precisar de comportamento determinístico, defina tool_choice para required.
    • Reveja os rastreios para confirmar se o modelo gerou uma chamada de ferramenta.
  • As chamadas de ferramenta devolvem resultados vazios ou irrelevantes:
    • Melhorar as descrições das ferramentas e as instruções dos agentes.
    • Para ferramentas de pesquisa, certifique-se de que os seus dados estão importados e pesquisáveis.
  • As chamadas de ferramenta falham:
    • Verifique a configuração e autenticação da ferramenta.
    • Para as ferramentas MCP e OpenAPI, valida que o endpoint é acessível e devolve as respostas esperadas.
  • O Foundry devolve um erro de "ferramenta não suportada" mesmo que as tabelas mostrem suporte:
    • A disponibilidade de ferramentas requer suporte tanto do modelo como da região. Consulta a tabela de disponibilidade de regiões para a tua região e a tabela de suporte de modelos para o teu modelo. Se qualquer uma das tabelas mostrar No, a ferramenta não pode correr, mesmo que a outra tabela mostre Yes.
    • Confirma que o modelo está realmente implementado no projeto e na região que estás a escolher. Um modelo que suporta uma ferramenta em geral pode não ser implementado em todas as regiões.
    • Experimente uma região diferente ou um modelo diferente de implementação que suporte a ferramenta. Por exemplo, o Code Interpreter não é executado em regiões que mostram no para o Code Interpreter (como southcentralus e spaincentral), independentemente do modelo utilizado.

FAQ

Como posso validar se uma ferramenta foi chamada?

Revise os traços para confirmar se o seu agente chamou uma ferramenta e para inspecionar as entradas e saídas da ferramenta. Para orientações de configuração, consulte Configurar rastreamento para agentes da Foundry.

Como posso tornar o uso da ferramenta mais fiável?

Comece com instruções claras para a ferramenta. Se precisar de chamada de ferramenta determinística, use tool_choice. Para detalhes, veja a chamada de ferramenta de Controlo com tool_choice.

Conteúdo relacionado

Gestão de ferramentas

Ferramentas de recuperação e pesquisa

Dados e ferramentas de integração

Automação e ferramentas de geração

  • Last updated on