Mejores prácticas de herramientas para el Agente de Foundry de Microsoft

Al crear agentes en el servicio de agentes de Microsoft Foundry, las herramientas amplían lo que el agente puede hacer: recuperando información, llamando a unas API y conectándose a servicios externos. Este artículo le ayuda a configurar herramientas de forma eficaz, controlar cuándo los llama el agente y mantener los datos seguros.

Sugerencia

En las instrucciones del agente, describa para qué sirve cada herramienta y cuándo usarla. Por ejemplo:

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.

Requisitos previos

  • Acceso a un proyecto foundry en el portal de Foundry con el rol Azure AI Developer o permisos equivalentes.
  • Un modelo implementado en el mismo proyecto.
  • Las conexiones necesarias configuradas para las herramientas que tenga previsto utilizar (por ejemplo, Búsqueda de Azure AI, SharePoint o Bing grounding).
  • Un modelo y una región de proyecto que admiten la herramienta. Consulte Compatibilidad de herramientas por región y modelo.

Configuración y validación del uso de herramientas

Mejorar la fiabilidad de las llamadas a herramientas

Control de llamadas a herramientas con tool_choice

Utilice tool_choice para obtener el control más determinista sobre las llamadas a herramientas.

  • auto: el modelo decide si llamar a las herramientas.
  • required: El modelo debe llamar a una o varias herramientas.
  • none: el modelo no llama a herramientas.

Para obtener más información, consulte tool_choice la referencia de REST del proyecto Foundry.

Escribir instrucciones de herramientas eficaces

  • Mantenga instrucciones específicas y coherentes con la configuración de la herramienta.
  • Indique al modelo para qué sirve cada herramienta.
  • Si tiene varias herramientas que se superponen, agregue una regla de decisión (por ejemplo, "Usar búsqueda de archivos antes de buscar contenido interno").

Uso seguro de herramientas

Las herramientas envían y reciben datos fuera del modelo. Reduzca los riesgos de seguridad y privacidad con estas prácticas:

  • Trate las salidas de la herramienta como entrada que no son de confianza y valide los valores críticos antes de actuar en ellas.
  • Valide las salidas estructuradas en un esquema esperado, permita solo campos y operaciones conocidos y requiera la aprobación del usuario antes de las acciones consecuentes.
  • Envíe solo la información necesaria para completar la tarea.
  • No incluya claves, tokens u otras credenciales en mensajes.
  • Evite registrar información confidencial en trazas o registros de aplicaciones.
  • Si se conecta a servidores MCP que no son de servicios Microsoft (por ejemplo, servidores MCP de terceros), revise las consideraciones de control de datos en Creación y administración de un cuadro de herramientas en Foundry.
  • Si necesita el enrutamiento centralizado y la aplicación de directivas para las herramientas de MCP, consulte Gobernanza de herramientas con AI Gateway (versión preliminar).

Solución de problemas

Use estas comprobaciones para resolver problemas comunes:

  • Tu agente no invoca ninguna herramienta:
    • Confirme que la herramienta está asociada al agente.
    • Confirme que el modelo admite la herramienta.
    • Si necesita un comportamiento determinista, establezca tool_choice a required.
    • Revise los rastros para confirmar si el modelo generó una llamada a la herramienta.
  • Las llamadas de herramienta devuelven resultados vacíos o irrelevantes:
    • Mejore las descripciones de herramientas y las instrucciones del agente.
    • Para las herramientas de recuperación, asegúrese de que los datos se incorporen y sean buscables.
  • Se produce un error en las llamadas a herramientas:
    • Compruebe la configuración y la autenticación de la herramienta.
    • En el caso de las herramientas MCP y OpenAPI, valide que el punto de conexión sea accesible y devuelva respuestas esperadas.
  • Foundry devuelve un error de "herramienta no compatible", aunque las tablas muestran compatibilidad:
    • La disponibilidad de herramientas requiere compatibilidad con el modelo y la región. Compruebe la tabla de disponibilidad de regiones de su región y la tabla de compatibilidad del modelo para el modelo. Si alguna de las tablas muestra No, la herramienta no se puede ejecutar, aunque la otra tabla muestre Yes.
    • Confirme que el modelo se implementa realmente en el proyecto y la región de destino. Es posible que un modelo que admita una herramienta en general no se implemente en todas las regiones.
    • Pruebe una región diferente o una implementación de modelo diferente que admita la herramienta. Por ejemplo, el intérprete de código no se ejecuta en regiones que se muestran no para el intérprete de código (como southcentralus y spaincentral), independientemente del modelo que use.

Preguntas más frecuentes

¿Cómo verificar si se ha invocado una herramienta?

Revise los seguimientos para confirmar si el agente llamó a una herramienta y para inspeccionar las entradas y salidas de la herramienta. Para obtener instrucciones de configuración, consulte Configurar el seguimiento para los agentes de Foundry.

¿Cómo puedo hacer que el uso de herramientas sea más confiable?

Comience con instrucciones de herramientas claras. Si necesita realizar llamadas deterministas a herramientas, use tool_choice. Para obtener más información, consulte Control de llamadas a herramientas con tool_choice.

Contenido relacionado

Gestión de herramientas

Herramientas de recuperación y búsqueda

Herramientas de integración y datos

Herramientas de automatización y generación

  • Last updated on