Escribir instrucciones eficaces para agentes declarativos con complementos de API

Los agentes declarativos adaptan Microsoft 365 Copilot para satisfacer las necesidades específicas de una organización. Al crear agentes declarativos con Microsoft 365 Agents Toolkit, puede agregar aptitudes al agente a través de complementos de API. Los complementos de API permiten a su agente consultar e interactuar con los datos de una organización a través de API.

En este artículo se describe la arquitectura del agente y se proporcionan prácticas recomendadas para escribir instrucciones para agentes declarativos que incluyen complementos de API.

Componentes principales de los agentes declarativos con complementos API

Los agentes declarativos que llaman a los complementos API incluyen varios componentes que garantizan una integración y funcionalidad efectivas. Comprender esta arquitectura lo ayudará a diseñar su agente de manera efectiva. La arquitectura incluye los siguientes componentes:

  • Manifiesto de aplicación : describe cómo se configura la aplicación y hace referencia al manifiesto del agente declarativo.
  • Manifiesto de agente declarativo : define la configuración del agente, incluidas las instrucciones, las funcionalidades, los iniciadores de conversaciones y las acciones. Hace referencia al manifiesto del complemento.
  • Manifiesto de complemento : describe la configuración del complemento, incluidas las funciones disponibles y una referencia a la especificación OpenAPI.
  • Especificación OpenAPI - Proporciona definiciones detalladas de los puntos finales de la API, incluidas las rutas, los parámetros, los formatos de solicitud y respuesta, y la autenticación.

Juntos, estos archivos definen el comportamiento del agente y cómo interactúa con la API subyacente.

Diagrama que muestra los cuatro archivos de manifiesto que hacen referencia al otro

Para obtener más información sobre los complementos de API, consulte:

Asignación de funciones en el manifiesto del complemento

En el manifiesto del complemento, cada función debe asignarse a un operationId correspondiente en la especificación OpenAPI. Esto garantiza que cuando el agente invoca una función (por ejemplo, createTask), el agente sabe a qué punto de conexión de API llamar.

En los ejemplos siguientes se muestra la asignación en el manifiesto del complemento y la función asignada en la especificación OpenAPI.

"functions": [
  {
    "name": "createTask",
    "description": "Creates a new task in the specified task list."
  }
]

paths:
  /me/todo/lists/{listId}/tasks:
    post:
      operationId: createTask
      summary: Create a new task
      description: Creates a new task in the specified task list.
      parameters:

Procedimientos recomendados para instrucciones de agente

Escribir instrucciones efectivas es esencial para garantizar que los agentes declarativos con complementos API tengan éxito. Para optimizar tu agente, aplica la asignación de funciones correcta, utiliza el encadenamiento para permitir interacciones más ricas y prueba y refina iterativamente el comportamiento de tu agente.

Aplique las siguientes prácticas recomendadas al escribir instrucciones para agentes declarativos con complementos de API:

  • Evite instrucciones ambiguas o negativas. Las instrucciones contrastantes o negativas pueden introducir ambigüedad y confundir el modelo. Céntrate en definir casos de uso válidos con ejemplos positivos. Si es importante distinguir entre consultas válidas y no válidas, proporcione criterios claros y ejemplos que definan la respuesta esperada del agente para cada una.
  • Ejemplos de uso Proporciona ejemplos claros para guiar el comportamiento de los agentes. Por ejemplo:

Entrada del usuario: ¿Qué tiempo hace en Praga? Llamada del agente: getWeather(location="Prague") Entrada de usuario: "¿Necesito un paraguas mañana?" Llamada del agente: getWeather(location=user_location, forecast="tomorrow")

  • Revise y pruebe las instrucciones. Pruebe las instrucciones en varios escenarios para comprobar que el agente realiza las llamadas de función correctas. Si en las pruebas encuentra que el agente invoca funciones inesperadamente, revise la descripción de la función en la especificación OpenAPI y aclare las instrucciones del agente para mejorar el mapeo de intenciones.

  • Instrucciones de diseño para conversaciones de varios turnos. Cuando integre complementos de API, diseñe sus instrucciones para que el agente maneje conversaciones de varios turnos.

Por ejemplo, si la función requiere varios parámetros, además de definir los parámetros requeridos en la especificación OpenAPI, indique al agente que recopile todos los parámetros antes de realizar la llamada API. Esto garantiza que el agente recopile toda la información necesaria en una secuencia lógica.

En el siguiente ejemplo se muestra cómo instruir a un agente meteorológico para conversaciones de varios turnos y el flujo de agente resultante.

Instrucciones para el agente Flujo de agente
Si el usuario pregunta sobre el clima:

