OpenAPI Explorer:OpenAPI MCP Server Core Tool Usage Guide

ListProducts

Cuando es necesario conocer qué productos de Alibaba Cloud están disponibles, el agente de IA utiliza esta herramienta para consultar el catálogo de productos. Por ejemplo, al introducir "What compute-related products does Alibaba Cloud have", el agente de IA extrae palabras clave y filtra la lista de productos en consecuencia.

Guía de uso

• Especifique palabras clave del producto en la descripción. Por ejemplo, "What compute-related products does Alibaba Cloud have" es mejor que "What products does Alibaba Cloud have".

• Los resultados de la consulta pueden servir como contexto para conversaciones posteriores. Por ejemplo, primero pregunte "What database products are available" y luego solicite detalles operativos específicos de un producto en particular.

{
  "filter": "compute"
}

[
  {
    "code": "Ess",
    "name": "Auto Scaling",
    "group": "Elastic Computing",
    "style": "RPC",
    "versions": ["2014-08-28", "2022-02-22"],
    "defaultVersion": "2022-02-22"
  },
  {
    "code": "Ecs",
    "name": "Elastic Compute Service",
    "group": "Elastic Computing",
    "style": "RPC",
    "versions": ["2014-05-26"],
    "defaultVersion": "2014-05-26"
  },
  {
    "code": "Eci",
    "name": "Elastic Container Instance",
    "group": "Elastic Computing",
    "style": "RPC",
    "versions": ["2018-08-08"],
    "defaultVersion": "2018-08-08"
  }
]
// More results returned, only 3 shown here

ListApis

Cuando una operación del usuario involucra un producto específico pero el agente de IA necesita confirmar la operación exacta de la API, se utiliza esta herramienta para explorar la lista de API del producto. Por ejemplo, al introducir "Allocate a public IP to an ECS instance", el agente de IA puede consultar primero qué API de ECS son relevantes y luego seleccionar la adecuada para su ejecución.

Guía de uso

• Sea lo más específico posible sobre el producto y la acción al describir la intención operativa. Por ejemplo, "allocate a public IP to an ECS instance" es mejor que "allocate IP".

{
  "product": "Ecs",
  "filter": "Instance"
}

[
  {
    "summary": "Allocates a public IP address to an ECS instance.",
    "apiName": "AllocatePublicIpAddress",
    "title": "Allocate Public IP"
  },
  {
    "summary": "Attaches a RAM role to one or more ECS instances.",
    "apiName": "AttachInstanceRamRole",
    "title": "Attach RAM Role to Instance"
  }
]
// More results returned, only 2 shown here

GetApiDefinition

Cuando una solicitud del usuario implica una llamada a API, el agente de IA normalmente localiza primero la API objetivo mediante SearchApis o ListApis, luego usa esta herramienta para obtener las definiciones de parámetros de la API y finalmente construye la llamada correcta. Por ejemplo, al introducir "Query ECS instances in Hangzhou region", el agente de IA localiza primero la API DescribeInstances y luego confirma los parámetros obligatorios mediante esta herramienta antes de ejecutarla.

Guía de uso

• Sea lo más específico posible al describir la intención operativa. Una vez que el agente de IA localiza la API correcta, confirma automáticamente los parámetros y ejecuta la operación.

{
  "product": "Ecs",
  "apiVersion": "2014-05-26",
  "apiName": "DescribeInstances"
}

{
  "summary": "Queries an instance list based on different request conditions",
  "methods": ["post", "get"],
  "parameters": ["...45 parameters total, omitted here"],
  "responses": {"...": "omitted"},
  "errorCodes": ["...omitted"]
}

SearchApis

Cuando se desconoce el nombre exacto de la API, el agente de IA utiliza esta herramienta para encontrar la OpenAPI de Alibaba Cloud correspondiente según una descripción en lenguaje natural. Por ejemplo, al introducir "How to view ECS instance monitoring data", el agente de IA busca y encuentra las API de monitoreo relevantes.

Guía de uso

• Incluya el nombre del producto en la descripción. Por ejemplo, "query ECS security group rules" es mejor que "query security groups".

• Divida los requisitos complejos en varias preguntas independientes, cada una correspondiente a una sola operación de API.

• Si ya conoce el nombre de la API, especifíquelo directamente al agente de IA (por ejemplo, "use DescribeInstances to query") para omitir el paso de búsqueda.

