Tools

Tools are functions that give your agent concrete capabilities. For example: querying a database, sending an email, calling an external API, etc.

Create a tool

Tools are defined with the @tool decorator:

# src/tools/search_products.py
from klisk import tool

@tool
async def search_products(category: str, max_price: float) -> str:
    """Search available products by category and maximum price."""
    # Your implementation here...
    return results

Rules

Every tool must follow these rules:

1. Docstring required — Describes what the tool does. The agent uses this description to decide when to use it.
2. Type hints on all parameters — Every parameter must be type-annotated.
3. Async function — Tools must be asynchronous.
4. Return string — The result must be a string that the agent can interpret.

Auto-discovery

Klisk automatically discovers all tools defined in .py files within the project. You just need to reference them by name in get_tools():

# src/main.py
from klisk import define_agent, get_tools

agent = define_agent(
    name="MyAgent",
    instructions="...",
    model="gpt-5.2",
    tools=get_tools("search_products", "create_order"),
)

Built-in tools

For OpenAI models, you can use built-in tools without implementing them:

• Web Search — Internet search
• Code Interpreter — Python code execution
• File Search — Search across uploaded files
• Image Generation — Image generation with DALL-E

agent = define_agent(
    name="Researcher",
    instructions="You research topics using the internet.",
    model="gpt-5.2",
    builtin_tools=["web_search"],
)

Full example

# src/tools/weather.py
from klisk import tool
import httpx

@tool
async def check_weather(city: str) -> str:
    """Check the current weather for a city."""
    async with httpx.AsyncClient() as client:
        resp = await client.get(
            f"https://api.weather.example/v1/current?city={city}"
        )
        data = resp.json()
    return f"Weather in {city}: {data['temp']}°C, {data['description']}"