Follow our quickstart guide below or use an interactive notebook.

​
Installation

To connect to your Kolena Agents using Python, install the kolena-agents client from PyPI using any Python package manager such as pip or poetry: 
pip install kolena-agents

​
Initialization

An API Key is required to use the python client. Create and copy a key, then store the value in a KOLENA_API_KEY environment variable: 
export KOLENA_API_KEY="your-api-key"

​
Usage

Here’s an example of how to use the client to add, download and delete Agent Runs: 
from kolena_agents import Client

client = Client()

# add new Agent Run
new_run = client.agent_run.add(agent_id=1, files=["path/to/file1", "path/to/file2"])

# download Agent Run
run = client.agent_run.get(agent_id=1, run_id=2)

# alternatively, list all Agent Runs
all_runs = client.agent_run.list(agent_id=1)

# delete Agent Run
client.agent_run.delete(agent_id=1, run_id=2)

# list all Agents
all_agents = client.agent.list()

# get an Agent
agent = client.agent.get(agent_id=1)

​
Synchronous Usage

You can also add an Agent Run synchronously, which creates a Run and waits for processing of all prompts to complete. Note that this endpoint has rate limits. 
# add new Agent Run and wait for processing to complete
new_run = client.agent_run.add_wait(agent_id=1, files=["path/to/file1"])

# if the Run times out (still in "running" status), fall back to polling:
while new_run.status == "running":
    new_run = client.agent_run.get(agent_id=1, run_id=new_run.run_id)
    time.sleep(10)

​
Query Access Logs

This is available on the Enterprise Plan. Contact Kolena if you’re not on an Enterprise plan but would like to try this feature.
time_range = {"start_time": "2025-09-09T00:00:00Z", "end_time": "2025-09-10T23:59:59Z"}

# Initial query
response = client.access_logs.query(
    time_range=time_range,
    page_size=100
)
all_events = response.events

# Fetch remaining pages
while response.next_cursor:
    response = client.access_logs.query(
        time_range=time_range,
        page_size=100,
        cursor=response.next_cursor
    )
    all_events.extend(response.events)

​
Serializing to JSON

All kolena-agents objects are standard Pydantic data objects and can be easily converted to and from JSON: 
from kolena_agents import Client
from kolena_agents.types.agent_run import AgentRun

client = Client()
run = client.agent_run.get(agent_id=1, run_id=2)

run_dict = run.model_dump(mode="json")  # get the AgentRun as a dictionary
run = AgentRun.model_validate(run_dict)  # deserialize an AgentRun

​
Webhook

Kolena provides a helper function to handle signature verification and parsing. See Webhook Connection for more information. 
from kolena_agents import webhook

result = webhook.construct_event(request_body, secret, request_headers)

​
Supported Python Versions

Python versions 3.8 and later are supported.