Esquema de manifiesto del complemento de API 2.2 para Microsoft 365 Copilot

Artículo
11/19/2024

Los complementos de API permiten que Microsoft 365 Copilot interactúen con las API REST descritas por una descripción de OpenAPI. La descripción de OpenAPI en un complemento de API describe las API REST con las que Copilot puede interactuar. Además, un complemento de API incluye un archivo de manifiesto de complemento que proporciona metadatos sobre el complemento, como el nombre, la descripción y la versión del complemento. El manifiesto del complemento también incluye información sobre las funcionalidades del complemento, como las API que admite y las operaciones que puede realizar.

En el siguiente artículo se describe el esquema 2.2 que usan los archivos de manifiesto del complemento de API. Para obtener más información sobre los complementos de API, consulte Complementos de API para Microsoft 365 Copilot.

Cambios de la versión anterior

Esta versión del esquema presenta los siguientes cambios de la versión 2.1.

Se agregó la security_info propiedad al objeto Function capabilities. Esta propiedad permite atestiguar el comportamiento del complemento con el fin de evaluar los riesgos de llamar a la función.
Se quitó la propiedad en desuso localization del objeto de funcionalidades del complemento. Los manifiestos generados con teams Toolkit mediante el esquema 2.1 incluían la propiedad en localization desuso. Los manifiestos que usan el esquema 2.2 producirán un error de validación si se incluye esta propiedad.

Esquema JSON

El esquema descrito en este documento se puede encontrar en formato de esquema JSON aquí.

Convenios

Referencias relativas en direcciones URL

A menos que se especifique lo contrario, todas las propiedades que son direcciones URL PUEDEN ser referencias relativas. Las referencias relativas en el documento de manifiesto son relativas a la ubicación del documento de manifiesto.

Longitud de cadena

A menos que se especifique lo contrario, todas las propiedades de cadena DEBEN estar limitadas a 4 000 caracteres. Esta longitud de cadena no confiere ningún tamaño aceptable para todo el documento. Implementa una libertad para imponer sus propios límites prácticos sobre la longitud del manifiesto.

Propiedades no reconocidas

Los objetos JSON definidos en este documento solo admiten las propiedades descritas. Las propiedades no reconocidas en cualquier objeto JSON DEBEN hacer que todo el documento no sea válido.

Localización de cadenas

Las cadenas localizables pueden usar una clave de localización en lugar de un valor literal. La sintaxis es [[key_name]], donde key_name es el nombre clave de la localizationKeys propiedad de los archivos de localización. Para obtener más información sobre la localización, consulte Localización del agente.

Ejemplo de cadena localizada

{
    "schema_version": "v2.2",
    "name_for_human": "[[plugin_name]]",
    "description_for_human": "[[plugin_description]]"
}

Objeto de manifiesto del complemento

La raíz del documento de manifiesto del complemento es un objeto JSON que contiene propiedades que describen el complemento.

El objeto de manifiesto del complemento contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`schema_version`	Cadena	Obligatorio. Versión del esquema. Las versiones anteriores son `v1` y `v2`. Se debe configurar como `v2.2`.
`name_for_human`	Cadena	Obligatorio. Un nombre corto y legible para el complemento. DEBE contener al menos un carácter nowhitespace. Los caracteres posteriores a 20 PUEDEN omitirse. Esta propiedad es localizable.
`namespace`	String	Obsoleto. Opcional.
`description_for_model`	Cadena	Opcional. Descripción del complemento que se proporciona al modelo. Esta descripción debe describir para qué es el complemento y, en qué circunstancias, sus funciones son pertinentes. Los caracteres posteriores a 2048 PUEDEN omitirse. Esta propiedad es localizable.
`description_for_human`	Cadena	Obligatorio. Descripción legible del complemento. Los caracteres posteriores a 100 PUEDEN omitirse. Esta propiedad es localizable.
`logo_url`	Cadena	Opcional. Dirección URL usada para capturar un logotipo que puede usar el orquestador. Las implementaciones PUEDEN proporcionar métodos alternativos para proporcionar logotipos que cumplan sus requisitos visuales. Esta propiedad es localizable.
`contact_email`	Cadena	Opcional. Dirección de correo electrónico de un contacto para seguridad/moderación, soporte técnico y desactivación.
`legal_info_url`	Cadena	Opcional. Dirección URL absoluta que busca un documento que contiene los términos de servicio del complemento. Esta propiedad es localizable.
`privacy_policy_url`	Cadena	Opcional. Dirección URL absoluta que busca un documento que contiene la directiva de privacidad del complemento. Esta propiedad es localizable.
`functions`	Matriz del objeto Function	Opcional. Conjunto de objetos de función que describen las funciones disponibles para el complemento. Cada nombre de objeto de función DEBE ser único dentro de la matriz. El orden de la matriz no es significativo. Si la `functions` propiedad no está presente y hay un entorno de ejecución de OpenAPI, las funciones se deducen de las operaciones de OpenAPI.
`runtimes`	Matriz del objeto en tiempo de ejecución de OpenAPI	Opcional. Conjunto de objetos en tiempo de ejecución que describen los tiempos de ejecución usados por el complemento.
`capabilities`	Objeto de funcionalidades del complemento	Opcional. Describe las funcionalidades del complemento.