{
  "prompt": "How to view ECS instance monitoring data",
  "limit": 3
}

[
  {
    "apiName": "DescribeInstanceMonitorData",
    "code": "Ecs",
    "description": "Calls DescribeInstanceMonitorData to query monitoring information for an ECS instance. Available metrics include vCPU utilization, burstable instance credits, received data traffic, sent data traffic, and average bandwidth.",
    "weight": 0.98,
    "version": "2014-05-26"
  },
  {
    "apiName": "QueryMetricList",
    "code": "Cms",
    "description": "Queries monitoring data for a specified product instance over a period of time.",
    "weight": 0.85,
    "version": "2016-09-22"
  },
  {
    "apiName": "DescribeMetricLast",
    "code": "Cms",
    "description": "Queries the latest monitoring data for a specified metric.",
    "weight": 0.75,
    "version": "2019-01-01"
  }
]

ListProductRegions

Cuando una operación implica la selección de región, el agente de IA utiliza esta herramienta para confirmar si la región objetivo admite el producto. Por ejemplo, al introducir "Can ECS be used in Ulanqab" o "Create an ECS instance in Singapore", el agente de IA verifica primero la disponibilidad de la región.

Guía de uso

• Especifique tanto el nombre del producto como la región objetivo en la consulta. Por ejemplo, "Can ECS be used in Ulanqab" es mejor que "Can it be used in Ulanqab".

• Cuando intervienen varias regiones, especifique cada una de ellas. Por ejemplo, "Confirm whether ECS is available in Hangzhou, Shanghai, and Singapore".

{
  "product": "Ecs"
}

{
  "code": 0,
  "data": {
    "type": "regional",
    "endpoints": [
      {
        "regionId": "us-west-1",
        "regionName": "US (Silicon Valley)",
        "public": "ecs.us-west-1.aliyuncs.com",
        "vpc": "ecs-vpc.us-west-1.aliyuncs.com"
      },
      {
        "regionId": "cn-hangzhou",
        "regionName": "China (Hangzhou)",
        "public": "ecs.cn-hangzhou.aliyuncs.com",
        "vpc": "ecs-vpc.cn-hangzhou.aliyuncs.com"
      }
    ]
  }
}
// More results returned, only 2 shown here

GenerateCLICommand

Cuando se indica "solo generar el comando sin ejecutar" o cuando el agente de IA necesita previsualizar un comando, esta herramienta genera una cadena de comando CLI. El agente de IA normalmente confirma primero los parámetros mediante GetApiDefinition, luego genera el comando con esta herramienta y finalmente lo ejecuta a través de CallCLI. Por ejemplo, al introducir "Generate a command to query ECS instances in Hangzhou", se devuelve un comando completo que puede ejecutarse en una terminal local.

Guía de uso

• Para ejecutar manualmente un comando en la terminal local, solicite al agente de IA que "solo genere el comando sin ejecutar". El comando generado puede copiarse y usarse directamente.

{
  "product": "Ecs",
  "apiVersion": "2014-05-26",
  "apiName": "DescribeInstances",
  "regionId": "cn-hangzhou",
  "jsonApiParameters": "{\"Status\": \"Running\", \"PageSize\": 100}"
}

{
  "cli": "aliyun ecs describe-instances --page-size 100 --status Running --region cn-hangzhou"
}

CallCLI

Cuando el agente de IA sabe exactamente qué operación de API ejecutar, utiliza esta herramienta para realizar la llamada directamente. Esta es la herramienta principal para llamadas a API en Core Edition. Por ejemplo, al introducir "Query running ECS instances in Hangzhou region", el agente de IA construye un comando CLI y ejecuta la consulta.

Guía de uso

• Los comandos CLI ejecutados por esta herramienta se ejecutan en un servidor remoto y no pueden leer archivos locales.

• Las operaciones de escritura (crear, modificar o eliminar recursos) pueden generar cargos. Solicite al agente de IA que confirme el contenido de la operación antes de ejecutarla.

{
  "command": "aliyun ecs describe-instances --biz-region-id cn-hangzhou --status Running"
}

{
  "Instances": {
    "Instance": []
  },
  "PageNumber": 1,
  "PageSize": 10,
  "TotalCount": 0
}

RunScript

