Ferramentas (Tools)

José David Atualizado por José David

As ferramentas são o núcleo funcional do seu agente. Elas são as capacidades que permitem a interação com o mundo externo: APIs, bancos de dados ou qualquer lógica de negócio personalizada.

Por que as Ferramentas são Importantes?

As ferramentas transformam seu agente de um simples conversador em um potente solucionador de problemas capaz de:

  • Obter dados em tempo real de APIs externas.
  • Realizar cálculos complexos e processamento de dados.
  • Interagir com bancos de dados e sistemas de armazenamento.
  • Executar lógica de negócio personalizada e específica às suas necessidades.
  • Integrar-se com serviços de terceiros e outras plataformas.
  • Automatizar tarefas e fluxos de trabalho.

Exemplo de uma Ferramenta: GetAddress

Esta é a estrutura básica de uma ferramenta em Python. Vamos voltar ao exemplo da Tool que consulta um endereço a partir de um código postal (CEP).

from weni import Tool, Context
from weni.responses import TextResponse
import requests

class GetAddress(Tool):
    def execute(self, context: Context) -> TextResponse:
        cep = context.parameters.get("cep", "")
        address_response = self.get_address_by_cep(cep=cep)
        return TextResponse(data=address_response)

    def get_address_by_cep(self, cep):
        url = f"https://viacep.com.br/ws/{cep}/json/"
        response = requests.get(url)
        if response.status_code == 200:
            return response.json()
        return {"error": f"Não foi possível encontrar o endereço para o CEP {cep}."}

Explicação do Código

Segue um resumo simples do que o código faz:

  • Imports: Primeiro, importamos os componentes necessários:
    • Tool, Context, TextResponse: Componentes base da Weni CLI.
    • requests: Biblioteca popular do Python para fazer requisições HTTP.
  • Definição da Classe: Criamos uma nova ferramenta chamada GetAddress que sabe buscar endereços.
  • Método execute: Esta é a parte principal executada quando o agente usa a ferramenta.
  1. Obtém o código postal (cep) fornecido pelo usuário.
  2. Chama outra função (get_address_by_cep) para encontrar o endereço.
  3. Retorna as informações do endereço ao agente.

Método get_address_by_cep: É uma função auxiliar que:

  1. Recebe um código postal.
  2. Constrói uma URL para consultar uma API externa.
  3. Obtém a resposta e a retorna.

Passos para Criar sua Própria Ferramenta

Aqui está um fluxo de trabalho recomendado para criar suas ferramentas:

  1. Defina sua Classe: Crie uma nova classe Python que herde de Tool.
  2. Implemente o Método execute: Escreva sua lógica de negócio principal dentro desse método.
  3. Adicione Métodos Auxiliares: Separe lógicas complexas em funções menores e claras para manter seu código organizado.
  4. Implemente Tratamento de Erros: Utilize try...except para lidar com possíveis falhas em chamadas a APIs ou no processamento de dados.
  5. Escreva Testes: Crie casos de teste no seu arquivo test_definition.yaml para validar a ferramenta localmente com weni run.
  6. Configure a Ferramenta no YAML: Adicione sua nova ferramenta à lista tools do seu agent_definition.yaml.

Uso de Credenciais em Ferramentas

Nunca escreva chaves de API ou senhas diretamente no seu código. Para isso, utilize context.credentials.

class GetAddressWithAuth(Tool):
    def execute(self, context: Context) -> TextResponse:
        cep = context.parameters.get("cep", "")
        # Acesse a credencial de forma segura
        api_key = context.credentials.get("mi_api_key")

        headers = {"Authorization": f"Bearer {api_key}"}
        # ...lógica para fazer uma requisição autenticada...

Nota Para um guia completo sobre como configurar isso, consulte o artigo Gerenciamento de Credenciais ######.

Boas Práticas Gerais para Ferramentas

  • Responsabilidade Única: Cada ferramenta deve ter um propósito claro e focado.
  • Tratamento de Erros Abrangente: Controle possíveis falhas em todas as chamadas externas e casos de borda.
  • Validação de Entradas: Valide todos os parâmetros de entrada antes do processamento.
  • Considerações de Segurança: Trate dados sensíveis adequadamente e siga as melhores práticas de segurança.
  • Testabilidade: Projete suas ferramentas para serem fáceis de testar.
  • Controle de Versão: Utilize um repositório (ex.: GitHub) para versionar suas ferramentas.

Como a gente se saiu?

Gerenciamento de Credenciais

Contato