Function (objeto)

Información relacionada con cómo debe interactuar el modelo con una función.

El objeto de función contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`id`	Cadena	Opcional.
`name`	Cadena	Obligatorio. Cadena que identifica de forma única esta función. Los objetos en tiempo de ejecución PUEDEN hacer referencia a este identificador para enlazar el tiempo de ejecución a la función . Cuando la función está enlazada a un entorno de ejecución de OpenAPI, el valor debe coincidir con un `operationId` valor de la descripción de OpenAPI. El valor debe coincidir con la `^[A-Za-z0-9_]+$` expresión regular.
`description`	Cadena	Opcional. Una descripción mejor adaptada al modelo, como consideraciones sobre la longitud del contexto del token o el uso de palabras clave para mejorar la solicitud del complemento.
`parameters`	Objeto de parámetros de función	Opcional. Objeto que contiene propiedades que describen los parámetros de una función de forma independiente en tiempo de ejecución. Refleja la forma de json-schema , pero solo admite un pequeño subconjunto de las funcionalidades del esquema JSON. Si la `parameters` propiedad no está presente, las funciones descritas por un objeto en tiempo de ejecución de tipo `OpenApi` usan la descripción de OpenAPI para determinar los parámetros. Cada miembro del objeto JSON es un objeto de parámetro de función que describe la semántica del parámetro.
`returns`	Objeto Return O bien, objeto devuelto enriquecido	Opcional. Describe la semántica del valor devuelto por la función.
`states`	Objeto de estados de función	Opcional. Define objetos de estado para los estados de orquestador.
`capabilities`	Function capabilities (objeto)	Opcional. Contiene una colección de datos que se usan para configurar funcionalidades opcionales del orquestador al invocar la función.

Ejemplo de objeto de función

{
  "functions": [
    {
      "name": "add_todo",
      "description": "Adds a new Todo",
      "parameters": {
        "type": "object",
        "properties": {
          "description": {
            "type": "string"
          }
        },
        "required": [
          "description"
        ]
      },
      "returns": {
        "type": "string"
      }
    }
  ]
}

Objeto de parámetros de función

Objeto que se usa para identificar el conjunto de parámetros que se pueden pasar a la función. Este objeto está estructurado para reflejar la forma de un objeto de esquema JSON, pero solo admite un subconjunto de palabras clave de esquema JSON.

El objeto de parámetros de función contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`type`	Cadena	Opcional. Tipo de esquema JSON. Se debe establecer en `object`.
`properties`	Objeto de propiedades de parámetros de función	Obligatorio. Objeto que asigna nombres de parámetros a sus definiciones.
`required`	Matriz de cadenas	Opcional. Los nombres de las propiedades que son parámetros necesarios. A diferencia del esquema JSON, los valores de esta matriz DEBEN coincidir con los nombres enumerados en la `properties` propiedad .

Ejemplo de objeto de parámetros de función

{
  "type": "object",
  "properties": {
    "param1": {
      "type": "string"
    },
    "param2": {
      "type": "number"
    }
  },
  "required": [
    "param1"
  ]
}

Objeto de propiedades de parámetros de función

Objeto que asigna nombres de parámetros a sus definiciones.

El objeto de propiedades de parámetros de función contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
Coincidencia de nombres `^[A-Za-z0-9_]+$`	Objeto de parámetro de función	Opcional. Definición de parámetro que corresponde al parámetro que coincide con el nombre de la propiedad.

Objeto de parámetro de función

Objeto que describe la semántica de un parámetro de función.

