Create your first agent

This guide walks you step by step through creating an AI agent with Klisk.

1. Create the project

klisk create travel-assistant

This generates the following structure in ~/klisk/projects/travel-assistant/:

travel-assistant/
├── klisk.config.yaml
├── .env
├── .gitignore
├── requirements.txt
├── .venv/
├── src/
│   ├── __init__.py
│   ├── main.py
│   └── tools/
│       ├── __init__.py
│       └── example.py
└── tests/

2. Configure the API key

Edit the .env file:

OPENAI_API_KEY=sk-...

3. Create a tool

Create a file at 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 for a specific date."""
    # Here you'd call a flights API
    return f"Flights found from {origin} to {destination} on {date}: Flight IB001 at 10:00 (€250), Flight VY002 at 14:30 (€180)"

4. Define the agent

Edit src/main.py:

from klisk import define_agent, get_tools

agent = define_agent(
    name="TravelAssistant",
    instructions="""You are a travel assistant that helps users find
    and compare flights. Always display prices and schedules clearly.""",
    model="gpt-5.2",
    temperature=0.7,
    tools=get_tools("search_flights"),
)

5. Validate the agent

klisk check travel-assistant -a TravelAssistant

If everything is correct, you'll see a success message.

6. Test in the Studio

klisk studio

The server starts in the background and returns control to the terminal. Open the URL shown in the output to access the Studio:

• A chat panel to talk to the agent
• A visual graph of agents and tools
• Live property editing

To stop the server when you're done:

klisk studio --stop

7. Test from the terminal

klisk run -p travel-assistant "Find flights from Madrid to Tokyo on March 15"

For interactive mode (continuous conversation):

klisk run -p travel-assistant -i

Next step

• Define more tools to expand the agent's capabilities
• Deploy to the cloud to share it