Custom plugins

Etapa 1: Criar um plugin

1. Acesse a página Plugins e clique em Create Plugin.
2. Insira as informações do plugin.

   Plug-in Name: Insira um nome descritivo. Há suporte para chinês e inglês. Exemplo: Dormitory Agreement Query Tool Test

   Plug-in Description: Descreva brevemente os recursos e a finalidade do plugin em linguagem natural. Essa descrição ajuda o modelo a decidir quando usar o plugin. Exemplo: Queries the content of a specific dormitory agreement entry based on the input numeric index.

   Plug-in URL: O endpoint de acesso do plugin. Exemplo:https://domitorgreement-plugin-example-icohrkdjxy.cn-beijing.fcapp.run O Model Studio trata caminhos diferentes no mesmo domínio como APIs distintas. Esses caminhos correspondem ao Tool Path configurado durante a criação de uma ferramenta. As ferramentas dentro do mesmo plugin compartilham um nome de domínio, mas o caminho de cada ferramenta mapeia para uma API exclusiva. Por exemplo, um plugin contém duas APIs: Consulta: https://xxx.com/query Exclusão: https://xxx.com/delete Neste exemplo, https://xxx.com é a Plug-in URL, enquanto /query e /delete são os valores de Tool Path. Isso indica que o plugin contém duas ferramentas.

   Se for necessária autenticação, ative a chave Enable Authentication e insira as configurações de autenticação.
   Parâmetros de autenticação

   Headers (Opcional)	Caso seja necessária autenticação, passe as informações em um cabeçalho personalizado.
   Enable Authentication (Opcional)	Determina se um aplicativo deve fornecer autenticação para chamar seu plugin personalizado. Isso depende da política de segurança do provedor de API.
   Authentication Type	Existem dois métodos de autenticação: autenticação no nível de serviço e autenticação no nível de usuário. Location: Coloque as informações de autenticação no cabeçalho da solicitação ou na string de consulta. Header: Esta opção coloca as informações de autenticação no cabeçalho Authorization da solicitação HTTP, mantendo-as ocultas na URL. Query: Esta opção coloca as informações de autenticação na URL. Por exemplo: https://example.com?api_key=123456. Parameter Name: Se colocar as informações de autenticação na string de consulta, especifique o nome do parâmetro usado para autenticação, como api_key. Se colocá-las no cabeçalho, o parâmetro será Authorization por padrão. Type: basic: Não adiciona nenhum prefixo ao token fornecido. bearer: Adiciona o prefixo Bearer ao token. appcode: Adiciona o prefixo APPCODE ao token. O prefixo é incluído no campo de autenticação. Por exemplo, se selecionar bearer, o cabeçalho Authorization se tornará Authorization: Bearer <YOUR_TOKEN>. Token (para autenticação no nível de serviço): O token de autenticação do provedor de API, como uma chave de API.

3. Após preencher o formulário, clique em Confirm Create Plug-in > Create Tool ou clique em Continue to Add Tool.

Etapa 2: Criar uma ferramenta