El objeto de parámetro de función contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`type`	Cadena	Obligatorio. Especifica el tipo del parámetro. Los valores posibles son: `string`, `array`, `boolean`, `integer` y `number`.
`items`	Objeto de parámetro de función	Opcional. Objeto de parámetro de función que describe un único elemento de una matriz. SOLO DEBE estar presente cuando `type` es `array`.
`enum`	Matriz de cadenas	Opcional. Matriz de valores válidos para este parámetro. SOLO DEBE estar presente cuando `type` es `string`.
`description`	Cadena	Opcional. Una descripción del parámetro.
`default`	Array, Boolean, String, Number, Integer	Opcional. Valor del tipo especificado por la `type` propiedad que indica el valor que usa la API cuando no se proporciona un valor para un parámetro opcional.

Ejemplo de parámetro de función

{
  "type": "string",
  "description": "The color of the item",
  "enum": [
    "green",
    "blue",
    "orange"
  ]
}

Objeto Return

Contiene la semántica del valor devuelto por la función.

El objeto devuelto contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`type`	Cadena	Obligatorio. Especifica el tipo del valor devuelto por la API. Los valores posibles son: `string`.
`description`	Cadena	Opcional. Descripción del valor devuelto por la API.

Objeto devuelto enriquecido

Indica que la función devuelve una respuesta compatible con el protocolo respuestas enriquecidas.

El objeto devuelto enriquecido contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`$ref`	Cadena	Obligatorio. Se debe establecer en `https://copilot.microsoft.com/schemas/rich-response-v1.0.json`.

Objeto de estados de función

Define objetos de estado para los estados de orquestador.

El objeto de estados de función contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`reasoning`	State (objeto)	Opcional. Estado en el que el modelo puede llamar a funciones y realizar cálculos.
`responding`	State (objeto)	Opcional. Estado en el que el modelo puede generar texto que se muestra al usuario. El modelo no puede invocar funciones en el estado de respuesta.
`disengaging`	State (objeto)	Opcional.

State (objeto)

Contiene instrucciones específicas para cuando se invoca una función en un estado de orquestador específico.

El objeto de estado contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`description`	Cadena	Opcional. Describe el propósito de una función cuando se usa en un estado de orquestador específico.
`instructions`	Matriz, cadena	Opcional. Una cadena o una matriz de cadenas que se usan para proporcionar instrucciones al orquestador sobre cómo usar esta función mientras se encuentra en un estado de orquestador específico. Proporcionar una sola cadena indica la intención de proporcionar un conjunto completo de instrucciones que invalidarían cualquier solicitud de función integrada. Proporcionar una matriz de cadenas indica la intención de aumentar el mecanismo de solicitud de función integrada.
`examples`	Matriz, cadena	Opcional. Una cadena o una matriz de cadenas que se usan para proporcionar ejemplos al orquestador sobre cómo se puede invocar esta función.

Ejemplo de objeto State

{
  "functions": [
    {
      "name": "searchEmails",
      "description": "search for Emails from using 3S search Service",
      "states": {
        "reasoning": {
          "description": "\n# `searchEmails(**params) -> str` returns the emails from user's inbox based on search query.",
          "instructions": [
            "Examine the output of `searchEmails(**params) -> str`.",
            "Do not include any information that is not present in the JSON results.",
            "Exclude any irrelevant data from the JSON results",
            "Determine if the response contains an error field.",
            "If an error is present, provide the error code and error message extracted from the response JSON.",
            "If there is no error, extract and include as much relevant information as possible from the JSON result to meet the user's needs."
          ],
          "examples": []
        }
      }
    }
  ]
}

Function capabilities (objeto)

Contiene una colección de datos que se usan para configurar funcionalidades opcionales del orquestador al invocar la función.

El objeto function capabilities contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`confirmation`	Objeto de confirmación	Opcional. Describe un cuadro de diálogo de confirmación que DEBE presentarse al usuario antes de invocar la función.
`response_semantics`	Objeto de semántica de respuesta	Opcional. Describe cómo el orquestador puede interpretar la carga de respuesta y proporcionar una representación visual.
`security_info`	Objeto de información de seguridad	Opcional. Contiene atestaciones sobre el comportamiento del complemento con el fin de evaluar los riesgos de llamar a la función. Si se omite esta propiedad, la función no puede interactuar con otros complementos o funcionalidades del agente contenedor.

Objeto de confirmación

Describe cómo el orquestador pide al usuario que confirme antes de llamar a una función.

