Creación de un agente declarativo con un complemento de API
Al agregar acciones a un agente declarativo, se le permite recuperar y actualizar los datos almacenados en sistemas externos. La conexión de un agente a sistemas externos que se usan en su organización le permite usar agentes para admitir los procesos empresariales. En las secciones siguientes se explican los distintos elementos implicados en la extensión de un agente declarativo con acciones.
Agente declarativo
Los agentes declarativos pueden incluir una o varias acciones que les permitan interactuar con sistemas externos en tiempo real. Mediante acciones, los agentes pueden leer y modificar los datos almacenados en una aplicación externa. Una acción se conecta a una API a través de un complemento de API. El agente define sus acciones en el manifiesto mediante la matriz actions :
{
"$schema": "https://developer.microsoft.com/json-schemas/copilot/declarative-agent/v1.0/schema.json",
"version": "v1.0",
"name": "Il Ristorante",
"description": "Order the most delicious Italian dishes and drinks from the comfort of your desk.",
"instructions": "$[file('instruction.txt')]",
"actions": [
{
"id": "menuPlugin",
"file": "ai-plugin.json"
}
]
}
Para definir una acción, agregue un elemento a la matriz actions . Cada elemento identifica de forma única una acción mediante un identificador y usa la propiedad file para hacer referencia a un archivo de definición de complemento independiente en el proyecto que describe el complemento de API.
Definición del complemento
Un archivo de definición de complemento describe un complemento de API que un agente declarativo usa para comunicarse con una API. La definición del complemento consta de varias secciones, como la información básica, las funciones y los tiempos de ejecución.
Información básica
Cada archivo de definición de complemento contiene información básica sobre el complemento, como su nombre y descripción. El siguiente fragmento de código muestra un ejemplo de información básica del complemento:
{
"$schema": "https://developer.microsoft.com/json-schemas/copilot/plugin/v2.1/schema.json",
"schema_version": "v2.1",
"namespace": "ilristorante",
"name_for_human": "Il Ristorante",
"description_for_human": "See the today's menu and place orders",
"description_for_model": "Plugin for getting the today's menu, optionally filtered by course and allergens, and placing orders",
"functions": [
],
"runtimes": [
],
"capabilities": {
"localization": {},
"conversation_starters": []
}
}
El contenido de las propiedades name_for_human y description_for_human son puramente informativos. La propiedad description_for_model es importante porque el agente la usa para decidir si debe invocar el complemento para el símbolo del usuario. Si ve que el agente no invoca el complemento para solicitudes específicas, debe comprobar si la descripción del modelo contiene la información necesaria para que el agente lo considere pertinente.
Otra propiedad importante es el espacio de nombres que es necesario y que el agente usa para eliminar la ambigüedad de las acciones en los distintos complementos. Si lo quita o proporciona un valor no válido que no coincide con el esquema, podría impedir que el agente use el complemento. El espacio de nombres debe coincidir con la siguiente expresión ^[A-Za-z0-9_]+regular , lo que significa que debe constar de al menos un carácter, como A-Z, a-z, 0-9o _. Cualquier otro carácter no es válido.
Funciones
La siguiente sección de la definición del complemento son las funciones. Las funciones definen una o varias operaciones de API que el complemento de API puede realizar e indican al agente cómo mostrar los datos que recibe de la API. El siguiente fragmento de código muestra una función de ejemplo:
{
"functions": [
{
"name": "getDishes",
"description": "Returns information about the dishes on the menu. Can filter by course (breakfast, lunch or dinner), name, allergens, or type (dish, drink).",
"capabilities": {
"response_semantics": {
"data_path": "$.dishes",
"properties": {
"title": "$.name",
"subtitle": "$.description"
},
"static_template": {
...trimmed for brevity
}
}
}
}
]
}
Cada función consta de varios elementos.
Nombre
El nombre identifica de forma única la operación en el complemento de API y que debe coincidir exactamente con un operationId de la especificación de API relacionada. Si el nombre especificado no coincide con ninguna operación, microsoft 365 Agents Toolkit produce un error al compilar el proyecto. Si implementa una función con un nombre que no coincide con un operationId, el agente no puede invocar esa función.
Descripción
El agente usa la descripción para hacer coincidir una función con el símbolo del sistema de un usuario. Al describir la función, asegúrese de explicar qué tareas completa, incluidas las variaciones, como filtrar o ordenar información. Si la descripción es inexacta o incompleta, el agente no puede coincidir con el símbolo del sistema específico y no puede invocar la función.
Semántica de respuesta
La propiedad response_semantics indica al agente cómo debe mostrar los datos que recibe de la API. Consta de tres propiedades: data_path, propiedades y static_template.
Si la API devuelve una estructura de datos compleja y desea que el agente solo muestre una parte específica de ella, use la propiedad data_path para especificar una expresión de ruta de acceso JSON que apunte a la parte pertinente de la respuesta de la API. Tenga en cuenta la siguiente respuesta de API:
{
"dishes": [
{
"id": 1,
"name": "Classic Italian Frittata",
"description": "A fluffy omelette filled with sautéed mushrooms, onions, and melted pecorino, served with a side of roasted cherry tomatoes.",
"image_url": "https://raw.githubusercontent.com/pnp/copilot-pro-dev-samples/main/samples/da-ristorante-api/assets/frittata.jpeg",
"price": 8.99,
"allergens": [
"eggs",
"dairy"
],
"course": "breakfast",
"type": "dish"
},
...trimmed for brevity
]
}
Los datos que desea que muestre el agente están en la propiedad dishes , por lo que se establece la propiedad data_path en la $.dishes expresión JSONPath que hace referencia a la propiedad dishes del objeto raíz que indica $.
La siguiente parte de la semántica de respuesta son las propiedades. Con las propiedades, indica al agente cuál de las propiedades de datos de la respuesta de LA API representa las propiedades del elemento, como título, descripción o dirección URL. Cuando la API devuelve varios elementos, el agente usa la asignación semántica para incluir la información más relevante en la respuesta. Tenga en cuenta la siguiente asignación semántica:
{
"response_semantics": {
"properties": {
"title": "$.name",
"subtitle": "$.description"
}
}
}
Cuando el agente responde, genera una respuesta como la siguiente:
Para cada plato, el agente incluye un título en negrita, seguido de una descripción. Dado que la asignación no incluye una dirección URL ni una etiqueta de confidencialidad, el agente no las incluye en su respuesta.
La parte final de la semántica de respuesta es static_template. Use una plantilla estática para definir una plantilla de tarjeta adaptable que el agente debe usar para mostrar los datos de la API.
Sugerencia
Para más información sobre el uso de plantillas de tarjeta adaptable con complementos de API, consulte el módulo Uso de tarjetas adaptables para mostrar datos en complementos de API para agentes declarativos en la sección Más recursos al final de este módulo de aprendizaje.
Tiempos de ejecución
La parte final de la definición del complemento son los tiempos de ejecución. Los tiempos de ejecución describen qué API usa el complemento y qué funciones pertenecen a qué API. El siguiente fragmento de código muestra una definición en tiempo de ejecución:
{
"type": "OpenApi",
"auth": {
"type": "None"
},
"spec": {
"url": "apiSpecificationFile/ristorante.yml"
},
"run_for_functions": [
"getDishes",
"placeOrder"
]
}
Empiece por definir el tipo de descripción de la API. En este momento, los complementos de API solo admiten OpenAPI.
A continuación, defina si la API es anónima o requiere autenticación. El tipo de autenticación None significa que el agente puede llamar a la API de forma anónima. Si necesita comunicarse con una API protegida, actualice el valor en consecuencia para que coincida con el mecanismo de autenticación de la API. Para obtener más información sobre los mecanismos de autenticación admitidos, consulte la documentación.
Sugerencia
Para obtener más información sobre cómo conectar complementos de API a API protegidas, consulte el módulo Autenticación del complemento de API para agentes declarativos con API protegidas en la sección Más recursos al final de este módulo de aprendizaje.
En la siguiente sección denominada spec, se proporciona una referencia a un documento de especificación de API local que describe la API que el complemento de API puede usar. Con la propiedad url , se especifica una ruta de acceso relativa al archivo en el proyecto.
La parte final es la propiedad run_for_functions que especifica cuál de las funciones especificadas pertenece a esta API.
Sugerencia
Al compilar el proyecto, Microsoft 365 Agents Toolkit comprueba que las funciones especificadas en esta propiedad coinciden con las funciones definidas en la sección de funciones y produce un error si no lo hacen. Microsoft 365 Agents Toolkit comprueba la coherencia del proyecto y le proporciona comentarios tempranos y le ayuda a evitar errores difíciles de depurar.
Especificación de API
Una parte importante de cada complemento de API es la especificación de API, que proporciona información importante sobre la API, como:
- Dónde se encuentra la API.
- Si la API requiere autenticación y, si es así, de qué manera.
- Qué operaciones admite la API.
- Para cada operación, qué datos espera y cómo puede responder.
Cuando un agente carga un complemento de API, usa toda esta información para compilar una solicitud de API, llamar a la API y procesar su respuesta. Por lo tanto, es importante que describa claramente todos los parámetros y propiedades, de modo que el agente comprenda cómo usarlos para satisfacer la solicitud del usuario.
Si tiene previsto usar una API existente, asegúrese de incluir solo la parte de la especificación de API que tiene previsto usar en el complemento de API. Si incluye toda la especificación de API, pero solo usa una o dos operaciones, es más difícil que el agente analice la información pertinente de la especificación de API de gran tamaño.
Sugerencia
Si necesita usar una parte de la especificación de API existente, considere la posibilidad de usar Hidi. Se trata de una herramienta creada por Microsoft que permite extraer fácilmente una parte pertinente de una especificación de API junto con todas las entidades relacionadas. Busque más información al final de este módulo de aprendizaje.
Los agentes admiten las especificaciones de la API de OpenAPI en YAML y JSON.
Sugerencia
Al compilar una API personalizada para que la use el complemento de API y ejecutarla desde el equipo local, debe exponerla a Internet para que el agente pueda llamarla. Puede exponer la API mediante tuneles dev, una herramienta creada por Microsoft para compartir servicios locales a través de Internet. Si usa Microsoft 365 Agents Toolkit para compilar el agente con el complemento de API, no solo inicia automáticamente un túnel de desarrollo, sino que también actualiza automáticamente la dirección URL de la API en la especificación de la API, lo que le permite centrarse en la creación de la solución.
Cómo encaja entre sí
Ahora que sabe de qué diferentes elementos consta un agente declarativo con un complemento de API, echemos un vistazo a cómo encajan juntos. En el diagrama siguiente se muestran las relaciones entre los distintos elementos.
Las aplicaciones de Microsoft Teams se usan para empaquetar y distribuir los agentes. Cada aplicación de Teams puede contener uno o más agentes declarativos, cada uno optimizado para un escenario específico. Un agente, en función de su propósito, puede contener cero o más complementos de API que le permitan comunicarse con sistemas externos. Un complemento define una o varias funciones. Cada función realiza una tarea específica y hace referencia exactamente a una operación de API. Junto a las funciones, un complemento de API hace referencia a una o varias especificaciones de API que describen las API que usa. A su vez, cada especificación de API define una o varias operaciones que un complemento puede usar a través de sus funciones.