Compartir vía

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 al agente consultar e interactuar con los datos de una organización a través de las API.

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

Componentes principales de agentes declarativos con complementos de API

Los agentes declarativos que llaman a complementos de API incluyen varios componentes que garantizan una integración y funcionalidad eficaces. Comprender esta arquitectura le ayudará a diseñar el agente de forma eficaz. 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 del agente declarativo : define la configuración del agente, incluidas instrucciones, funcionalidades, inicios de conversación y acciones. Hace referencia al manifiesto del complemento.
  • Manifiesto del complemento : describe la configuración del complemento, incluidas las funciones disponibles y una referencia a la especificación de OpenAPI.
  • Especificación de OpenAPI : proporciona definiciones detalladas de puntos de conexión de API, incluidas rutas de acceso, parámetros, formatos de solicitud y respuesta y 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 a los que cada uno hace referencia

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 de 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 las instrucciones del agente

Escribir instrucciones eficaces es esencial para garantizar que los agentes declarativos con complementos de API sean correctos. Para optimizar el agente, aplique la asignación de funciones correcta, use el encadenamiento para habilitar interacciones más enriquecidas y pruebe y refine iterativamente el comportamiento del agente.

Aplique los siguientes procedimientos recomendados al escribir instrucciones para agentes declarativos con complementos de API:

  • Evite instrucciones ambiguas o negativas. Las instrucciones de contraste o negativas pueden introducir ambigüedad y confundir el modelo. Céntrese 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 del agente esperada para cada una.
  • Usar ejemplos Proporcione ejemplos claros para guiar el comportamiento del agente. Por ejemplo:

Entrada del usuario: ¿Cuál es el tiempo en Praga? Llamada del agente: getWeather(location="Praga") Entrada del 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 detecta que el agente invoca funciones de forma inesperada, revise la descripción de la función en la especificación de OpenAPI y aclare las instrucciones del agente para mejorar la asignación de intenciones.

  • Instrucciones de diseño para conversaciones de varios turnos. Al integrar complementos de API, diseñe las instrucciones para que el agente controle las conversaciones de varios turnos.

Por ejemplo, si la función requiere varios parámetros, además de definir los parámetros necesarios en la especificación de 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 ejemplo siguiente se muestra cómo indicar a un agente meteorológico para las conversaciones de varios turnos y el flujo de agente que se produce.

Instrucciones para el agente Flujo del agente
Si el usuario pregunta sobre el tiempo:

- Pregunte al usuario por la ubicación.
- Pedir al usuario el día de previsión.
- Preguntar al usuario por el sistema de unidades.
- Solo llame a getWeather cuando recopile todos los valores.		 Usuario: "¿Cuál es el clima?"
Agente: "¿Cuál es su ubicación?"
Usuario: "London"
Agent: "¿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?"
Usuario: "Today"
Agent: "Comprobaré el tiempo de Londres para hoy"
Llamadas de agente: getWeather(location="London", forecast="today", system="Metric")

Para obtener procedimientos recomendados generales para las instrucciones del agente, consulte Escritura de instrucciones eficaces.

Encadenamiento de llamadas a funciones en complementos de API

Las llamadas de función de encadenamiento permiten a los agentes declarativos combinar varias acciones de API en un flujo sin problemas. En las secciones siguientes se describen patrones comunes y cómo escribir instrucciones para cada uno.

Llamadas de función de encadenamiento con salida como parámetro de entrada

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

En el ejemplo siguiente, un agente declarativo con Weather API y api de tareas pendientes crea una tarea de tareas pendientes con datos de la previsión meteorológica.

Instrucciones para el agente Flujo del agente
Para obtener el tiempo, use siempre la acción getWeather , cree una tarea con el título "temperature in" y agregue la ubicación y la temperatura mencionadas en el clima al título de la tarea. Usuario: "Get the weather in Prague"
Agent: Calls getWeather (location="Prague", forecast="today")
Agent: Usa los datos de la primera llamada para crear una tarea de tareas pendientes createTask (title ="{weather output}")

Encadenamiento basado en el historial de conversaciones dentro de un agente

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

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

Instrucciones para el agente Flujo del agente
1. Cuando el usuario le pida que enumere todas las tareas pendientes, llame a getTasks para recuperar la lista de tareas pendientes con el título y el identificador.
2. Después de enumerar las tareas pendientes, si el usuario solicita eliminar una tarea pendientes, 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 tareas pendientes de TaskMaster Pro"
Agente: usa la información del historial de conversaciones para buscar el identificador de tareas pendientes y elimina el tareas pendientes mediante una llamada a deleteTask.

Encadenamiento con conocimientos de SharePoint

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

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

Instrucciones para el agente Flujo del agente
- Para obtener los estados del proyecto, use ProjectDeadlines de conocimiento de Sharepoint.
- Cree siempre una tarea pendientes para cada proyecto mediante la actualización de estado para el título.		 Usuario: "¿Puede 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 de tareas pendientes para cada proyecto.

Encadenamiento con intérprete de código

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

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

Instrucciones para el agente Flujo del agente
Cuando el usuario pide enumerar todas las tareas pendientes, llama a getTasks para recuperar la lista de tareas pendientes con el título y el identificador, y también traza el gráfico para la salida. Usuario: "Recuperar todas las tareas en Tareas"
Agente: 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.

Contenido relacionado

  • Last updated on