El objeto de confirmación contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`type`	Cadena	Opcional. Especifica el tipo de confirmación. Los valores posibles son `None` y `AdaptiveCard`.
`title`	Cadena	Opcional. Título del cuadro de diálogo de confirmación. Esta propiedad es localizable.
`body`	Cadena	Opcional. Texto del cuadro de diálogo de confirmación. Esta propiedad es localizable.

Objeto de semántica de respuesta

Contiene información para identificar la semántica de la carga de respuesta y habilitar la representación de esa información en una experiencia visual enriquecida mediante tarjetas adaptables.

El objeto de semántica de respuesta contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`data_path`	Cadena	Obligatorio. Una consulta JSONPath RFC9535 que identifica un conjunto de elementos de la respuesta de función que se va a representar mediante la plantilla especificada en cada elemento.
`properties`	Objeto de propiedades semánticas de respuesta	Opcional. Permite la asignación de consultas JSONPath a elementos de datos conocidos. Cada consulta JSONPath es relativa a un valor de resultado.
`static_template`	Objeto	Opcional. Objeto JSON que se ajusta al esquema de tarjeta adaptable y al lenguaje de plantillas. Esta instancia de tarjeta adaptable se usa para representar un resultado de la respuesta del complemento. Este valor se usa si `template_selector` no está presente o no se resuelve en una tarjeta adaptable.
`oauth_card_path`	Cadena	Opcional.

Ejemplo de plantilla estática

{
  "functions": {
    "capabilities": {
      "response_semantics": {
        "data_path": "$.resources",
        "properties": {
          "title": "$.name",
          "subtitle": "$.location",
          "url": "$.href",
          "information_protection_label": "$.ipLabel"
        },
        "static_template": {
          "$schema": "http://adaptivecards.io/schemas/adaptive-card.json",
          "type": "AdaptiveCard",
          "version": "1.5",
          "body": [
            {
              "type": "TextBlock",
              "text": "${name}",
              "weight": "Bolder"
            },
            {
              "type": "TextBlock",
              "text": "${description}"
            }
          ],
          "action": [
            {
              "type": "Action.OpenUrl",
              "title": "View",
              "text": "${href}"
            }
          ]
        }
      }
    }
  }
}

Ejemplo de plantilla dinámica

{
  "functions": {
    "capabilities": {
      "response_semantics": {
        "data_path": "$.attachments",
        "properties": {
          "title": "$.title",
          "subtitle": "$.subtitle",
          "url": "$.url",
          "thumbnail_url": "$.thumbnailUrl",
          "template_selector": "$.template"
        }
      }
    }
  }
}

Objeto de propiedades semánticas de respuesta

Permite la asignación de consultas JSONPath a elementos de datos conocidos. Cada consulta JSONPath es relativa a un valor de resultado.

El objeto de propiedades semánticas de respuesta contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`title`	Cadena	Opcional. Título de una cita para el resultado.
`subtitle`	Cadena	Opcional. Subtítulo de una cita para el resultado.
`url`	Cadena	Opcional. Dirección URL de una cita para el resultado.
`thumbnail_url`	Cadena	Opcional. Dirección URL de una imagen en miniatura para el resultado.
`information_protection_label`	Cadena	Opcional. Indicador de confidencialidad de datos del contenido del resultado.
`template_selector`	Cadena	Opcional. Expresión JSONPath en una instancia de tarjeta adaptable que se va a usar para representar el resultado.

Objeto de información de seguridad

Contiene información que se usa para determinar el riesgo relativo de invocar la función.

El objeto de información de seguridad contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`data_handling`	Matriz de cadenas	Obligatorio. Matriz de cadenas que describen el comportamiento de control de datos de la función. Los valores válidos son `GetPublicData`, `GetPrivateData`, `DataTransform`, `DataExport`y `ResourceStateUpdate`.

Valores de control de datos

Valor	Descripción	Ejemplo
`GetPublicData`	Indica que la función recupera datos de un origen externo que no requiere autenticación.	Función que realiza una llamada de servicio para recuperar datos de un sitio web público.
`GetPrivateData`	Indica que la función recupera datos de un origen externo que requiere autenticación o de la aplicación actual del usuario.	Función que obtiene datos de una base de datos privada o del documento abierto actualmente del usuario.
`DataTransform`	Indica que la función solo devuelve una salida basada en la entrada, sin introducir datos nuevos ni provocar una actualización de recursos.	Función que convierte un número en una palabra o da formato a una fecha.
`DataExport`	Indica que la función envía o escribe datos en una ubicación fuera de la propia función.	Función que guarda datos en un archivo local o en la nube.
`ResourceStateUpdate`	Indica que la función afecta a un recurso iniciando una transacción, cambiando un proceso en el mundo real, concediendo o denegando permisos, o realizando cualquier otra acción que requiera confirmación explícita del usuario.	Función que reserva una habitación de hotel o cambia el estado de un elemento de trabajo de `active` a `resolved`.

