Skip to main content
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)

# update Agent properties
updated_agent = client.agent.update(
    agent_id=1,
    metadata={
        "environment": "production",
        "version": 2,
        "tags": ["nlp", "extraction"]
    }
)

​
Managing Agent Properties

You can attach key-value pairs metadata to your Agents for organizing, filtering, and tracking purposes. Metadata values can be primitives (strings, numbers, booleans, or null) or arrays (lists of primitive values). See the API reference for more details. 
# update Agent properties
agent = client.agent.update(
    agent_id=1,
    metadata={
        "environment": "production",
        "version": 2,
        "department": "finance",
        "tags": ["invoice-processing", "high-priority"],
        "threshold": 0.85,
        "enabled": True
    }
)

# access metadata from retrieved agent
agent = client.agent.get(agent_id=1)
print(agent.metadata)

# clear metadata
client.agent.update(agent_id=1, metadata={})

​
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 Integration 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.