Cuando una sola llamada a API no puede cumplir con el requisito, el agente de IA utiliza esta herramienta para escribir scripts destinados a operaciones por lotes. Por ejemplo, al introducir "Count ECS instances across all regions" o "Check all security groups for high-risk rules", el agente de IA escribe scripts concurrentes para consultar múltiples recursos simultáneamente.

Guía de uso

• Cuando se necesiten agregaciones, comparaciones u operaciones por lotes, describa claramente el alcance y el objetivo. Por ejemplo, "Count ECS instances across all regions" o "Check all security groups for high-risk rules".

• La ejecución del script puede tardar desde segundos hasta decenas de segundos. Espere pacientemente a que se devuelva el resultado.

{
  "script": "regions = ['cn-hangzhou', 'cn-shanghai', 'cn-beijing']\nresponses = await asyncio.gather(*[\n    call_cli(product='Ecs', action='DescribeInstances',\n             params={'RegionId': r, 'PageSize': 100})\n    for r in regions\n], return_exceptions=True)\nresult = {r: res.get('TotalCount', 0) if isinstance(res, dict) else str(res)\n    for r, res in zip(regions, responses)}"
}

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "status": "Running",
  "nextAction": "CallGetTask",
  "result": null,
  "waitTimedOut": true,
  "message": "Task not in terminal state. Call AlibabaCloud___GetTask to wait for result.",
  "error": null
}

GetTask

Cuando una tarea RunScript o RunIaC tarda mucho en ejecutarse, el agente de IA utiliza esta herramienta para esperar a que finalice la tarea y recuperar el resultado. Esta herramienta puede activarse durante operaciones que consumen mucho tiempo, como inspecciones entre regiones o despliegues de Terraform.

Guía de uso

• Para operaciones que consumen mucho tiempo (como inspecciones entre regiones o consultas por lotes), espere pacientemente a que se devuelva el resultado.

• Si se requiere aprobación manual, complete el proceso de aprobación según las indicaciones y el resultado continuará devolviéndose.

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "waitTimeoutSeconds": 25
}

{
  "processID": "proc_1f7b02be133a41ee89135fafb833a972",
  "status": "Succeeded",
  "nextAction": "None",
  "result": {
    "cn-hangzhou": 0,
    "cn-shanghai": 0,
    "cn-beijing": 0
  }
}

GetPresignedUrl

Cuando las herramientas RunIaC o RunScript necesitan hacer referencia a archivos externos, el agente de IA utiliza esta herramienta para generar un enlace de carga temporal. Por ejemplo, cuando el código de Terraform supera los 64 KB o un script necesita procesar archivos de datos cargados previamente, el agente de IA primero carga el archivo mediante esta herramienta antes de ejecutar las operaciones posteriores.

Guía de uso

• Cuando se trata de cargas de archivos grandes, puede ser necesario esperar a que finalice la carga antes de ejecutar las operaciones posteriores.

RunIaC

Cuando es necesario crear, modificar o destruir recursos en la nube, el agente de IA puede utilizar esta herramienta para gestionar la infraestructura mediante Terraform. Por ejemplo, al introducir "Create a VPC in Hangzhou with CIDR 172.16.0.0/16", el agente de IA genera primero la configuración del recurso y previsualiza los cambios; luego ejecuta la creación tras la confirmación.

Guía de uso

• Al describir los requisitos de recursos, especifique claramente la región, las especificaciones y el nombre. Por ejemplo, "Create a VPC in Hangzhou with CIDR 172.16.0.0/16, named mcp-demo-vpc".

• Los cambios en los recursos pueden requerir aprobación manual. Complete el proceso de aprobación según las indicaciones.

SearchDocuments

Cuando se formula una pregunta basada en conocimientos sobre el uso de productos, métodos de configuración o resolución de errores, el agente de IA utiliza esta herramienta para buscar en la documentación oficial de Alibaba Cloud. Por ejemplo, al introducir "How to optimize Function Compute cold start" o "How to configure OSS Bucket Policy", se activa una búsqueda de documentos oficiales coincidentes.

Guía de uso

• Incluir el nombre del producto en la consulta mejora la relevancia de los resultados de búsqueda. Por ejemplo, "OSS cross-origin configuration" es mejor que "cross-origin configuration".

• Cuando se necesita documentación de un producto específico, indique el nombre del producto. Por ejemplo, "Function Compute cold start optimization documentation" es mejor que "cold start optimization".

{
  "query": "ECS instance creation",
  "limit": 3
}

