Skip to content

Server Tools Package

The azad.server_tools package provides a framework for creating and executing server-side tools. These tools run on the server and can perform operations that require specific environments or resources.

Core Components

Base

The Base module defines the core interfaces and classes for server tools. It includes:

  • ServerToolBase class for implementing server tools
  • Methods for running tools and reporting progress
  • Utilities for handling tool arguments and results

How Server Tools Work

Server tools are executed by the agent on the server side, without requiring user approval for each step. They can:

  1. Run asynchronously in the background
  2. Report progress through callbacks
  3. Access server resources and environments
  4. Return structured results to the agent

When a server tool is called:

  1. The agent creates an instance of the tool class
  2. The agent calls the tool's run method with the provided arguments
  3. The tool executes its logic, potentially reporting progress along the way
  4. The tool returns its final result to the agent
  5. The agent forwards the result to the language model

Creating Custom Server Tools

To create a custom server tool:

  1. Create a class that inherits from ServerToolBase
  2. Implement the run method to perform the tool's logic
  3. Use the step_callback to report progress
  4. Register the tool in the SERVER_TOOL_REGISTRY

Example:

from typing import Dict, Any, Optional
import asyncio
import logging
from azad.server_tools.base import ServerToolBase

class MyTool(ServerToolBase):
    """A simple server-side tool."""

    def __init__(self, config: Dict[str, Any], protocol: Optional[Any] = None):
        super().__init__(config, protocol)
        self.logger = logging.getLogger(__name__)

    async def run(self, args: Dict[str, Any], step_callback: callable, server_tool_run_id: str) -> Dict[str, Any]:
        """Run the tool with the given arguments."""
        # Report initial progress
        await step_callback({
            "server_tool_run_id": server_tool_run_id,
            "tool_name": "my_tool",
            "step_number": 1,
            "status": "progress",
            "data": {"message": "Starting my tool..."}
        })

        # Do some work
        await asyncio.sleep(1)  # Simulate work

        # Report completion
        await step_callback({
            "server_tool_run_id": server_tool_run_id,
            "tool_name": "my_tool",
            "step_number": 2,
            "status": "complete",
            "data": {"result": "Tool execution complete!"}
        })

        # Return the final result
        return {"result": "Tool execution complete!"}

# Register the tool
from azad.server_tools import SERVER_TOOL_REGISTRY
SERVER_TOOL_REGISTRY["my_tool"] = MyTool

See the Extending Azad guide for more details.