Klisk Guide

Klisk is a framework for building AI agents programmatically. It wraps the OpenAI Agents SDK with conventions, a CLI, and a visual Studio. Supports any LLM provider (OpenAI, Anthropic, Gemini, Mistral, etc.) via LiteLLM.

Installation

pip install klisk

Skill Contents

Workflow: From Zero to Deployed Agent

1. Initialize the workspace

klisk

This creates ~/klisk/ and ~/klisk/projects/ and shows a welcome message. Run your AI agent from this directory:

cd ~/klisk
claude               # or your preferred AI agent
> "Create an agent that ..."

2. Create the project

klisk create my-agent

Projects are created in ~/klisk/projects/<name>. All CLI commands accept the project name directly — no need to cd:

klisk studio                    # Start Studio (loads all projects)
klisk run -p my-agent "Hello"
klisk check my-agent

This scaffolds a standard project structure with a virtual environment:

my-agent/
├── klisk.config.yaml        # Config (entry point, ports)
├── .env                        # API keys (gitignored)
├── .gitignore                  # Ignores .venv/, __pycache__/, .env
├── requirements.txt            # Dependencies (starts with "klisk")
├── .venv/                      # Virtual environment (auto-created)
├── src/
│   ├── __init__.py
│   ├── main.py                 # Entry point — defines the main agent
│   └── tools/
│       ├── __init__.py
│       └── example.py          # Example tool (@tool decorated)
└── tests/

The .venv/ is created automatically with klisk pre-installed, so editors (VS Code, PyCharm) can resolve imports like from klisk import define_agent without errors.

3. Configure the API key

Edit ~/klisk/projects/my-agent/.env (created automatically from .env.example):

OPENAI_API_KEY=sk-...
# Or for other providers:
# ANTHROPIC_API_KEY=sk-ant-...
# GEMINI_API_KEY=...

4. Define tools

Create files under src/tools/. Each tool is a decorated async function:

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

@tool
async def search_flights(origin: str, destination: str, date: str) -> str:
    """Search available flights between two cities."""
    # your implementation...
    return results

Rules: must have docstring + type hints on all params. Should be async. Tools are auto-discovered.

5. Define the agent

Edit src/main.py to wire the agent with its tools and instructions:

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

agent = define_agent(
    name="TravelAgent",
    instructions="You help users find and book flights.",
    model="gpt-5.2",
    temperature=0.7,
    tools=get_tools("search_flights"),
)

Always use model="gpt-5.2" by default unless the user explicitly requests a different model.

Key parameters: name, instructions, model, temperature, reasoning_effort, tools, builtin_tools, plus SDK kwargs (handoffs, guardrails, output_type).

Note: reasoning_effort defaults to None (not sent to the API). Only set it for o-series models (o1, o3, o4-mini, etc.) and gpt-5+ (gpt-5.1, gpt-5.2, etc.). Models like gpt-4.1 or gpt-4o do NOT support this parameter.

For OpenAI models, you can also add built-in tools (web search, code interpreter, file search, image generation) via the builtin_tools parameter. See references/builtin_tools.md.

Important: temperature and reasoning_effort MUST be passed as direct parameters of define_agent(), NOT inside model_settings. If you pass model_settings explicitly, the automatic temperature and reasoning_effort configuration is skipped and those parameters are ignored. Wrong:

# DON'T do this — temperature and reasoning_effort are ignored
agent = define_agent(
    name="MyAgent",
    temperature=0.7,
    reasoning_effort="medium",
    model_settings=ModelSettings(temperature=0.3),  # overrides everything
)

Correct:

# DO this — let define_agent() build model_settings automatically
agent = define_agent(
    name="MyAgent",
    temperature=0.7,
    reasoning_effort="medium",
    tools=get_tools("my_tool"),
)

For non-OpenAI models, use provider/model format (e.g. "anthropic/claude-sonnet-4-20250514"). Requires pip install 'klisk[litellm]'. See references/litellm.md.

6. Validate the agent

After defining the agent, run klisk check to verify everything is correct before opening the Studio. The first argument is the project name, and -a specifies the agent name to check:

klisk check my-project -a TravelAgent
#           ^^^^^^^^^^    ^^^^^^^^^^^
#           project name  agent name

This validates the agent’s config, tools, docstrings, and parameter usage. Fix any errors before proceeding.

7. Develop and test with Studio

IMPORTANT — Be proactive: Once the agent passes klisk check, immediately run klisk studio to open the Studio without waiting for the user to ask. The user expects to see the Studio as soon as the agent is ready.

