Integração Rápida de Ferramentas

10 min

Aqui, usaremos o GoogleSearch como exemplo para demonstrar como integrar rapidamente uma ferramenta.

1. Prepare o YAML do Provedor de Ferramenta Introdução

Este YAML declara um novo provedor de ferramenta e inclui informações como o nome do provedor, ícone, autor e outros detalhes que são recuperados pelo frontend para exibição.

Exemplo

Precisamos criar um módulo (pasta) chamado google em core/tools/provider/builtin e criar o arquivo google.yaml. O nome deve ser consistente com o nome do módulo.

Subsequentemente, todas as operações relacionadas a esta ferramenta serão realizadas sob este módulo.

identity: # Informações básicas do provedor de ferramenta
  author: Paragraph # Autor
  name: google # Nome, único, sem duplicação com outros provedores
  label: # Rótulo para exibição no frontend
    en_US: Google # Rótulo em inglês
  description: # Descrição para exibição no frontend
    en_US: Google # Descrição em inglês
  icon: icon.svg # Ícone, precisa ser colocado na pasta _assets do módulo atual

O campo identity é obrigatório e contém as informações básicas do provedor de ferramenta, incluindo autor, nome, rótulo, descrição, ícone, etc.

O ícone precisa ser colocado na pasta _assets do módulo atual. Você pode se referir a: api/core/tools/provider/builtin/google/_assets/icon.svg.

<svg xmlns="http://www.w3.org/2000/svg" width="24" height="25" viewBox="0 0 24 25" fill="none">
  <path d="M22.501 12.7332C22.501 11.8699 22.4296 11.2399 22.2748 10.5865H12.2153V14.4832H18.12C18.001 15.4515 17.3582 16.9099 15.9296 17.8898L15.9096 18.0203L19.0902 20.435L19.3106 20.4565C21.3343 18.6249 22.501 15.9298 22.501 12.7332Z" fill="#4285F4"/>
  <path d="M12.214 23C15.1068 23 17.5353 22.0666 19.3092 20.4567L15.9282 17.8899C15.0235 18.5083 13.8092 18.9399 12.214 18.9399C9.38069 18.9399 6.97596 17.1083 6.11874 14.5766L5.99309 14.5871L2.68583 17.0954L2.64258 17.2132C4.40446 20.6433 8.0235 23 12.214 23Z" fill="#34A853"/>
  <path d="M6.12046 14.5766C5.89428 13.9233 5.76337 13.2233 5.76337 12.5C5.76337 11.7766 5.89428 11.0766 6.10856 10.4233L6.10257 10.2841L2.75386 7.7355L2.64429 7.78658C1.91814 9.20993 1.50146 10.8083 1.50146 12.5C1.50146 14.1916 1.91814 15.7899 2.64429 17.2132L6.12046 14.5766Z" fill="#FBBC05"/>
  <path d="M12.2141 6.05997C14.2259 6.05997 15.583 6.91163 16.3569 7.62335L19.3807 4.73C17.5236 3.03834 15.1069 2 12.2141 2C8.02353 2 4.40447 4.35665 2.64258 7.78662L6.10686 10.4233C6.97598 7.89166 9.38073 6.05997 12.2141 6.05997Z" fill="#EB4335"/>
</svg>

2. Prepare as Credenciais do Provedor

O Google, como uma ferramenta de terceiros, usa a API fornecida pelo SerpApi, que requer uma chave API para ser utilizada. Isso significa que esta ferramenta precisa de uma credencial para ser usada. Para ferramentas como a Wikipedia, não é necessário preencher o campo de credencial, você pode se referir a: api/core/tools/provider/builtin/wikipedia/wikipedia.yaml.

identity:
  author: Paragraph
  name: wikipedia
  label:
    en_US: Wikipedia
    pt_BR: Wikipedia
  description:
    en_US: Wikipedia is a free online encyclopedia, created and edited by volunteers around the world.
    pt_BR: Wikipedia é uma enciclopédia online gratuita, criada e editada por voluntários ao redor do mundo.
  icon: icon.svg
credentials_for_provider:

Após configurar o campo de credencial, o efeito é o seguinte:

identity:
  author: Paragraph
  name: google
  label:
    en_US: Google
  description:
    en_US: Google
  icon: icon.svg
credentials_for_provider: # Campo de credencial
  serpapi_api_key: # Nome do campo de credencial
    type: secret-input # Tipo do campo de credencial
    required: true # Obrigatório ou não
    label: # Rótulo do campo de credencial
      en_US: SerpApi API key # Rótulo em inglês
    placeholder: # Texto de placeholder do campo de credencial
      en_US: Please input your SerpApi API key # Placeholder em inglês
    help: # Texto de ajuda do campo de credencial
      en_US: Get your SerpApi API key from SerpApi # Texto de ajuda em inglês
    url: https://serpapi.com/manage-api-key # Link de ajuda do campo de credencial

3. Prepare o YAML da Ferramenta

Um provedor pode ter várias ferramentas, cada ferramenta precisa de um arquivo YAML para descrição, este arquivo contém as informações básicas, parâmetros, saída, etc., da ferramenta.

Ainda tomando o GoogleSearch como exemplo, precisamos criar um módulo de ferramentas sob o módulo google e criar o arquivo tools/google_search.yaml, com o seguinte conteúdo.

