Define tools

Tools are what make your agent useful. They allow it to interact with APIs, databases, external services, and more.

Anatomy of a tool

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

@tool
async def tool_name(param1: str, param2: int) -> str:
    """Clear description of what this tool does."""
    # Implementation
    return "result"

Requirements:

• @tool decorator
• async function
• Docstring (the agent uses it to decide when to use the tool)
• Type hints on all parameters
• Returns str

Add a tool to an existing project

1. Create the file in src/tools/:

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

@tool
async def send_email(recipient: str, subject: str, body: str) -> str:
    """Send an email to a recipient with the given subject and body."""
    # Your sending logic here...
    return f"Email sent to {recipient}"

2. Add it to get_tools() in src/main.py:

agent = define_agent(
    name="MyAgent",
    instructions="...",
    model="gpt-5.2",
    tools=get_tools("search_flights", "send_email"),  # Add it here
)

External dependencies

If your tool needs an external library:

1. Add it to requirements.txt:

klisk
httpx

2. Install it in the project's virtual environment:

.venv/bin/pip install -r requirements.txt

3. Use it in your tool:

from klisk import tool
import httpx

@tool
async def query_api(endpoint: str) -> str:
    """Query an API endpoint and return the response."""
    async with httpx.AsyncClient() as client:
        resp = await client.get(endpoint)
    return resp.text

Multimodal input

Klisk supports sending images and PDFs to the agent from the terminal:

klisk run -p my-agent "@photo.jpg Describe this image"
klisk run -p my-agent "@report.pdf Summarize this document"
klisk run -p my-agent "@img1.png @img2.png Compare these images"

Supported formats: JPEG, PNG, GIF, WebP, and PDF (max 20MB per file).