OpenAPI Explorer:OpenAPI MCP Server Core Tool Usage Guide

ListProducts

Para identificar quais produtos da Alibaba Cloud estão disponíveis, o AI Agent usa esta ferramenta para consultar o catálogo de produtos. Por exemplo, ao inserir "What compute-related products does Alibaba Cloud have", o AI Agent extrai palavras-chave e filtra a lista de produtos adequadamente.

Orientações de uso

• Especifique palavras-chave do produto na descrição. Por exemplo, "What compute-related products does Alibaba Cloud have" é melhor do que "What products does Alibaba Cloud have".

• Use os resultados da consulta como contexto para conversas subsequentes. Por exemplo, primeiro pergunte "What database products are available" e depois solicite detalhes operacionais específicos de um produto.

{
  "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

Se uma operação do usuário envolver um produto específico, mas o AI Agent precisar confirmar a operação exata da API, use esta ferramenta para navegar pela lista de APIs do produto. Por exemplo, ao inserir "Allocate a public IP to an ECS instance", o AI Agent pode primeiro consultar quais APIs do ECS são relevantes e então selecionar a apropriada para execução.

Orientações de uso

• Seja o mais específico possível sobre o produto e a ação ao descrever a intenção operacional. Por exemplo, "allocate a public IP to an ECS instance" é melhor do 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

Quando uma solicitação do usuário envolve uma chamada de API, o AI Agent normalmente localiza primeiro a API alvo por meio de SearchApis ou ListApis. Em seguida, usa esta ferramenta para obter as definições de parâmetros da API e, finalmente, constrói a chamada correta. Por exemplo, ao inserir "Query ECS instances in Hangzhou region", o AI Agent localiza primeiro a API DescribeInstances e confirma os parâmetros necessários por meio desta ferramenta antes de executar.

Orientações de uso

• Seja o mais específico possível ao descrever a intenção operacional. Assim que o AI Agent localizar a API correta, ele confirmará automaticamente os parâmetros e executará a ação.

{
  "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

Se o nome exato da API for desconhecido, o AI Agent usa esta ferramenta para localizar a Alibaba Cloud OpenAPI apropriada com base em uma descrição em linguagem natural. Por exemplo, ao inserir "How to view ECS instance monitoring data", o AI Agent pesquisa e encontra as APIs de monitoramento relevantes.

Orientações de uso

• Inclua o nome do produto na descrição. Por exemplo, "query ECS security group rules" é melhor do que "query security groups".

• Divida requisitos complexos em várias perguntas independentes, cada uma correspondendo a uma única operação de API.

• Se já souber o nome da API, especifique-o diretamente ao AI Agent (por exemplo, "use DescribeInstances to query") para pular a etapa de pesquisa.

{
  "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

Se uma operação envolver a seleção de região, o AI Agent usa esta ferramenta para confirmar se a região alvo oferece suporte ao produto. Por exemplo, ao inserir "Can ECS be used in Ulanqab" ou "Create an ECS instance in Singapore", o AI Agent verifica primeiro a disponibilidade da região.

Orientações de uso

• Especifique tanto o nome do produto quanto a região alvo na consulta. Por exemplo, "Can ECS be used in Ulanqab" é melhor do que "Can it be used in Ulanqab".

• Se houver várias regiões envolvidas, especifique cada uma delas. Por exemplo, "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

Se receber a instrução "only generate the command without executing" ou se o AI Agent precisar visualizar um comando, esta ferramenta gera uma string de comando CLI. O AI Agent geralmente confirma primeiro os parâmetros por meio de GetApiDefinition, depois gera o comando através desta ferramenta e, finalmente, o executa via CallCLI. Por exemplo, ao inserir "Generate a command to query ECS instances in Hangzhou", a ferramenta retorna um comando completo executável em um terminal local.

Orientações de uso

• Para executar manualmente um comando no terminal local, solicite ao AI Agent que "only generate the command without executing". Copie e use o comando gerado diretamente.

{
  "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

Se o AI Agent souber exatamente qual operação de API executar, use esta ferramenta para fazer a chamada diretamente. Esta é a principal ferramenta para chamadas de API na Edição Principal. Por exemplo, ao inserir "Query running ECS instances in Hangzhou region", o AI Agent constrói um comando CLI e executa a consulta.

Orientações de uso

• Os comandos CLI executados por esta ferramenta rodam em um servidor remoto e não podem ler arquivos locais.

• Operações de escrita (criar, modificar ou excluir recursos) podem gerar cobranças. Solicite ao AI Agent que confirme o conteúdo da operação antes da execução.

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

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

RunScript

Se uma única chamada de API não atender ao requisito, o AI Agent usa esta ferramenta para escrever scripts destinados a operações em lote. Por exemplo, ao inserir "Count ECS instances across all regions" ou "Check all security groups for high-risk rules", o AI Agent escreve scripts concorrentes para consultar vários recursos simultaneamente.

Orientações de uso

• Se forem necessárias agregação, comparação ou operações em lote, descreva claramente o escopo e o objetivo. Por exemplo, "Count ECS instances across all regions" ou "Check all security groups for high-risk rules".

• A execução do script pode levar de segundos a dezenas de segundos. Aguarde o retorno do 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

Se uma tarefa RunScript ou RunIaC demorar muito para ser executada, o AI Agent usa esta ferramenta para aguardar a conclusão da tarefa e recuperar o resultado. Esta ferramenta pode ser acionada durante operações demoradas, como inspeção entre regiões ou implantação do Terraform.

Orientações de uso

• Em operações demoradas (como inspeção entre regiões ou consultas em lote), aguarde o retorno do resultado.

• Se for necessária aprovação manual, conclua o processo conforme solicitado para que o resultado seja retornado.

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

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

GetPresignedUrl

Se as ferramentas RunIaC ou RunScript precisarem referenciar arquivos externos, o AI Agent usa esta ferramenta para gerar um link temporário de upload. Por exemplo, quando o código do Terraform excede 64 KB ou um script precisa processar arquivos de dados pré-carregados, o AI Agent primeiro faz o upload do arquivo por meio desta ferramenta antes de executar as operações subsequentes.

Orientações de uso

• Em uploads de arquivos grandes, pode ser necessário aguardar a conclusão do upload antes de executar as operações subsequentes.

RunIaC

Para criar, modificar ou destruir recursos cloud, o AI Agent pode usar esta ferramenta para gerenciar a infraestrutura via Terraform. Por exemplo, ao inserir "Create a VPC in Hangzhou with CIDR 172.16.0.0/16", o AI Agent gera primeiro a configuração do recurso e visualiza as alterações, executando a criação após a confirmação.

Orientações de uso

• Ao descrever requisitos de recursos, especifique claramente a região, as especificações e a nomenclatura. Por exemplo, "Create a VPC in Hangzhou with CIDR 172.16.0.0/16, named mcp-demo-vpc".

• Alterações de recursos podem exigir aprovação manual. Conclua o processo de aprovação conforme solicitado.

SearchDocuments

Para perguntas sobre uso de produto, métodos de configuração ou solução de erros, o AI Agent usa esta ferramenta para pesquisar na documentação oficial da Alibaba Cloud. Por exemplo, ao inserir "How to optimize Function Compute cold start" ou "How to configure OSS Bucket Policy", uma busca por documentos oficiais correspondentes é acionada.

Orientações de uso

• Incluir o nome do produto na consulta melhora a relevância dos resultados da pesquisa. Por exemplo, "OSS cross-origin configuration" é melhor do que "cross-origin configuration".

• Se precisar de documentação de um produto específico, especifique o nome do produto. Por exemplo, "Function Compute cold start optimization documentation" é melhor do 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

Após o AI Agent localizar documentos relevantes por meio de SearchDocuments, esta ferramenta lê o conteúdo completo para responder à pergunta. Por exemplo, ao inserir "How to optimize Function Compute cold start?", o AI Agent primeiro pesquisa e localiza o documento, depois lê o texto completo e organiza a resposta.

Orientações de uso

• O AI Agent lê e organiza automaticamente o conteúdo após localizar os documentos. Todo o processo é transparente para o usuário.

{
  "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

Para entender a estrutura da documentação de um produto, o AI Agent usa esta ferramenta para navegar pela árvore de diretórios de documentos. Por exemplo, ao inserir "What does the OSS documentation structure look like" ou "What user guides does ECS have".

Orientações de uso

• Especifique o nome do produto na consulta. Por exemplo, "What document categories does OSS have" ou "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

Se uma pergunta envolver termos específicos, itens de configuração ou códigos de erro, o AI Agent usa esta ferramenta para realizar correspondência exata de palavras-chave dentro da documentação de um produto especificado. Por exemplo, ao inserir "What values does InstanceChargeType have in ECS documentation" ou "Search for CORS-related content in OSS documentation".

Orientações de uso

• Especifique tanto o produto quanto a palavra-chave na consulta. Por exemplo, "Search for DescribeInstanceAttribute in ECS documentation".

• Palavras-chave mais precisas geram resultados mais relevantes. Múltiplas palavras-chave têm uma relação E (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?