Tools

Tools let agents take actions. Write a normal Python function, add the @tool decorator, and pass it to your agent.

Creating a tool

custom.py
from veska import Agent, tool

@tool
def get_weather(city: str):
    # Your API call here
    return f"Weather in {city}: 72°F, sunny"

agent = Agent(
    name="weather-bot",
    system_prompt="You help users check the weather. Use the get_weather tool.",
    model="claude-sonnet-4-6",
    tools=[get_weather],
)

result = agent.run("What's the weather in Paris?")
print(result.output)

The @tool decorator reads the function name, parameters, and types automatically. You just write a normal function.

Optional parameters

Parameters with defaults become optional:

optional.py
from veska import tool

@tool
def search(query: str, max_results: int = 10):
    # query is required, max_results is optional
    return f"Found results for {query} (limit: {max_results})"

Multiple tools

multiple.py
from veska import Agent, tool

@tool
def get_weather(city: str):
    return f"Weather in {city}: 72°F, sunny"

@tool
def send_email(to: str, subject: str, body: str):
    # Your email logic here
    return f"Email sent to {to}"

agent = Agent(
    name="assistant",
    system_prompt="You help with weather and emails. Use get_weather and send_email tools.",
    model="claude-sonnet-4-6",
    tools=[get_weather, send_email],
)

Pre-built tools

Register pre-built tool sets by name in the Orchestrator:

file_manager

create_file(path, content)read_file(path)edit_file(path, old_text, new_text)delete_file(path)list_files(directory, pattern)search_files(directory, query)

code_runner

run_python(code, cwd)run_node(code, cwd)run_command(command, cwd)install_package(package, manager)run_tests(directory, framework)

project_tools

create_folder(path)create_project_structure(root, structure)init_git(directory)create_env_file(path, variables)
prebuilt.py
from veska import Orchestrator

orchestrator = Orchestrator(
    model="claude-sonnet-4-6",
    agents=[dev_agent],
    tools=["file_manager", "code_runner", "project_tools"],
)

Tool Permissions

Control which agents can use which tools:

permissions.py
from veska import ToolPermissions

permissions = ToolPermissions(registry)

# Set allowed tools for an agent
permissions.set("researcher", ["read_file", "search_files"])
permissions.set("developer", ["create_file", "edit_file", "run_python"])

# Check access
permissions.can_use("researcher", "delete_file")  # False