Tools

José David Updated by José David

Tools are the functional core of your agent. They are the capabilities that allow it to interact with the outside world: APIs, databases, or any custom business logic.

Why Are Tools Important?

Tools transform your agent from a simple conversationalist into a powerful problem-solver capable of:

  • Fetching real-time data from external APIs.
  • Performing complex computations and data processing.
  • Interacting with databases and storage systems.
  • Executing custom, business-specific logic tailored to your needs.
  • Integrating with third-party services and other platforms.
  • Automating tasks and workflows.

Example of a Tool: GetAddress

This is the basic structure of a tool in Python. Let’s return to the example of the Tool that looks up an address from a postal code (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"The address for the CEP {cep} could not be found."}

Code Explanation

Here’s a simple breakdown of what the code does:

  • Imports: First, we import the pieces we need:
    • Tool, Context, TextResponse: Base components of Weni CLI.
    • requests: Popular Python library for making HTTP requests.
  • Class Definition: We create a new tool called GetAddress that knows how to look up addresses.

execute Method: This is the main part that runs when the agent uses the tool.

  1. Obtains the postal code (cep) provided by the user.
  2. Calls another function (get_address_by_cep) to find the address.
  3. Returns the address information to the agent.

get_address_by_cep Method: This is a helper function that:

  1. Receives a postal code.
  2. Builds a URL to query an external API.
  3. Retrieves the response and returns it.

Steps to Create Your Own Tool

Here’s a recommended workflow for building your tools:

  1. Define Your Class: Create a new Python class that inherits from Tool.
  2. Implement the execute Method: Write your main business logic inside this method.
  3. Add Helper Methods: Split complex logic into smaller, clearer functions to keep your code organized.
  4. Implement Error Handling: Use try...except to handle potential failures in API calls or data processing.
  5. Write Tests: Create test cases in your test_definition.yaml to validate your tool locally with weni run.
  6. Configure the Tool in YAML: Add your new tool to the tools list in your agent_definition.yaml.

Using Credentials in Tools

You should never hardcode API keys or passwords directly in your code. Instead, use context.credentials.

class GetAddressWithAuth(Tool):
    def execute(self, context: Context) -> TextResponse:
        cep = context.parameters.get("cep", "")
        # Access the credential securely
        api_key = context.credentials.get("mi_api_key")

        headers = {"Authorization": f"Bearer {api_key}"}
        # ...logic to make an authenticated request...

Note For a complete guide on how to configure this, see the Credential Management ###### article.

General Best Practices for Tools

  • Single Responsibility: Each tool should have a clear, focused purpose.
  • Thorough Error Handling: Guard against failures in all external calls and edge cases.
  • Input Validation: Validate all input parameters before processing.
  • Security Considerations: Handle sensitive data appropriately and follow security best practices.
  • Testability: Design your tools to be easy to test.
  • Version Control: Use a repository (e.g., GitHub) to version your tools.

How did we do?

Credential Management

Contact