klisk studio             # Start Studio in background (workspace mode)
klisk studio --stop      # Stop the Studio dev server

The server runs as a background daemon — it launches, prints the URL and PID, and returns control to the terminal immediately. The server survives terminal closure. PID files are stored in ~/klisk/run/ and logs in ~/klisk/logs/.

If you run klisk studio again while a server is already running, it detects the existing instance and shows its URL instead of launching a duplicate.

The Studio always runs in workspace mode: it loads every project from ~/klisk/projects/ into a single session. Agents/tools are tagged with their project name. If two projects define an agent with the same name, they get prefixed (project-a/MyAgent, project-b/MyAgent). .env files from all projects are loaded (no override).

Studio features:

• Graph view of agents and tools
• Chat panel to test the agent
• Live editing of agent/tool properties
• Hot reload on file changes (watches all projects)

8. Test from the terminal

klisk run -p my-agent "Find flights from Madrid to Tokyo on March 15"
klisk run -p my-agent -i   # interactive conversation mode

Multimodal (images/PDFs): Use @path to attach files:

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: JPEG, PNG, GIF, WebP images and PDF files (max 20MB each).

9. Validate before deploying

The first argument is always the project name (or path). Use -a to filter by agent name:

klisk check my-project                       # All agents in the project
klisk check my-project -a TravelAgent        # Only TravelAgent
klisk check                                  # Current directory as project

Verifies config, entry point, agent/tool discovery, docstrings, correct usage of temperature/reasoning_effort (must be define_agent() params, not inside model_settings), and warns if reasoning_effort is set on a model that doesn’t support it (only o-series and gpt-5+ do).

With --agent/-a, only the specified agent and its tools are validated. If the agent is not found, it shows available agents.

10. Start in production

klisk start my-agent --port 8080

Starts a production server with chat UI (/), REST API (/api/chat), WebSocket (/ws/chat), and embeddable widget (/widget.js). Supports optional API key authentication.

See references/server.md for endpoints, auth, streaming events, and widget config.

11. Deploy to the cloud

klisk docker my-agent         # generates Dockerfile + .dockerignore

This generates a Dockerfile that runs klisk start on port 8080. From there, build the image and deploy to any container platform (Cloud Run, AWS App Runner, Azure Container Apps, Fly.io, etc.).

See references/deploy.md for recommended platforms, deployment checklist, and how Customize settings work in production.

CLI Commands (Quick Reference)

klisk                            # Initialize workspace + show welcome
klisk create <name>              # Scaffold new project in ~/klisk/projects/
klisk studio                     # Start Studio in background (all projects)
klisk studio --stop              # Stop the Studio dev server
klisk run -p <name> "<message>"  # Run agent (or -i for interactive)
klisk check <name>               # Validate project
klisk check <name> -a <agent>    # Validate specific agent
klisk list                       # List all projects
klisk delete <name>              # Remove project
klisk start <name>               # Production server
klisk docker <name>              # Generate Docker files for deployment
klisk config                     # View global configuration
klisk config <key> <value>       # Set a global config value
klisk status                     # Show workspace and Studio status
klisk assistant [<name>]         # AI assistant for building agents (requires pip install 'klisk[assistant]')

Key Patterns

Multi-agent with handoffs

search_agent = define_agent(name="Search", tools=get_tools("search_flights"))

router = define_agent(
    name="Router",
    instructions="Route to the right specialist.",
    handoffs=[search_agent],
)

Adding a new tool to an existing project

1. Create src/tools/send_email.py with @tool decorator
2. Add to get_tools() in src/main.py: tools=get_tools("search_flights", "send_email")

Managing dependencies

Projects use requirements.txt for dependencies. To add a library:

1. Add it to requirements.txt (e.g. requests)
2. Install in the project’s venv: .venv/bin/pip install -r requirements.txt
3. Import and use it in your tools

The venv is automatically activated during klisk studio, klisk run, and klisk start. When deploying, all dependencies from requirements.txt (including klisk from PyPI) are installed in the Docker image.

Important Rules

• Default model is gpt-5.2. Always use model="gpt-5.2" unless the user explicitly requests a different model.
• Tools are auto-discovered: all .py files imported before the entry point
• Every @tool function must have a docstring and type hints
• define_agent() returns the SDK Agent object — usable with Runner.run() directly
• **kwargs forwarded to the SDK: handoffs, guardrails, output_type, etc.

Reference Docs

Integration Guides