Quickstart

Build your first AI agent in 5 minutes

This guide will walk you through creating your first Klisk agent from scratch. You’ll learn how to scaffold a project, define an agent, create custom tools, and run your agent.

Before starting, make sure you have installed Klisk and have an OpenAI API key ready.

Create Your First Project

1. Create a new project

   Use the klisk create command to scaffold a new agent project:

   klisk create my-agent
   cd my-agent
   

   This creates a ready-to-run project with the following structure:

   my-agent/
   ├── klisk.config.yaml    # Project configuration
   ├── .env                 # API keys and environment variables
   └── src/
       ├── main.py          # Agent definition
       └── tools/           # Custom tools directory
           ├── __init__.py
           └── example.py   # Example tool
   
2. Configure your API key

   Open the .env file and add your OpenAI API key:

   .env

   OPENAI_API_KEY=sk-your-key-here
   
   # Uncomment and fill in the API key for your chosen provider:
   # ANTHROPIC_API_KEY=sk-ant-your-key-here
   # GEMINI_API_KEY=your-key-here
   # MISTRAL_API_KEY=your-key-here
   

   Never commit your .env file to version control. It’s already included in .gitignore.

3. Understand the project configuration

   The klisk.config.yaml file defines your project settings:

   klisk.config.yaml

   entry: src/main.py
   name: "my-agent"
   studio:
     port: 3000
   api:
     port: 8000
   

   • entry — Path to your main agent file
   • name — Project name
   • studio.port — Port for the development Studio
   • api.port — Port for the production API server

Define Your Agent

Your agent is defined in src/main.py. Let’s examine the default agent:

src/main.py

from klisk import define_agent, get_tools

agent = define_agent(
    name="Assistant",
    instructions="You are a helpful assistant. Use the tools available to help the user.",
    # Use "provider/model" for non-OpenAI models (e.g. "anthropic/claude-3-5-sonnet-20240620")
    model="gpt-5.2",
    tools=get_tools("greet"),
    # builtin_tools=["web_search"],  # Enable web search (OpenAI models only)
)

Agent Parameters

• name — Display name for your agent
• instructions — System prompt that defines the agent’s behavior
• model — LLM model to use (supports OpenAI and LiteLLM provider format)
• tools — List of custom tools to enable
• builtin_tools — Provider-hosted tools like web search (OpenAI only)
• temperature — Controls randomness (0.0 to 2.0, optional)
• reasoning_effort — For reasoning models like o3 (optional)

You can define multiple agents in the same project. Each call to define_agent() registers a new agent that will appear in the Studio.

Create Custom Tools

Tools are functions that your agent can call. Let’s look at the example tool in src/tools/example.py:

src/tools/example.py

from klisk import tool

@tool
async def greet(name: str) -> str:
    """Greet someone by name."""
    return f"Hello, {name}! How can I help you today?"

How Tools Work

1. Decorator — The @tool decorator registers your function and automatically generates a JSON schema from type hints
2. Docstring — The function’s docstring becomes the tool description that the LLM sees
3. Type hints — Required for all parameters and return values. The LLM uses these to understand the tool’s interface
4. Async — Tools should be async functions (use async def)

Create a New Tool

Let’s create a tool that searches for information. Create src/tools/search.py:

src/tools/search.py

from klisk import tool
import httpx

@tool
async def search_documentation(query: str) -> str:
    """Search the documentation for information about a topic.
    
    Args:
        query: The search query or topic to look up
    """
    # This is a simple example - replace with real search logic
    return f"Found documentation about: {query}"

@tool
async def get_weather(city: str) -> str:
    """Get the current weather for a city.
    
    Args:
        city: The name of the city
    """
    # Example implementation - replace with real weather API
    return f"The weather in {city} is sunny and 72°F"

Register Tools with Your Agent

Update src/main.py to use your new tools:

src/main.py

from klisk import define_agent, get_tools

agent = define_agent(
    name="Assistant",
    instructions="You are a helpful assistant. Use the tools available to help the user.",
    model="gpt-5.2",
    tools=get_tools("greet", "search_documentation", "get_weather"),
)

The get_tools() function looks up tools by their function name. Make sure your tools are imported before calling define_agent(). Klisk automatically imports all Python files in src/tools/.

Run Your Agent

There are several ways to interact with your agent:

CLI (One-off commands)

Run a single command and get a response:

klisk run "Say hello to Juan"

The agent will use the greet tool and respond:

Hello, Juan! How can I help you today?

Interactive Chat Mode

Start an interactive chat session:

klisk run -i

This opens a chat interface in your terminal where you can have a conversation with your agent.

Development Studio

Launch the visual development environment:

klisk dev

This opens a browser-based Studio at http://localhost:3000 with:

Agent Graph

Visual representation of your agents and their connected tools

Live Chat

Test your agent with file attachments and see tool calls in real-time

Inline Editing

Modify agent configuration directly from the UI

Hot Reload

Code changes update instantly without restarting

The Studio is perfect for rapid iteration. Make changes to your code, save the file, and see updates immediately in the browser.

Use Different Models

Klisk supports any LLM provider via LiteLLM. Just prefix the model name:

OpenAI (default)

define_agent(
    name="Agent",
    model="gpt-5.2",
)

Don’t forget to add the corresponding API key to your .env file:

.env

ANTHROPIC_API_KEY=sk-ant-your-key-here
GEMINI_API_KEY=your-key-here
MISTRAL_API_KEY=your-key-here

Enable Builtin Tools

OpenAI models support provider-hosted tools like web search:

src/main.py

from klisk import define_agent, get_tools

agent = define_agent(
    name="Researcher",
    instructions="You are a research assistant. Search the web for accurate information.",
    model="gpt-5.2",
    tools=get_tools("greet"),
    builtin_tools=["web_search", "code_interpreter"],
)

Available builtin tools:

• web_search — Search the web for information
• code_interpreter — Execute Python code in a sandboxed environment
• image_generation — Generate images from text descriptions
• file_search — Search uploaded files (requires FileSearch configuration)

Builtin tools only work with OpenAI models. If you use Anthropic, Google, or other providers, you’ll need to implement these capabilities as custom tools.

Next Steps

Congratulations! You’ve created your first Klisk agent. Here’s what to explore next:

Core Concepts

Learn about agents, tools, and how they work together

CLI Reference

Explore all available CLI commands

Deploy to Production

Learn how to deploy your agent to Google Cloud Run

API Reference

Detailed API documentation for all functions