Developing Custom Tools

The Squirro agent framework allows you to create and deploy custom tools using the LangChain framework. LLM agents can use these tools to perform actions in response to user input.

There are two supported approaches for registering tools:

1. Recommended method, integrated with the GenAI UI and simplified deployment.

2. Legacy method, using manual configuration of a YAML file.

Recommended Method

This method supports UI-driven deployment and does not require editing YAML configuration files or manually copying files to plugin directories.

• The tools are created using a decorated factory class.

• The tools are automatically listed in the /available_tools endpoint, and you can activate them directly via the UI.

• The deployment is done using the squirro_asset command from the Squirro Toolbox.

Creating a Tool

On your local system, create a folder for your tool, for example, greeter_tool/, with a minimal __init__.py file to make it a Python package.

To create the new tool, start with a new file in that folder, such as greeter.py. That Python file should contain the following code:

from __future__ import annotations
from langchain_core.tools import tool, BaseTool
from squirro.service.genai.components.registry import ToolBase, deploy_as_agent_tool

@deploy_as_agent_tool(
    "greeter",                    # Tool identifier
    tagline="A new greeter tool",  # Shown in the UI
    material_icon="public",        # Material icon
    category="retriever",          # UI category
)
class GreeterFactory(ToolBase):
    message_format: str = "Hello, {name}!"

    def create_runnable(self) -> BaseTool:
        @tool
        def greeter(name: str) -> str:
            """Greet someone by their name."""
            return self.message_format.format(name=name)
        return greeter

Deploying the Tool

Before deploying a tool, make sure you have remote access to a Squirro server via SSH. Also make sure the Squirro Toolbox is installed, then on your local system run the following command in a terminal:

squirro_asset genai_plugin upload \
    --token $SQ_API_KEY \
    --cluster $SQ_CLUSTER \
    --folder ./greeter_tool

In order for the Squirro platform to detect the new tool, you need to restart the GenAI service running the following command in a terminal connected to the Squirro instance:

sudo systemctl restart sqgenaid

The tool now appears in the Squirro Chat > Project Configuration > Agents Tab > [Your Agent] > “+ Configure New Tool” dropdown menu, where you can configured it.

Note

There is no need to edit the YAML file or manage the plugin folders manually.

Example with Dependencies

One of the advantages of uploading plugins using squirro_asset is the ability to include a requirements.txt file alongside your tool. That file lists any additional Python packages your tool depends on. When you deploy the plugin, the server automatically installs the dependencies and makes them available to the tool. There is no manual installation required.

For example, the following tool uses the pyjokes library to return a random joke.

Tool Implementation (jokester.py)

from __future__ import annotations

import logging

from langchain_core.tools import BaseTool, tool
from squirro.service.genai.components.registry import (
    ToolBase,
    deploy_as_agent_tool,
)

import pyjokes

log = logging.getLogger(__name__)

@deploy_as_agent_tool(
    "jokes",  # Tool identifier
    tagline="A tool that generates jokes",  # Shown in the UI
    material_icon="public",  # Material icon name
    category="retriever",  # UI category
)
class JokesterFactory(ToolBase):
    def create_runnable(self) -> BaseTool:
        @tool
        def jokester() -> str:
            """Return a random joke."""
            return pyjokes.get_joke()
        return jokester

Plugin Directory Structure

Your plugin directory (for example, jokester_tool/) should contain:

jokester_tool/
├── jokester.py
├── __init__.py
└── requirements.txt

Contents of requirements.txt:

pyjokes

Deployment

Upload the plugin as usual:

squirro_asset genai_plugin upload \
    --token $SQ_API_KEY \
    --cluster $SQ_CLUSTER \
    --folder ./jokester_tool

Restart the GenAI service:

ssh <host> sudo systemctl restart sqgenaid

The tool now appears in the Squirro Chat > Project Configuration > Agents Tab > “+ Configure New Tool” dropdown menu, ready for configuration and use.

Note

The requirements.txt file is only supported when using the recommended upload method with squirro_asset. It is not supported when using the legacy YAML-based method.

Legacy Configuration

Although a new approach is now available, the legacy method is still currently supported to cover some advanced use cases. However, to ensure future compatibility and avoid potential disruptions, developers are advised to gradually plan their transition to the new method. As the technology continues to evolve, the new approach is likely to become even more suitable for advanced use cases, offering improved performance, features, and capabilities.

Overview

• You register tools with @register_component.

• You reference the tools with a string identifiers in the YAML config files.

• You manually create the plugin and deployment folders.

Tool Example

import random
from langchain_core.tools import tool, BaseTool
from squirro.service.genai.components.registry import ToolBase, register_component

DAD_JOKES = [
    "I'm reading a book on anti-gravity. It's impossible to put down!",
    ...
]

@tool
async def random_dad_joke_tool() -> str:
    return random.choice(DAD_JOKES)

@register_component(name="examples/tools/dad_joke")
class RandomDadJokeToolFactory(ToolBase):
    def create_runnable(self) -> BaseTool:
        return random_dad_joke_tool

Note

For advanced use cases, you can apply both @deploy_as_agent_tool and @register_component to the same factory class. It allows the tool to be available in the GenAI UI for interactive selection and accessible via the YAML deployment configuration.

@deploy_as_agent_tool(
    "greeter",
    tagline="Greeter with UI and YAML support",
    material_icon="public",
    category="retriever",
)
@register_component(name="examples/tools/greeter")
class GreeterFactory(ToolBase):
    ...

Referencing in YAML

After placing your plugin in /var/lib/squirro/genai/plugins, reference it in the deployment config:

tools:
  - $runnable: "examples/tools/dad_joke"

Platform Setup

sudo mkdir -p /var/lib/squirro/genai/plugins
sudo mkdir -p /etc/squirro/genai.d/deployments

sudo chown -R sqgenai:squirro /var/lib/squirro/genai/plugins
sudo chown -R sqgenai:squirro /etc/squirro/genai.d/deployments

sudo systemctl restart sqgenaid

Versions prior to 3.10.6...

Edit /etc/squirro/genai.d/run.sh and add volume mounts for plugins and deployments.

--volume /var/lib/squirro/genai/plugins/:... \
--volume /etc/squirro/genai.d/deployments/:... \

Accessing Authenticated User Context

The agent framework makes authenticated user information available to tools via the squirro_client_args variable. It can be useful when tools require authorization or access control logic based on the current user.

In the legacy configuration, you must explicitly wire this context through the deployment YAML and your tool factory.

...
extra_input_mapping:
    /retriever/input_model/client_args: squirro_client_args
...
        auth_kwargs:
            $placeholder: squirro_client_args
...

Then, in your factory class, define a matching argument and forward it to your tool:

class MyToolFactory(ToolBase):
    auth_kwargs: dict[str, Any] | None = None

    def create_runnable(self) -> Runnable:
        return my_tool(auth=self.auth_kwargs)

Troubleshooting

To troubleshoot issues or unexpected results, the first step is to check the logs of the genai service. You can do that by running the following command in a terminal connected to the Squirro instance:

sudo docker logs -f squirro-service-genai

To open a shell in the container for further investigation or debugging, use the following command:

sudo docker exec -it squirro-service-genai /bin/bash

Getting Assistance

For assistance with Squirro-specific topics, contact Squirro Support and submit a technical support request. To learn more about LangChain tools, visit the LangChain documentation.