identity: # Informações básicas da ferramenta
  name: google_search # Nome da ferramenta, único, sem duplicação com outras ferramentas
  author: Paragraph # Autor
  label: # Rótulo para exibição no frontend
    en_US: GoogleSearch # Rótulo em inglês
description: # Descrição para exibição no frontend
  human: # Introdução para exibição no frontend, suporta vários idiomas
    en_US: A tool for performing a Google SERP search and extracting snippets and webpages. Input should be a search query.
  llm: A tool for performing a Google SERP search and extracting snippets and webpages. Input should be a search query. # Introdução passada para o LLM, para que o LLM compreenda melhor esta ferramenta, sugerimos escrever o máximo de informações detalhadas possíveis aqui, para que o LLM possa compreender e usar esta ferramenta
parameters: # Lista de parâmetros
  - name: query # Nome do parâmetro
    type: string # Tipo do parâmetro
    required: true # Obrigatório ou não
    label: # Rótulo do parâmetro
      en_US: Query string # Rótulo em inglês
    human_description: # Introdução para exibição no frontend, suporta vários idiomas
      en_US: used for searching
    llm_description: key words for searching # Introdução passada para o LLM, da mesma forma, para que o LLM compreenda melhor este parâmetro, sugerimos escrever o máximo de informações detalhadas possíveis aqui, para que o LLM compreenda este parâmetro
    form: llm # Tipo de formulário,

 llm significa que este parâmetro precisa ser inferido pelo Agente, o frontend não exibirá este parâmetro
  - name: result_type
    type: select # Tipo de parâmetro
    required: true
    options: # Opções da caixa de seleção
      - value: text
        label:
          en_US: text
      - value: link
        label:
          en_US: link
    default: link
    label:
      en_US: Result type
    human_description:
      en_US: used for selecting the result type, text or link
    form: form # Tipo de formulário, form significa que este parâmetro precisa ser preenchido pelo usuário no frontend antes de a conversa começar

O campo identity é obrigatório, ele contém as informações básicas da ferramenta, incluindo nome, autor, rótulo, descrição, etc.

4. Adicionar Lógica da Ferramenta

Depois de concluir a configuração da ferramenta, podemos começar a escrever o código da ferramenta que define como ela será invocada.

Crie google_search.py no módulo google/tools, com o seguinte conteúdo.

from core.tools.tool.builtin_tool import BuiltinTool
from core.tools.entities.tool_entities import ToolInvokeMessage

from typing import Any, Dict, List, Union

class GoogleSearchTool(BuiltinTool):
    def _invoke(self, 
                user_id: str,
               tool_parameters: Dict[str, Any], 
        ) -> Union[ToolInvokeMessage, List[ToolInvokeMessage]]:
        """
            invocar ferramentas
        """
        query = tool_parameters['query']
        result_type = tool_parameters['result_type']
        api_key = self.runtime.credentials['serpapi_api_key']
        # TODO: pesquisar com serpapi
        result = SerpAPI(api_key).run(query, result_type=result_type)

        if result_type == 'text':
            return self.create_text_message(text=result)
        return self.create_link_message(link=result)

Parâmetros

A lógica geral da ferramenta está no método _invoke, este método aceita dois parâmetros: user_id e tool_parameters, que representam respectivamente o ID do usuário e os parâmetros da ferramenta.

Dados de Retorno

Quando a ferramenta retorna, você pode escolher retornar uma mensagem ou várias mensagens, aqui retornamos uma mensagem, usando create_text_message e create_link_message para criar uma mensagem de texto ou uma mensagem de link.

5. Adicionar Código do Provedor

Finalmente, precisamos criar uma classe de provedor no módulo provider para implementar a lógica de verificação de credenciais do provedor. Se a verificação de credenciais falhar, ela lançará uma exceção ToolProviderCredentialValidationError.

Crie google.py no módulo google, com o seguinte conteúdo.

from core.tools.entities.tool_entities import ToolInvokeMessage, ToolProviderType
from core.tools.tool.tool import Tool
from core.tools.provider.builtin_tool_provider import BuiltinToolProviderController
from core.tools.errors import ToolProviderCredentialValidationError

from core.tools.provider.builtin.google.tools.google_search import GoogleSearchTool

from typing import Any, Dict

class GoogleProvider(BuiltinToolProviderController):
    def _validate_credentials(self, credentials: Dict[str, Any]) -> None:
        try:
            # 1. Aqui você precisa instanciar um GoogleSearchTool com GoogleSearchTool(), ele carregará automaticamente a configuração yaml do GoogleSearchTool, mas neste momento não tem informações de credenciais
            # 2. Então, você precisa usar o método fork_tool_runtime para passar as informações de credenciais atuais para o GoogleSearchTool
            # 3. Finalmente, invoque-o, os parâmetros precisam ser passados de acordo com as regras de parâmetro configuradas no yaml do GoogleSearchTool
            GoogleSearchTool().fork_tool_runtime(
                meta={
                    "credentials": credentials,
                }
            ).invoke(
                user_id='',
                tool_parameters={
                    "query": "test",
                    "result_type": "link"
                },
            )
        except Exception as e:
            raise ToolProviderCredentialValidationError(str(e))

Conclusão

Após a conclusão dos passos acima, podemos ver esta ferramenta no frontend, e ela pode ser usada no Agente.

Claro, como o google_search precisa de uma credencial, antes de usá-lo, você também precisa inserir suas credenciais no frontend.