Nota:

Los manifiestos de complemento que usan el DataExport valor pueden producir un error de validación al intentar instalar el complemento. Esto es temporal y se resolverá pronto.

Objeto en tiempo de ejecución de OpenAPI

Describe cómo invoca el complemento las funciones de OpenAPI.

El objeto en tiempo de ejecución de OpenAPI contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`type`	Cadena	Obligatorio. Identifica este tiempo de ejecución como un entorno de ejecución de OpenAPI. Se debe establecer en `OpenApi`.
`auth`	Objeto de autenticación en tiempo de ejecución	Obligatorio. Información de autenticación necesaria para invocar el entorno de ejecución.
`run_for_functions`	Matriz de cadenas	Opcional. Los nombres de las funciones que están disponibles en este entorno de ejecución. Si se omite esta propiedad, están disponibles todas las funciones descritas por el tiempo de ejecución. Los valores de cadena proporcionados pueden contener caracteres comodín. Más de un entorno de ejecución NO DEBE declarar la compatibilidad con la misma función de forma implícita o explícita.
`spec`	Objeto de especificación de OpenAPI	Obligatorio. Contiene la información de OpenAPI necesaria para invocar el entorno de ejecución.

Objeto de especificación de OpenAPI

Contiene la información de OpenAPI necesaria para invocar el entorno de ejecución.

El objeto de especificación de OpenAPI contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`url`	Cadena	Opcional. Dirección URL para capturar la especificación de OpenAPI, a la que se llama con una solicitud GET. Este miembro es necesario a menos que `api_description` esté presente.
`api_description`	Cadena	Opcional. Cadena que contiene una descripción de OpenAPI. Si este miembro está presente, `url` no es necesario y se omite si está presente.
`progress_style`	Cadena	Opcional. Estilo de progreso que se usa para mostrar el progreso de la función. Los valores posibles son: `None`, `ShowUsage`, `ShowUsageWithInput` y `ShowUsageWithInputAndOutput`.

Ejemplo de objeto de especificación de OpenAPI

{
  "runtimes":
  [
    {  
      "type": "OpenApi",
      "auth": {
        "type": "None"
      },
      "spec": {
        "url": "https://example.org/api/openapi.yaml",  
      }
    }
  ]
}

Objeto de autenticación en tiempo de ejecución

Contiene información usada por el complemento para autenticarse en el entorno de ejecución.

El objeto de autenticación en tiempo de ejecución contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`type`	Cadena	Opcional. Especifica el tipo de autenticación necesario para invocar una función. Los valores posibles son: `None`, `OAuthPluginVault` y `ApiKeyPluginVault`.
`reference_id`	Cadena	Opcional. Valor que se usa cuando `type` es `OAuthPluginVault` o `ApiKeyPluginVault`. El `reference_id` valor se adquiere de forma independiente al proporcionar los valores de configuración de autenticación necesarios. Este mecanismo existe para evitar la necesidad de almacenar valores secretos en el manifiesto del complemento.

Ejemplo de objeto de autenticación en tiempo de ejecución

{
  "type": "OAuthPluginVault",
  "reference_id": "0123456-abcdef"
}

Objeto de funcionalidades del complemento

Describe las funcionalidades del complemento.

El objeto de funcionalidades del complemento contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`conversation_starters`	Matriz del objeto de inicio de conversación	Opcional. Inicios de conversación que se pueden mostrar al usuario para obtener sugerencias sobre cómo invocar el complemento.

Objeto de inicio de conversación

Ejemplo de una pregunta a la que el complemento puede responder.

El objeto de inicio de conversación contiene las siguientes propiedades.

Propiedad	Tipo	Descripción
`text`	Cadena	Obligatorio. Texto del inicio de la conversación. Esta propiedad es localizable.
`title`	Cadena	Opcional. Título del inicio de la conversación. Esta propiedad es localizable.

Ejemplo de objeto de inicio de conversación

{
  "conversation_starters": [
    {
      "title": "Developer tasks",
      "text": "What issues are assigned to me?"
    }
  ]
}

