Tools

Tools are pluggable functions that an agent or LLM can invoke to interact with external systems.

Built-in Tools

Tool	Description
WebSearchTool	Search the web (simulated by default; set XYBEROS_WEB_SEARCH_URL)
ReadFileTool	Read file contents from the filesystem
CalculatorTool	Safely evaluate mathematical expressions
ListDirectoryTool	List files and directories

Using Tools

from xyberos.tools import ToolManager, CalculatorTool, WebSearchTool

manager = ToolManager()

# Register tools
manager.register("calc", CalculatorTool())
manager.register("web", WebSearchTool())

# Execute
result = manager.run("calc", expression="sqrt(144) + 42")
print(result.value)  # 54.0

result = manager.run("web", query="latest AI news")
print(result.value)

Creating a Custom Tool

from xyberos.tools import Tool, ToolResult, ToolSpec


class WeatherTool(Tool):
    @property
    def name(self) -> str:
        return "weather"

    @property
    def description(self) -> str:
        return "Get the current weather for a city."

    def run(self, city: str) -> ToolResult:
        # Your weather API call here
        return ToolResult.ok(
            value={"city": city, "temperature": 22, "unit": "C"},
            metadata={"source": "simulated"},
        )

    def to_spec(self) -> ToolSpec:
        """Return an LLM function-calling spec."""
        return ToolSpec(
            name=self.name,
            description=self.description,
            parameters={
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name",
                    },
                },
                "required": ["city"],
            },
        )


# Register and use
manager.register("weather", WeatherTool())
result = manager.run("weather", city="London")

Plugin Registration

Tools auto-discover via entry points in pyproject.toml:

[project.entry-points."xyberos.tools"]
my_tool = "my_package:MyTool"

See Providers for details on the plugin system.