- Pídale al usuario la ubicación.
- Pregunte al usuario por el pronóstico del día.
- Pregunte al usuario por el sistema de unidades.
- Solo llame a getWeather cuando recopile todos los valores.		 Usuario: "¿Qué tiempo hace?"
Agente: "¿Cuál es tu ubicación?"
Usuario: "London"
Agente: "¿Prefiere la información meteorológica en unidades métricas o imperiales?"
Usuario: "Metric"
Agent: "¿Necesita el tiempo para hoy o la previsión para mañana?"
User: "Today"
Agent: "Comprobaré el tiempo de Londres para hoy"
Agent calls: getWeather(location="London", forecast="today", system="Metric")

Para conocer las prácticas recomendadas generales para las instrucciones del agente, consulte Escribir instrucciones eficaces.

Encadenamiento de llamadas de función en complementos de API

El encadenamiento de llamadas de función permite a los agentes declarativos combinar múltiples acciones de API en un flujo continuo. En las secciones siguientes se describen patrones comunes y cómo escribir instrucciones para cada uno.

Encadenamiento de llamadas de función con salida como parámetro de entrada

Use el resultado de una llamada API como entrada para otra. Esto es útil cuando se necesita el resultado de la primera función para realizar la segunda función. Esto puede funcionar en todos los complementos.

En el siguiente ejemplo, un agente declarativo con la API Weather y la API To-do crea una tarea to-do con datos de la previsión meteorológica.

Instrucciones para el agente Flujo de agente
Para obtener el tiempo, use siempre la acción getWeather , luego cree una tarea con el título "temperatura en" y agregue la ubicación y la temperatura mencionadas en el clima al título de la tarea. Usuario: "Obtener el tiempo en Praga"
Agent: Llamadas a getWeather (location="Prague", forecast="today")
Agent: usa los datos de la primera llamada para crear una tarea pendiente createTask (title ="{weather output}")

Encadenamiento basado en el historial de conversaciones dentro de un agente

Cuando se utiliza el encadenamiento basado en el historial de conversaciones, el agente utiliza las respuestas anteriores para manejar las acciones de seguimiento. Este enfoque usa el historial de conversaciones para mantener el contexto.

En el siguiente ejemplo, un agente elimina una tarea pendiente por su nombre.

Instrucciones para el agente Flujo de agente
1. Cuando el usuario pida enumerar todas las tareas pendientes, llame a getTasks para recuperar la lista de tareas pendientes con título e identificación.
2. Después de enumerar las tareas pendientes, si el usuario solicita eliminar una tarea pendiente, use el identificador de la respuesta para llamar a deleteTask.		 Usuario: "¿Mostrar todas las tareas pendientes en la carpeta Tareas?"
Agente: alls getTasks (folderId="Tasks") y muestra todas las tareas pendientes con identificadores.
Usuario: "Eliminar tarea de TaskMaster Pro"
Agente: usa la información del historial de conversaciones para encontrar el identificador de la tarea pendiente y la elimina llamando a deleteTask.

Encadenamiento con el conocimiento de SharePoint

El encadenamiento de llamadas API permite a un agente combinar fuentes de conocimiento y acciones para diseñar flujos de trabajo más complejos.

En el siguiente ejemplo, un agente recupera los datos de estado del proyecto de SharePoint y crea las tareas correspondientes en Microsoft To-Do para realizar un seguimiento.

Instrucciones para el agente Flujo de agente
- Para obtener estados de proyectos, use ProjectDeadlines de conocimiento de Sharepoint.
- Cree siempre una tarea pendiente para cada proyecto utilizando la actualización de estado del título.		 Usuario: "¿Pueden proporcionar una actualización sobre el estado de todos los proyectos?"
Agente: Extrae los datos de estado del proyecto de SharePoint y, a continuación, usa createTask para generar una tarea pendiente para cada proyecto.

Encadenamiento con el intérprete de código

También es posible encadenar llamadas API e integrar capacidades adicionales, como un intérprete de código. Esto permite a un agente procesar las salidas de la API dinámicamente para habilitar flujos de trabajo más avanzados.

En el siguiente ejemplo, un agente crea un gráfico basado en los datos de las tareas pendientes.

Instrucciones para el agente Flujo de agente
Cuando el usuario pida enumerar todas las tareas pendientes, llame a getTasks para recuperar la lista de tareas pendientes con título e identificador, trazar también el gráfico para la salida. Usuario: "Recuperar todas las tareas en Tasks"
Agent: Llama a getTasks (folderId="Tasks") y muestra todas las tareas pendientes con identificadores.
Agente: Llama al intérprete de código para iniciar la generación del gráfico en función de la salida de la primera llamada.

En este ejemplo también se ejecutan varias acciones a la vez. Esto es útil para iniciar una serie de acciones relacionadas que no requieren varias entradas de usuario.

Cuando el intérprete de código genera un archivo (como una imagen de gráfico o una hoja de cálculo), Copilot presenta automáticamente un vínculo de descarga en la respuesta, lo que permite a los usuarios guardar el archivo localmente. Para obtener más información, consulte Generar archivos descargables.

Contenido relacionado

  • Last updated on