1. Insira as informações da ferramenta, configure os parâmetros de entrada e saída e defina as configurações avançadas. Neste exemplo, insira "Dormitory Rules Query Tool" para Tool Name e "Queries the content of a specific dormitory rule based on the input numeric index" para Tool Description. Defina o Tool Path como /article, selecione POST para o Request Method e selecione application/json para o Submission Method. Para o parâmetro de entrada, defina o nome do parâmetro como article_index, a descrição do parâmetro como "index" e o tipo como Number. Este parâmetro é passado no Body, é obrigatório e seu método de passagem é LLM recognition. Para o parâmetro de saída, defina o nome do parâmetro como article, a descrição do parâmetro como "dormitory rule content" e o tipo como String. Nas configurações avançadas, a consulta de entrada do usuário é "Query the content of the corresponding dormitory rule based on the input index value", e o valor do parâmetro de entrada article_index é 5.
   Parâmetros da ferramenta

   Informações da ferramenta

   Tool Name	Insira um nome descritivo. Há suporte para chinês e inglês.
   Tool Description	Uma breve descrição dos recursos e casos de uso da ferramenta. Isso ajuda o modelo a decidir quando chamar a ferramenta. Use linguagem natural e forneça exemplos sempre que possível.
   Tool Path	O caminho relativo para a Plug-in URL. O caminho deve começar com uma barra (/). O sistema anexa este caminho à Plug-in URL para construir a URL completa da solicitação.
   Request Method	Selecione GET ou POST como o método de solicitação para chamar a API.
   Submission Method	O tipo de codificação para o corpo da solicitação. application/json: O conteúdo do corpo são dados formatados em JSON. application/x-www-form-urlencoded: Codifica dados de formulário como pares chave-valor. Este método de codificação aplica-se a solicitações POST. Ele codifica dados de formulário em pares chave-valor, separa os pares com e comerciais (&) e separa chaves de valores com sinais de igual (=). Os dados são então codificados por URL, o que converte caracteres especiais em um sinal de porcentagem (%) seguido por dois dígitos hexadecimais. Por exemplo, um espaço é codificado como %20, & como %26 e = como %3D. Exemplo: name=John Doe&age=25 é codificado como name=John%20Doe&age=25.

   Configurar parâmetros de entrada e saída

   Configure Input Parameters	Clique em Add Input Parameter para configurar os parâmetros.
   	Parameter Name: Use um nome descritivo para ajudar o modelo a entender o que o parâmetro representa. Por exemplo, city.
   	Parameter Description: Uma descrição concisa e precisa da função do parâmetro de entrada. Isso ajuda o modelo a entender melhor como recuperar o valor do parâmetro. Por exemplo, para um parâmetro chamado date, descreva-o como uma data e especifique seu formato, como yyyy-MM-dd.
   	Type: O tipo de dados do parâmetro. As subpropriedades de um tipo Object não podem estar vazias. Clique no ícone no final da linha do objeto para adicionar uma subpropriedade.
   	Passing Method: Define como o valor do parâmetro é passado. Esta configuração é crítica para a operação correta. LLM Recognition: O modelo extrai o valor do parâmetro da entrada do usuário. Business Pass-through: O sistema passa o valor do parâmetro diretamente de uma source externa sem processamento ou modificação. Ao chamar um aplicativo usando o DashScope SDK ou uma API HTTP, o sistema passa parâmetros de entrada do tipo business pass-through para o aplicativo usando biz_params e user_defined_params. Para mais informações, consulte Passar parâmetros para um aplicativo.
   Configure Output Parameters	Clique em Add Output Parameters e configure os parâmetros. Todos os parâmetros são obrigatórios. O modelo usa as definições de parâmetros de saída para filtrar e reestruturar a resposta da API com base na consulta do usuário e, em seguida, retorna a resposta final. Assim como os parâmetros de entrada, os parâmetros de saída devem ser descritos de forma concisa e precisa, com aninhamento mínimo. Os métodos de solicitação GET e POST suportam o tipo Object para parâmetros. No entanto, as subpropriedades de um tipo Object não podem estar vazias. Clique no ícone no final da linha do objeto para adicionar uma subpropriedade.

   Configuração avançada (Opcional)

   Advanced Configuration	Forneça exemplos de chamada para ajudar o modelo a evitar chamadas de ferramenta perdidas ou incorretas. Se os parâmetros de entrada forem complexos e o modelo puder construí-los incorretamente, fornecer exemplos melhora a precisão da chamada.
   	Value: Especifica os parâmetros de invocação esperados do modelo a partir da consulta de um usuário. Por exemplo, para a entrada do usuário "Qual é a previsão do tempo em Hangzhou amanhã?", os parâmetros esperados são {"city": "Hangzhou", "date": "2025-04-25"}.

2. Após concluir a configuração, clique em Save Draft.
3. Depure a ferramenta online para verificar se a API pode ser chamada.

   Clique em Test Tool. Se ativou a autenticação, insira as informações de autenticação e os valores dos parâmetros de entrada. Em seguida, clique em Start Running. Se a execução falhar, ajuste a configuração com base na mensagem de erro na seção Run Result e teste novamente até obter sucesso. Insira valores de parâmetros de entrada manualmente ou como código. Para parâmetros complexos, use Code Editing. No editor de código, envie os parâmetros de entrada completos formatados em JSON e seus valores correspondentes.

4. Após o teste ser aprovado, clique em Publish. Os aplicativos só podem chamar ferramentas que estejam Published.

• Método 1: Publique o plugin como um serviço MCP e adicione o serviço a um aplicativo de agente. Etapa 1: Publicar o plugin como um serviço MCP
  1. Na página Plugins, passe o mouse sobre o cartão do plugin alvo e clique em Publish as MCP Service.

     Se o plugin já tiver sido convertido em um serviço MCP, o botão mudará para View MCP Service . Clique nele para ir à página de Gerenciamento de MCP e visualizar os detalhes do serviço.

  2. Após a publicação bem-sucedida, visualize os detalhes do serviço MCP na página MCP Management, incluindo o nome, a descrição e o ID do serviço.
  Etapa 2: Adicionar o serviço MCP a um aplicativo de agente
  1. Acesse a tela de orquestração do aplicativo Agent Application. No bloco MCP, clique em +.
  2. No painel Select MCP Service, alterne para a aba Custom MCPS, localize o serviço MCP convertido do plugin e clique em Add All para adicioná-lo ao aplicativo.

     Também é possível clicar em Convert from Plugin to MCP para publicar diretamente um plugin ainda não convertido.

  3. Teste se o plugin funciona conforme o esperado.
     • Sem autenticação: Converse com o modelo na caixa de entrada para testar a funcionalidade do plugin.
     • user-level authentication ou service-level authentication: Antes de iniciar uma conversa, clique em para configurar o token de autenticação. Configure o token apenas uma vez por sessão nesta página.

       Para plugins importados do Alibaba Cloud Marketplace, não é necessário inserir um token de autenticação nesta página.

     • Se o Passing Method para um parâmetro de entrada da ferramenta estiver definido como Business Pass-through, clique em para configurar o valor da variável antes de iniciar uma conversa. Insira o valor apenas uma vez por sessão nesta página.
  4. Após concluir o teste, Publish o aplicativo.
• Método 2: Na página Application Management, acesse a tela de orquestração do seu aplicativo Agent Application, adicione o serviço MCP do bloco MCP, teste sua funcionalidade e, em seguida, Publish o aplicativo.