BaseTool

Base Tool Class

The main tool wrapper class:

BaseTool()

Universal tool wrapper for both sync and async tools.

Tools can access rollout context (rollout_id, group_id, metadata) and resources via the Context parameter, which is automatically injected when requested.

Usage patterns:

1. Decorator-based (existing pattern):

@tool(name="my_tool", description="Does something")
def my_function(arg1: str, arg2: int):
    return f"Result: {arg1} {arg2}"

1. Inheritance-based (new pattern):

class MyTool(BaseTool):
    # Class-level metadata (shared across all instances)
    name = "my_tool"
    description = "A tool that uses an API key"

    def __init__(self, api_key: str):
        super().__init__()  # Class attributes are set at class definition time
        self.api_key = api_key  # Instance data
        # Schema is automatically extracted from call() method

    def call(self, query: str) -> str:
        ···
        Execute a query using the API key.

        Args:
            query (str): The query to execute.

        Returns:
            str: The result of the query.
        ···
        # Use self.api_key here
        return f"Result for {query} with key {self.api_key}"

# Register the tool
# Tool is automatically registered on initialization
my_tool = MyTool(api_key="secret")

Note: Metadata (name, description, schema, etc.) is stored as class attributes, making it shared across all instances of the same tool class. This is more memory-efficient and semantically correct since all instances of a tool type should have the same metadata.

1. Tools with Context (for resource access):

@tool(name="grep_search")
async def grep_search(pattern: str, path: str = ".", context: "Context"):
    container = await context.acquire_resource(image_id=..., scope="rollout")
    return container.run_cmd(f"grep -r {pattern} {path}")

Parameters:

• auto_register –

  Whether to automatically register this tool instance (defaults to True).

Note

• Class attributes (name, description, schema, etc.) must be set at class definition time.
• For inheritance-based tools, the 'call' method must be defined to provide the tool logic.
• The 'func' parameter is not allowed - it can only be set via the 'call' method.

Functions

__call__(**kwargs)

Call the tool with the given arguments. Args: **kwargs: The arguments to call the tool with. The arguments should be in the schema of the tool and must be specified with arg=value. Returns: dict or coroutine: The result of the tool call. Returns a coroutine if the tool is async, otherwise returns the result directly. The result is a dict with the following keys: - "name": The name of the tool. - "arguments": The arguments used to call the tool. - "observation": The observation of the tool call. - "status": The status of the tool call. - "info": The info of the tool call.

register(tool_obj=None, name: str | None = None, auto_register: bool = True) classmethod

Register a tool (class or instance) in the global tool registry.

Can be called as: - Class method: Tool.register(tool_class, name="my_tool") - Instance method: tool_instance.register() (automatically uses instance as tool_obj)

Parameters:

• tool_obj –

  The tool class or instance to register. If None, registers cls. When called on an instance, cls will be the instance's class.

• name (str | None, default: None ) –

  Optional name to register under (defaults to tool.name)

• auto_register (bool, default: True ) –

  Whether to automatically register (defaults to True)

Returns:

• –

  tool_obj or cls: Returns the registered tool for method chaining

Tool Decorator

The main decorator for creating tools:

tool(name: str | None = None, description: str | None = None, status: str = 'success', max_length: int = 2048, auto_register: bool = True, stateful: bool = False, resource_spec: Any = None, backend: str = 'local', pool_size: int = -1)

Decorator that registers a callable as a tool. Creates a Tool instance that can handle both stateful and non-stateful behavior.

Parameters:

• name (str, default: None ) –

  The name of the tool.

• description (str, default: None ) –

  The description of the tool.

• status (str, default: 'success' ) –

  We use this to control the chain search workflow. - "terminal": The tool call is the final step in the chain. The search will be stopped. - "continue": The tool call is not the final step in the chain. The search will continue.

• max_length (int, default: 2048 ) –

  The maximum length of the tool's output/observation.

• auto_register (bool, default: True ) –

  Whether to automatically register the tool. This is used to get tool by name.

• stateful (bool, default: False ) –

  Whether the tool is stateful (manages resources via ResourceEngine).

• resource_spec (Any, default: None ) –

  Structured resource spec for the tool (used when stateful).

• backend (str, default: 'local' ) –

  Backend name for the resource engine (e.g. "local").

• pool_size (int, default: -1 ) –

  The size of the resource pool.