Tools

Tools in HyperSaaS are plain Python functions with no framework-specific decorators. Each agent handler wraps them for its own runtime.

Available Tools

Tool	File	Description
Web Search	`chat/tools/web_search.py`	Search the web using SerpAPI or DuckDuckGo
Weather	`chat/tools/weather.py`	Get current weather via WeatherAPI.com
Location	`chat/tools/location.py`	Search for places via Google Maps
Knowledge Base	`documents/rag_tool.py`	Search attached knowledge bases (RAG)
URL Ingest	`documents/url_ingest_tool.py`	Ingest content from a URL

Tool Architecture

Tools are defined as plain functions in chat/tools/:

# chat/tools/weather.py
def get_weather(location: str) -> str:
    """Get current weather for a location."""
    # Pure Python — no @tool decorator, no framework imports
    response = requests.get(WEATHER_API_URL, params={"q": location, "key": API_KEY})
    return response.json()

Each handler wraps them differently:

LangGraph (in chat/handlers/langgraph/tools.py):

from langchain_core.tools import tool
from backend.chat.tools.weather import get_weather as get_weather_impl

@tool
def get_weather(location: str) -> str:
    """Get current weather for a location."""
    return get_weather_impl(location)

PydanticAI (in chat/handlers/pydantic_ai/agent.py):

@agent.tool_plain
def get_weather(location: str) -> str:
    """Get current weather for a location."""
    return get_weather_impl(location)

Knowledge Base Search Tool

The RAG tool is special — it needs access to the chat session to know which knowledge bases to search:

# documents/rag_tool.py
def search_knowledge_base_impl(query: str, session) -> str:
    """Pure function — no framework dependency."""
    results = search_documents(
        query=query,
        session_id=str(session.id),
        workspace_id=str(session.workspace_id),
    )
    return json.dumps(results)

The LangGraph wrapper uses InjectedToolArg to inject the session at runtime:

@tool
def search_knowledge_base(
    query: str,
    config: Annotated[RunnableConfig, InjectedToolArg],
) -> str:
    session = config["configurable"]["session"]
    return search_knowledge_base_impl(query, session)

Adding a New Tool

Create chat/tools/your_tool.py with a plain Python function
Add the LangChain wrapper in chat/handlers/langgraph/tools.py
Add the PydanticAI wrapper in chat/handlers/pydantic_ai/agent.py
Update the system prompt in chat/handlers/langgraph/nodes.py to describe the tool

Required API Keys

Tool	Environment Variable
Web Search	`SERPAPI_API_KEY`
Weather	`WEATHERAPI_COM_API_KEY`
Location	`GOOGLE_MAPS_API_KEY`
Knowledge Base	`OPENAI_API_KEY` (for embeddings)

Available Tools

Tool Architecture

Knowledge Base Search Tool

Adding a New Tool

Required API Keys

On this page