{
  "results": [
    {
      "doc_id": 108442,
      "title": "Creation Methods",
      "url": "https://www.alibabacloud.com/help/zh/ecs/user-guide/create-instances/",
      "product": "Elastic Compute Service",
      "content": "This topic describes several methods of creating ECS instances...",
      "website": "cn",
      "language": "zh"
    },
    {
      "doc_id": 151725,
      "title": "ECS Instance Provisioning Methods",
      "url": "https://www.alibabacloud.com/help/zh/ecs/user-guide/provisioning-methods-of-ecs-instances",
      "product": "Elastic Compute Service",
      "content": "Manually create one or more instances...",
      "website": "cn",
      "language": "zh"
    }
  ],
  "matched_filters": {
    "product": "",
    "doc_type": null,
    "website": "cn",
    "language": "zh"
  }
}

GetDocument

Después de que el agente de IA localiza los documentos relevantes mediante SearchDocuments, utiliza esta herramienta para leer el contenido completo y responder a la pregunta. Por ejemplo, al introducir "How to optimize Function Compute cold start?", el agente de IA busca y localiza primero el documento, luego lee el texto completo y organiza la respuesta.

Guía de uso

• El agente de IA lee y organiza automáticamente el contenido después de localizar los documentos. Todo el proceso es transparente para el usuario.

{
  "doc_id": 108442,
  "max_length": 500
}

{
  "doc_id": 108442,
  "url": "https://www.alibabacloud.com/help/ecs/user-guide/create-instances",
  "title": "Create Instances",
  "product": "ecs",
  "content": "This topic describes several methods of creating ECS instances..."
}

GetDocumentTree

Cuando un usuario desea comprender la estructura de documentación de un producto, el agente de IA utiliza esta herramienta para explorar el árbol de directorios de documentos. Por ejemplo, al introducir "What does the OSS documentation structure look like" o "What user guides does ECS have".

Guía de uso

• Especifique el nombre del producto en la consulta. Por ejemplo, "What document categories does OSS have" o "What chapters are under the ECS user guide".

{
  "doc_id": 108442,
  "depth": 1
}

{
  "product": "Elastic Compute Service",
  "website": "cn",
  "language": "zh",
  "children": [
    {"title": "User Guide", "doc_id": 2399509, "url": "https://www.alibabacloud.com/help/ecs/user-guide", "children": []},
    {"title": "Developer Reference", "doc_id": 2399511, "url": "https://www.alibabacloud.com/help/ecs/developer-reference", "children": []},
    {"title": "Billing", "doc_id": 25396, "children": []},
    {"title": "FAQ", "doc_id": 2983136, "children": []}
  ]
}
// This example uses depth=1, returning only top-level nodes. Set depth to 2 or 3 to include sub-chapters

GrepDocuments

Cuando una pregunta involucra términos específicos, elementos de configuración o códigos de error, el agente de IA utiliza esta herramienta para realizar una coincidencia exacta de palabras clave dentro de la documentación de un producto especificado. Por ejemplo, al introducir "What values does InstanceChargeType have in ECS documentation" o "Search for CORS-related content in OSS documentation".

Guía de uso

• Especifique tanto el producto como la palabra clave en la consulta. Por ejemplo, "Search for DescribeInstanceAttribute in ECS documentation".

• Palabras clave más precisas generan resultados más relevantes. Múltiples palabras clave tienen una relación Y (AND).

{
  "product": "ecs",
  "pattern": "DescribeInstanceAttribute",
  "limit": 3
}

{
  "product_code": "ecs",
  "pattern": "DescribeInstanceAttribute",
  "matches": [
    {
      "title": "DescribeInstanceAttribute - Query instance attribute information",
      "url": "https://www.alibabacloud.com/help/ecs/developer-reference/api-ecs-2014-05-26-describeinstanceattribute",
      "matched_text": "DescribeInstanceTypes - Query instance type information list\nDescribeInstanceAttribute - Query instance attribute information\nModifyInstanceAttribute - Modify instance attribute information",
      "line_no": 986
    }
  ],
  "total": 1,
  "truncated": false,
  "llms_txt_url": "https://www.alibabacloud.com/help/zh/ecs/llms.txt"
}

Check the security group rules in the Hangzhou region

Count the number of ECS instances in Hangzhou, Shanghai, and Beijing regions

Function Compute cold start latency is high. What optimization options are available?