Skip to main content

​
Tools

cascadeflow provides a tool calling framework for agent loops. Define tools, execute them, and track tool call budgets.

​
ToolConfig

Define a tool with its schema and handler function. 
from cascadeflow.tools import ToolConfig

search_tool = ToolConfig(
    name="search",
    description="Search the web for information",
    parameters={"query": {"type": "string", "description": "Search query"}},
    handler=lambda query: f"Results for: {query}",
)
FieldTypeDescription
namestrTool name
descriptionstrWhat the tool does (sent to the model)
parametersdictJSON Schema for tool parameters
handlerCallableFunction to execute when tool is called

​
ToolExecutor

Executes tool calls and returns results. 
from cascadeflow.tools import ToolExecutor

executor = ToolExecutor(tools=[search_tool, calc_tool])

result = await agent.run(
    "Search for Python tutorials",
    tools=[search_tool, calc_tool],
    tool_executor=executor,
    max_steps=10,
)

​
@tool Decorator

Define tools using a decorator for cleaner syntax. 
from cascadeflow.tools import tool

@tool
def calculator(expression: str) -> str:
    """Evaluate a math expression."""
    return str(eval(expression))

@tool
async def web_search(query: str) -> dict:
    """Search the web."""
    return {"results": await fetch_results(query)}

​
Tool Call Limits

Use max_tool_calls in cascadeflow.run() to cap tool usage: 
with cascadeflow.run(budget=1.00, max_tool_calls=5) as session:
    result = await agent.run(
        "Research and calculate",
        tools=tools,
        tool_executor=ToolExecutor(tools=tools),
        max_steps=15,
    )
    print(f"Tool calls: {session.summary()['tool_calls']}/5")
When the cap is reached, cascadeflow issues a deny_tool action — the agent continues with what it has.

​
ToolResult

Returned by ToolExecutor.execute().
FieldTypeDescription
tool_namestrName of the tool that was called
resultAnyReturn value from the handler
errorstr | NoneError message if execution failed