Ejemplo de manifiesto

Este es un ejemplo de un archivo de manifiesto de complemento que usa la mayoría de las propiedades de manifiesto y las propiedades del objeto descritas en el artículo:

{
  "schema_version": "v2.2",
  "name_for_human": "Contoso Real Estate",
  "description_for_human": "Find up-to-date, detailed real estate properties for sale on the market",
  "description_for_model": "Plugin for finding properties for sale. Use it whenever a user asks about real estate properties for sale on the market. This plugin can be used to search for properties in a particular city, and with a given number of bedrooms, bathrooms, and amenities.",
  "capabilities": {
    "conversation_starters": [
      {
        "title": "Available listings",
        "text": "What listings are available in my area?"
      }
    ]
  },
  "functions": [
    {
      "name": "getListings",
      "description": "Get a list of properties matching the specified criteria",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "The city to search properties in"
          },
          "bedrooms": {
            "type": "number",
            "description": "The number of bedrooms the property should have"
          },
          "bathrooms": {
            "type": "number",
            "description": "The number of bathrooms the property should have"
          },
          "amenities": {
            "type": "array",
            "description": "The list of amenities the property should have",
            "items": {
              "type": "string",
              "description": "One amenity the property should have",
              "enum": [
                "air conditioning",
                "balcony",
                "dishwasher",
                "elevator",
                "fireplace",
                "furniture",
                "garden",
                "gym",
                "heating",
                "jacuzzi",
                "laundry room",
                "microwave",
                "no furniture",
                "parking",
                "patio",
                "sauna",
                "swimming pool",
                "terrace",
                "wi-fi"
              ]
            }
          }
        }
      },
      "returns": {
        "type": "string",
        "description": "A list of properties"
      },
      "states": {
        "reasoning": {
          "description": "`getListings` returns a list of real estate properties for sale based on the specified criteria.",
          "instructions": [
            "If the user mentions a city in their question, only search in that city by using the city parameter.",
            "If the user asks for properties with things like parking space, heating, jacuzzi, or similar amenities, use the amenities parameter to filter the results.",
            "Only use the list of amenities provided in the amenities parameter enum. If the user asked for an amenity that is not in the list, find the closest match from the list, or ignore it if no match can be found.",
            "Determine if the response contains an error field.",
            "If an error is present, provide the error code and error message from the JSON response to the user.",
            "If there is no error, extract and include as much relevant information as possible from the JSON response to meet the users needs."
          ]
        }
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "GetPublicData",
            "GetPrivateData"
          ]
        }
      }
    },
    {
      "name": "saveSearch",
      "description": "Save a search for properties for sale",
      "parameters": {
        "type": "object",
        "properties": {
          "city": {
            "type": "string",
            "description": "The city to search in"
          },
          "bedrooms": {
            "type": "number",
            "description": "The number of bedrooms"
          }
        },
        "required": [
          "city"
        ]
      },
      "returns": {
        "type": "string",
        "description": "The unique ID for the saved search"
      },
      "states": {
        "responding": {
          "description": "`saveSearch` returns a unique ID that identifies the newly saved search.",
          "instructions": [
            "Examine the output of the `saveSearch` function.",
            "Extract the unique ID integer from the output and include it in your response to the user."
          ]
        }
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "ResourceStateUpdate"
          ]
        }
      }
    },
    {
      "name": "deleteSavedSearch",
      "description": "Delete a previously saved search",
      "parameters": {
        "type": "object",
        "properties": {
          "id": {
            "type": "integer",
            "description": "The unique ID of the saved search"
          }
        },
        "required": [
          "id"
        ]
      },
      "returns": {
        "type": "string",
        "description": "True if the saved search was deleted, false otherwise"
      },
      "capabilities": {
        "security_info": {
          "data_handling": [
            "ResourceStateUpdate"
          ]
        }
      }
    }
  ],
  "runtimes": [
    {
      "type": "OpenApi",
      "auth": {
        "type": "none"
      },
      "run_for_functions": [
        "getListings",
        "saveSearch",
        "deleteSavedSearch"
      ],
      "spec": {
        "url": "http://contoso.com/openapi.yaml"
      }
    }
  ],
  "logo_url": "http://contoso.com/logo.png",
  "contact_email": "contact@contoso.com",
  "legal_info_url": "https://contoso.com/legal/"
}

Complementos de API para Microsoft 365 Copilot

Compartir a través de