--- title: Integração Rápida de Ferramentas slug: integracao-rapida-de-ferramentas createdAt: 2024-09-03T20:28:43.417Z --- 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. ```yaml 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`. ```yaml ``` ## 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`. ```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: ```yaml 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. ```yaml 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. ```python 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. ```python 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. ![](https://api.archbee.com/api/optimize/NB-ulyH02IT7Ep_VosDsd/39SGBc0qO_libhuS0xndc_captura-de-tela-2024-09-03-as-90511-am.png)