# Manage API Keys Source: https://docs.agents.kolena.com/api-keys Manage API Keys for Programmatic Connections ## Using API Keys The HTTP API and Python client use API keys for authentication in the following ways: | Option | How To Use API Key | | - | - | | [HTTP API](/api-reference/quickstart) | Set API Key as Authorization bearer token in requests | | [Python client](/python-client/quickstart) | Set API Key to `KOLENA_API_KEY` environment variable | ## Personal API Keys Open your user profile at the bottom of the sidebar, click "Profile Settings", then switch to the "API Keys" tab. From here you can create new Keys and revoke existing ones. All personal API Keys have the same roles and permissions as your user. ## Service Users and API Keys This is available on the Enterprise Plan. [Contact Kolena](mailto:support@kolena.com) if you’re not on an Enterprise plan but would like to try this feature. Service users can be created with API Keys associated to them. This allows you to create Keys that are not tied to a specific user's membership in your Organization or their roles and permissions. Organization `admin`s can create service users and API Keys from the "API Keys" tab on [your Organization page](https://agents.kolena.com/organization?tab=api-keys). Creating an API Key from this modal will also create a service user. This service user has a default Organization role which you can manage, and can be [given permissions on individual agents](/fine-grained-access-control) like any other Organization user. ## Managing API Keys Across Your Organization Organization `admin`s can manage and revoke API keys for their team members and service users through the "API Keys" tab on [your Organization page](https://agents.kolena.com/organization?tab=api-keys). ## Programmatic API Key Management Users can programmatically manage their API keys for automated rotation and monitoring workflows. See the [API reference](/api-reference/create-api-key) or the [Python client guide](/python-client/quickstart#manage-api-keys) ### API Key Expiration This is available on the Enterprise Plan. [Contact Kolena](mailto:support@kolena.com) if you’re not on an Enterprise plan but would like to try this feature. Organization administrators can configure organization-wide API key expiration policies from the "Data & Security" tab on [your Organization page](https://agents.kolena.com/organization?tab=data-and-security): * **Organization-level policies**: Admins can require all keys to have an expiration date and set maximum allowed expiration periods for compliance * **Individual key expirations**: When creating new API keys, users can set expiration dates that don't exceed organization policies * **Expiration notifications**: Configure email alerts to be sent a specified number of days before key expiration to both administrators and the key owner # Add Agent Run Source: https://docs.agents.kolena.com/api-reference/add-agent-run openapi.json POST /api/v1/client/agents/{agent_id}/runs Push data to an Agent Run **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Add Agent Run (and Wait) Source: https://docs.agents.kolena.com/api-reference/add-agent-run-wait openapi.json POST /api/v1/client/agents/{agent_id}/runs/wait Push data to an Agent Run and wait for results #### Rate Limits This endpoint is rate limited based on your Organization tier: | Organization Tier | Rate Limit (requests/minute) | | - | - | | Starter | 10 | | Professional | 20 | | Enterprise | 40 | Rate limits are applied per Organization. #### Behavior This endpoint accepts data to create an Agent Run. If the results from all Prompts are available within the requested `timeout` period, the response will include the completed Agent Run with results. Otherwise, the response will contain a `status` of `running` and a `run_id` which can be used to [fetch the results](/api-reference/get-agent-run) later. Compared to the [Add Agent Run](/api-reference/add-agent-run) endpoint, this endpoint is synchronous and attempts to wait for the Agent Run to complete before returning results. Requests are processed with higher priority when resources are available, but the endpoint is rate limited more strictly. #### Handling Timeouts If the Agent Run takes longer than the request timeout period to complete, this endpoint will return the Agent Run in a `running` status. In such cases: 1. The response will indicate the Run is still in progress 2. You can use the [Get Agent Run](/api-reference/get-agent-run) endpoint to fetch the results later by providing the same `run_id` #### Tips to Avoid Timeouts To reduce the likelihood of timeouts when using this endpoint: 1. **Use smaller inputs** - Upload inputs with minimal content and fewer prompts 2. **Disable "Data Analysis"** - If your Agent has Data Analysis enabled, consider disabling it for faster processing 3. **Batch your requests** - For large volumes of data, consider using the non-waiting version ([Add Agent Run](/api-reference/add-agent-run)) and poll for results # Copy Agent Source: https://docs.agents.kolena.com/api-reference/copy-agent openapi.json POST /api/v1/client/agents/{agent_id}/copy Make a copy of an existing Agent **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Create API Key Source: https://docs.agents.kolena.com/api-reference/create-api-key openapi.json POST /api/v1/client/api-keys Create a new API key for the current user **Rate Limit:** This endpoint is limited to ** requests per minute** per user. **Important**: The `api_key` secret is only returned once during creation. Save it immediately in a secure location. # Delete Agent Run Source: https://docs.agents.kolena.com/api-reference/delete-agent-run openapi.json DELETE /api/v1/client/agents/{agent_id}/runs/{run_id} Delete Agent Run, including underlying files **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Delete API Key Source: https://docs.agents.kolena.com/api-reference/delete-api-key openapi.json DELETE /api/v1/client/api-keys/{key_id} Delete a specific API key owned by current user **Rate Limit:** This endpoint is limited to ** requests per minute** per user. This endpoint is idempotent - deleting a non-existent key returns success (204 No Content). # Download Agent Run Templated Output Source: https://docs.agents.kolena.com/api-reference/download-agent-run-templated-output openapi.json POST /api/v1/client/agents/{agent_id}/runs/{run_id}/templated-output Download an Agent Run into a [Templated Output](/templated-outputs) **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Get Agent Source: https://docs.agents.kolena.com/api-reference/get-agent openapi.json GET /api/v1/client/agents/{agent_id} Return a single Agent **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Get Agent Run Source: https://docs.agents.kolena.com/api-reference/get-agent-run openapi.json GET /api/v1/client/agents/{agent_id}/runs/{run_id} Return a single Run for an Agent, including results **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Get API Key Source: https://docs.agents.kolena.com/api-reference/get-api-key openapi.json GET /api/v1/client/api-keys/{key_id} Retrieve details for a specific API key owned by current user **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Create Ground Truth Source: https://docs.agents.kolena.com/api-reference/ground-truths/create-ground-truth openapi.json POST /api/v1/client/agents/{agent_id}/ground_truths Create a new Ground Truth for an Agent **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Create Ground Truth Version Source: https://docs.agents.kolena.com/api-reference/ground-truths/create-ground-truth-version openapi.json POST /api/v1/client/agents/{agent_id}/ground_truths/{ground_truth_id}/versions Create a new version of a Ground Truth for an Agent **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Create Validation Source: https://docs.agents.kolena.com/api-reference/ground-truths/create-validation openapi.json POST /api/v1/client/agents/{agent_id}/ground_truths/{ground_truth_id}/validations Create a Validation for a Ground Truth **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Delete Ground Truth Source: https://docs.agents.kolena.com/api-reference/ground-truths/delete-ground-truth openapi.json DELETE /api/v1/client/agents/{agent_id}/ground_truths/{ground_truth_id} Delete a Ground Truth for an Agent **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Delete Validation Source: https://docs.agents.kolena.com/api-reference/ground-truths/delete-validation openapi.json DELETE /api/v1/client/agents/{agent_id}/ground_truths/{ground_truth_id}/validations/{validation_id} Delete a Validation for a Ground Truth **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Get Ground Truth Source: https://docs.agents.kolena.com/api-reference/ground-truths/get-ground-truth openapi.json GET /api/v1/client/agents/{agent_id}/ground_truths/{ground_truth_id} Return Ground Truth for Agent **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Get Ground Truth Version Source: https://docs.agents.kolena.com/api-reference/ground-truths/get-ground-truth-version openapi.json GET /api/v1/client/agents/{agent_id}/ground_truths/{ground_truth_id}/versions/{version} Return a specific version of a Ground Truth for an Agent **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Get Validation Source: https://docs.agents.kolena.com/api-reference/ground-truths/get-validation openapi.json GET /api/v1/client/agents/{agent_id}/ground_truths/{ground_truth_id}/validations/{validation_id} Return a Validation result for a Ground Truth **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # List Ground Truths Source: https://docs.agents.kolena.com/api-reference/ground-truths/list-ground-truth openapi.json GET /api/v1/client/agents/{agent_id}/ground_truths Return all Ground Truths for Agent **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # List Ground Truth Versions Source: https://docs.agents.kolena.com/api-reference/ground-truths/list-ground-truth-versions openapi.json GET /api/v1/client/agents/{agent_id}/ground_truths/{ground_truth_id}/versions Return all versions of a Ground Truth for an Agent **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # List Validations Source: https://docs.agents.kolena.com/api-reference/ground-truths/list-validations openapi.json GET /api/v1/client/agents/{agent_id}/ground_truths/{ground_truth_id}/validations Return all Validation results for a Ground Truth **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # List Agent Runs Source: https://docs.agents.kolena.com/api-reference/list-agent-runs openapi.json GET /api/v1/client/agents/{agent_id}/runs Return all Runs for an Agent, including results **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # List Agents Source: https://docs.agents.kolena.com/api-reference/list-agents openapi.json GET /api/v1/client/agents Return all Agents **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # List API Keys Source: https://docs.agents.kolena.com/api-reference/list-api-keys openapi.json GET /api/v1/client/api-keys List all API keys owned by current user **Rate Limit:** This endpoint is limited to ** requests per minute** per user. Only keys belonging to the authenticating user are returned. Users cannot see keys from other users. # List Usage Records Source: https://docs.agents.kolena.com/api-reference/list-usage-records openapi.json GET /api/v1/client/usage List billed credit usage records for your account, scoped to accessible workspaces **Rate Limit:** This endpoint is limited to ** requests per minute** per user. ## Multiple Usage Records per Run A Run can have separate usage records for Prompt executions and document processing. These records may be split further by cost type or credit grant. A single Run can therefore have several records with the same `run_id` and `type: "agent_run"`. The response does not include Prompt IDs, cost types, or credit grants, so records may look alike. Keep each record when calculating usage. # List Workspaces Source: https://docs.agents.kolena.com/api-reference/list-workspaces openapi.json GET /api/v1/client/workspaces Return all Workspaces **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Query Access Logs Source: https://docs.agents.kolena.com/api-reference/query-access-logs PUT /api/v1/client/access-logs/query Query access logs This is available on the Enterprise Plan. [Contact Kolena](mailto:support@kolena.com) if you’re not on an Enterprise plan but would like to try this feature. **Rate Limit:** This endpoint is limited to ** requests per minute** per user. # Quickstart Guide Source: https://docs.agents.kolena.com/api-reference/quickstart Call Agents using the Kolena API The Kolena API provides a straight forward way to push data to your Agents and retrieve results. ## Create an Agent in the Web UI We recommend creating your Agent in the web UI at [https://agents.kolena.com](https://agents.kolena.com). This is the easiest way to create prompts and validate results on a sample set of files. See our guide on [Creating an Agent](/quickstart#creating-the-agent) for more details. Once you have created your Agent, you can call its API methods by using its `agent_id`. You can find this in the URL of the Agent page or by clicking the "Copy Agent ID" button on the Agent's overview page next to the Agent name. ## Push Data to an Agent Once you have an Agent created, upload files to a new Run using the [`POST /api/v1/client/agents/{agent_id}/runs`](/api-reference/add-agent-run) method. Files are uploaded as multipart form data in this request. The response body will be a JSON object containing the `run_id`, which you can use to retrieve results later. To authenticate your API requests, you need to set the `Authorization` header with your API key. See [Managing API Keys](/api-keys) for details. ## Retrieve Results from an Agent Results for an Agent Run can be retrieved using the [`GET /api/v1/client/agents/{agent_id}/runs`](/api-reference/list-agent-runs) method. This will return a list of all Runs for the Agent. Optionally, you can retrieve a single Run using the `run_id` query parameter. The response body is a JSON object of the following format: ```json theme={null} { "agent_id": 1, "run_id": 1, "run_url": "https://agents.kolena.com/my_org/agents/1/runs/1", "created": "2025-01-01T00:00:00", "updated": "2025-01-05T00:00:00", "files": [ "demo1.pdf", "demo2.csv" ], "order": [ "prompt_1", "prompt_2" ], "status": "success", "data": { "prompt_1": { "status": "success", "metadata": { "citations": [ { "file": "demo1.pdf", "pages": [ 2, 5 ] } ], "confidence": 1, "reasoning": "Looking at file demo1.pdf, ..." }, "value": "foo" }, "prompt_2": { "status": "success", "metadata": { "citations": [ { "file": "demo2.csv", "pages": [] } ], "confidence": 1, "reasoning": "The order amount is listed in demo2.csv" }, "value": 123 } } } ``` Note in particular the `data` field, which contains the results of the Agent Run. `data` is a dictionary keyed by the Prompt names you created in the Web UI for the Agent. Each entry in `data` contains the results for that Prompt, including: * `value`: The actual result value returned by the Agent for that Prompt. * `metadata`: Additional information about the result, such as reasoning and citations. The `metadata.confidence` field is deprecated and is no longer populated with a real confidence score. When present, the value is typically `1.0` and should not be used to assess result quality or uncertainty. Results can also be retrieved using a [webhook](/webhook). ## Get Agents information You can list all Agents using the [`GET /api/v1/client/agents`](/api-reference/list-agents) method, and get specific Agent information using the [`GET /api/v1/client/agents/{agent_id}`](/api-reference/get-agent) method. # Update Agent Source: https://docs.agents.kolena.com/api-reference/update-agent openapi.json PATCH /api/v1/client/agents/{agent_id} Update properties of an Agent **Rate Limit:** This endpoint is limited to ** requests per minute** per user. ## Overview Update properties of an Agent. Only `metadata` is currently supported for updates. # Overview Source: https://docs.agents.kolena.com/connecting-to-kolena Options for Programatic Connection to Kolena Kolena Agents can be connected to your data using app-level integrations such as [Sharepoint, Cloud Storage, and other means](/connections). If you require fine-grained control of your data or want to build a custom integration, you can connect to Kolena programmatically using any of the following options: | Option | When To Use | | - | - | | [HTTP API](/api-reference/quickstart) | Use this option if you want to connect to Kolena from any programming language or framework. This API exposes basic methods for adding new Runs and polling the results for an Agent. | | [Python client](/python-client/quickstart) | Use this option if you need to connect to Kolena from Python only. | | [Webhook](/webhook) | Use this option if you want to receive real-time results from Kolena about your Agents and Runs. Webhooks allow you to build custom integrations that respond to events in Kolena. | # Overview Source: https://docs.agents.kolena.com/connections Automate bringing documents into your Agent and sending its results to an Integration **Integrations** allow your Agent to connect directly with third-party applications and services. An Integration either brings documents into an Agent or sends its results out: * **Input**: documents coming into the Agent * **Output**: results going out of the Agent [See the full list of all supported integrations here](/connections/supported) and steps on how to integrate with them. Agents can also be connected using our [API](/api-reference/add-agent-run) or [Python Client](/python-client/quickstart). ## Configuring Integrations Integrations are configured for each Agent from the Workflow graph on the main Agent page. The Workflow graph starts at an **Input** node and ends at an **Output** node, with the Agent's Prompts in between. Each node lists what is currently connected to it. Clicking a node opens a panel where you can manage it: * From the **Input** node, click "Upload Files" to add documents yourself, or "Import from Integration" to bring them in automatically. * From the **Output** node, click "Add Output Template" to shape the results, or "Send to Integration" to send them somewhere. On a large Agent, use the "Jump to" control above the graph to bring the Input or Output node back into view. An Integration you connect is available to every Agent in the Workspace, and sharing one lets other people attach it to their own Agents. To view your integrations, open your user profile at the bottom of the sidebar, click "Profile Settings", then switch to the "Integrations" tab. Administrators, and anyone with a [Custom Role](/custom-roles) granting the "View Integration" action, can see every Integration connected across the Organization from the "Integrations" tab on the Organization page. ## How Integrations Work ### Input Integrations If documents come in from a file storage system (e.g. Box, Google Drive, S3), the Agent will automatically watch it for new files. When new files are detected, the Agent will create new Runs to process those files. See [Cloud Folder Sync](/connections/cloud-folder-sync) for details on how folders are kept in sync. An Input Integration can read files in two different patterns: 1. **Import Files Separately**: Each file in the connected location is processed as a separate Run. 2. **Group Files Together**: All files in a sub-folder pattern are processed together, where each sub-folder's content as a single run by the Agent. ### Output Integrations If results go out to a file storage system (e.g. Box, Google Drive, S3), the Agent will write output files to it after each Run is completed. An Output Integration can write files in two different patterns: 1. **Write to Directory**: Each Run by the Agent produces output files sent to the Integration. 2. **Write to File**: Each Run by the Agent produces a row in a single output spreadsheet. You can send your results to an Integration as PDF, Word, Excel, CSV, JSON, or Powerpoints. You can also use [templates](/templated-outputs) to customize the format of your output files. ### Example Workflows These patterns can be combined. Let's consider how to model some example workflows: #### Lease Abstraction Suppose you have multiple lease documents and amendments for various properties stored in a Box.com folder: ``` /Leases /Leases/Property_A/Lease.pdf /Leases/Property_A/Amendment_1.pdf /Leases/Property_A/Amendment_2.pdf /Leases/Property_B/Lease.pdf /Leases/Property_B/Amendment_1.pdf ``` and you want to generate an abstract file for each property. In this case, you would bring documents in from the Box.com folder, grouping files by subfolder (i.e., Property\_A, Property\_B) so that each property's documents are processed as a single run. The output can then be sent to another Box.com folder, with one output file per run. #### Utility Bill Extraction Suppose you have a folder of utility bills in Google Drive which you want to extract key details into a table, which one row per bill: ``` /Bills /Bills/Bill_001.pdf /Bills/Bill_002.pdf /Bills/Bill_003.pdf ``` In this case, you would bring documents in from the Google Drive folder and send results out to a single Google Sheet. The output of each runs will be synced to a new row in the Google Sheet. ## FAQ ### I've connected an Integration, when will my Agent start processing files? Files already in the connected location are imported when the Integration is added, and new files are typically detected within a minute or two of being added. For Integrations that group files together, Kolena waits until a sub-folder has been quiet for 5 minutes before processing it, so it may take up to five minutes before new runs are created. When connecting a folder that already contains a large number of files, the initial import happens in batches and may take some time to complete. See [Cloud Folder Sync](/connections/cloud-folder-sync#bulk-additions-and-large-folders) for details. ### How many Integrations can I add to my Agent? A single Agent can have multiple Integrations bringing documents in and sending results out. ### What happens if I add a new file to a connected folder? For Integrations where files are imported separately: * If a new file is added, Kolena will create a new run for that file For Integrations where files are grouped together: * If a new file is added to a sub-folder, Kolena will create a new run if one does not exist or update an existing run if one already exists for that grouping. ### What happens if I remove a file from a connected folder? By default, Kolena will not delete or update existing runs if a file is removed. Grouped folder Integrations on Box, Google Drive, and SharePoint can opt in to [syncing deletions](/connections/cloud-folder-sync#syncing-deletions), which removes deleted files from their Runs and either re-runs the affected Runs or marks them as stale. ### What happens if I move a file into or within a connected folder? A file moved or copied into a synced folder is imported the same as a new file, even if the file itself is old. For files moved between sub-folders within a synced folder, the file is imported at its new location; the copy at the old location is only removed if [syncing deletions](/connections/cloud-folder-sync#syncing-deletions) is enabled. ### What happens if I delete a Run or file in Kolena? The deletion is permanent: syncing will not re-import the file from the same location, even during a full re-scan. If the file later appears in a different location, it is treated as new and imported there. ### What happens if I update a file in a connected folder? If you update the content of an existing file, Kolena will not automatically re-process the updated files or refresh existing runs. # Cloud Folder Sync Source: https://docs.agents.kolena.com/connections/cloud-folder-sync How Kolena keeps your Agents in sync with cloud storage folders When a folder from a [cloud storage integration](/connections/supported) (Box, Google Drive, SharePoint, Amazon S3, or Azure Blob Storage) is used as an input to an Agent, Kolena keeps the Agent in sync with it automatically. The files already in the folder are imported when the Integration is added, and from then on the folder and all of its subfolders are monitored for changes. ## Change Detection For Box, Google Drive, and SharePoint, Kolena reads the provider's change feed and only processes what has changed since the last check. For Amazon S3 and Azure Blob Storage, Kolena periodically lists the folder and imports files it has not seen before. Each Integration is checked about once a minute. ## How Changes Are Handled | Change in the cloud folder | What Kolena does | | - | - | | File added | Creates a new Run (or, for grouped Integrations, adds the file to its subfolder's Run) | | File moved or copied into the folder | Imports it the same as a new file, even if the file is old | | Subfolder moved or copied into the folder | Imports all files inside it | | File edited in place | Nothing. Existing Runs are not automatically re-processed | | File deleted or moved out of the folder | Nothing, unless [deletion sync](#syncing-deletions) is enabled | Hidden system files (e.g. `.DS_Store`, `Thumbs.db`, `desktop.ini`) and Microsoft Office temporary lock files are never imported. If you delete a Run or file in Kolena, syncing will not re-import that file from the same location, even during a full re-scan. ## Grouped Folders When an Integration groups files together, each subfolder becomes a single Run containing every file nested beneath it. To avoid processing a folder while files are still being uploaded to it, Kolena waits until a subfolder has had no new file activity for 5 minutes before creating or updating its Run. When a file is added to a subfolder that already has a Run, the file is added to the existing Run and its Prompts are re-run. Manual edits to the Run's results are preserved. ## Syncing Deletions By default, deleting a file in the cloud folder never changes existing Runs in Kolena. Grouped Integrations on Box, Google Drive, and SharePoint can enable **Sync cloud deletions** when configuring the Integration. [Contact Kolena](mailto:support@kolena.com) to enable this feature for your organization. When enabled, files deleted or moved out of the folder are also removed from their Runs. The **On File Delete** setting controls what happens to the affected Run: **Re-run Prompts** (the default) re-processes the Run with its remaining files, while **Mark Run as stale** keeps the existing results and flags them as out of date so you can re-run later. Runs themselves are never deleted automatically. A Run whose files are all removed is kept and marked stale. ## Bulk Additions and Large Folders When many files arrive at once, or when a folder that already contains many files is first connected, the files are imported in batches over successive checks. No files are skipped. Large imports simply take longer to complete, and new files added in the meantime are still detected and imported. The standard [file limits](/faq/supported-formats#are-there-limits-on-file-uploads) apply to files imported from cloud Integrations. Files exceeding the limits appear on the Run with an error message rather than being silently skipped. # Supported Integrations Source: https://docs.agents.kolena.com/connections/supported List of Available Integrations to Connect Your Agents Below are all supported integrations and steps on how to integrate with them. Agents can also be connected using our [API](/api-reference/add-agent-run) or [Python Client](/python-client/quickstart). If you do not see an Integration you'd like to use, contact us and we will prioritize support! ##
Amazon S3
Amazon S3 can be used as an input to an Agent, or an output for its results. To connect an Amazon S3 bucket to an Agent:
  1. Navigate to the Agent you wish to connect
  2. From the Workflow graph, click the "Input" node and then "Import from Integration", or click the "Output" node and then "Send to Integration"
  3. If an Amazon S3 integration already exists, click "Select" under "Amazon S3" and choose an account. Otherwise, click "Connect" and follow the configuration steps below:

    4. Step 1: Specify Bucket(s)

    1. Enter the bucket name(s) you wish to connect
    2. Click "Continue"

    Step 2: Create Access Policy

    1. Copy the "Access Policy" JSON
    2. In your AWS console:
      1. Navigate to IAM Policies page
      2. Click "Create Policy" and select the "JSON" tab
      3. Paste the copied JSON
      4. Click through the "Next" buttons, adding the desired name, description, and tags

    Step 3: Create Trust Policy

    1. Copy the "Trust Policy" JSON
    2. In your AWS console:
      1. Navigate to IAM Roles page
      2. Click "Create Role" and select "Custom trust policy"
      3. Paste the copied JSON
      4. Search for and select the access policy created in Step 2. Click "Next"
      5. Provide a role name and review the permissions, then click "Create role"
      6. Copy the role's ARN for use in the next step

    Step 4: Save Integration

    1. In Kolena, click "Continue"
    2. Enter the ARN of the role created in Step 3
    3. Click "Finish"
  4. Select the bucket and folder you wish to connect to
##
Azure Blob Storage
Azure Blob Storage can be used as an input to an Agent, or an output for its results. To connect Azure Blob Storage to an Agent:
  1. Navigate to the Agent you wish to connect
  2. From the Workflow graph, click the "Input" node and then "Import from Integration", or click the "Output" node and then "Send to Integration"
  3. If an Azure Blob Storage integration already exists, click "Select" under "Azure Blob Storage" and choose an account. Otherwise, click "Connect" and follow the configuration steps below:

    4. Step 1: Create Azure App Registration for Kolena

    1. From the Azure portal, search for "App registrations" and navigate to this page
    2. Click "New Registration"
      1. Under "Supported account types", select "Accounts in any organizational directory"
      2. Click "Register" to save the App registration
    3. Click on the App registration you have created
    4. Note the "Tenant ID" and "Application (client) ID"
    5. Click "Certificates & secrets", then "New client secret"
      1. Click "Add" to save this secret and note the key value

    Step 2: Assign Roles to App Registration

    Assign Storage Blob Delegator Role

    1. Navigate to the storage account containing your blobs
    2. Click "Access Control (IAM)"
    3. Click the "Role assignments" tab
      1. Click "Add", then "Add role assignment"
    4. Search for and select "Storage Blob Delegator"
    5. Click on the "Members" tab, then click "Select members"
      1. Search for the App registration created in Step 1
      2. Click "Select"
    6. Click "Review + assign" to save

    Assign Storage Blob Data Reader Role

    1. From the storage account, click "Containers" under "Data Storage" and click on the container containing your blobs
    2. Click "Access Control (IAM)"
    3. Click the "Role assignments" tab
      1. Click "Add", then "Add role assignment"
    4. Search for and select "Storage Blob Data Reader"
    5. Click on the "Members" tab, then click "Select members"
      1. Search for the App registration created in Step 1
      2. Click "Select"
    6. Click "Review + assign" to save
    7. (Optional) Repeat the steps above for any additional containers you wish to connect

    Assign Storage Blob Data Contributor Role

    1. From the storage account, click "Containers" under "Data Storage" and click on the container containing your blobs
    2. Click "Access Control (IAM)"
    3. Click the "Role assignments" tab
      1. Click "Add", then "Add role assignment"
    4. Search for and select "Storage Blob Data Contributor"
    5. Click on the "Members" tab, then click "Select members"
      1. Search for the App registration created in Step 1
      2. Click "Select"
    6. Click "Review + assign" to save
    7. (Optional) Repeat the steps above for any additional containers you wish to connect

    Step 3: Save Integration

    1. In Kolena, fill in the fields for the integration:
      1. **Tenant ID**: The Directory (tenant) ID of the App registration created in Step 1
      2. **Client ID**: The Application (client) ID of the App registration created in Step 1
      3. **Client Secret**: The secret key for the App registration created in Step 1
      4. **Storage Account Name**: The storage account in Azure you wish to connect to
      5. **Storage Blob Endpoint URL**: The endpoint for accessing the storage account. Can be found in "Endpoints" under "Settings" for your storage account. Usually of the form `https://.blob.core.windows.net`
      6. **Container(s)**: The Azure storage container(s) to which you granted role permissions in Step 2
    2. Click "Finish"
  4. Select the container and folder you wish to connect to
##
Box
Box can be used as an input to an Agent, or an output for its results. To connect a Box account to an Agent: 1. Navigate to the Agent you wish to connect 2. From the Workflow graph, click the "Input" node and then "Import from Integration", or click the "Output" node and then "Send to Integration" 3. If a Box integration already exists, click "Select" under "Box" and choose an account. Otherwise, click "Connect" and click to authorize access 4. Select the folder you wish to connect to ##
Email
Agents can be set up to receive documents by email, or to email their results out. To connect an email address to an Agent:
  1. Navigate to the Agent you wish to connect
  2. From the Workflow graph, click the "Input" node and then "Import from Integration", or click the "Output" node and then "Send to Integration"
  3. Select the "Email" integration
  4. If the Agent should receive emails:
    1. Copy the recipient email address (this is where emails must be sent to)
    2. (Optional) Specify a sender or domain the email must be sent from. If omitted, the Agent will accept emails from any email address
    3. Click "Confirm"
    4. Send or forward emails to the recipient address
  5. If the Agent should send emails:
    1. Specify a recipient email address
      2. An Agent can send emails to a fixed recipient address, or dynamically generate the recipient address, subject, and body based on the Agent's output. To do this:
      • Create a Prompt for the Agent with output type `Text`.
      • Select this Prompt from the "To:", "Subject:", or "Body:" fields.
      • A Prompt used for the "To:" field can return multiple recipients in a single run - separate the addresses with commas, semicolons, or new lines, and the email will be sent to all of them.
      • For a given run, every address the "To:" Prompt returns must be a valid email. If any address is invalid or missing, that run is marked "Failed to Send" (with the invalid value shown) and is retried on later runs; other runs are unaffected.
    2. (Optional) Modify the generated sender address, or use your own. This is the address the Agent will send emails from
    3. (Optional) Enable "Attach input files" to include the run's original input files as additional email attachments
    4. Click "Confirm"
##
Gmail
Gmail can be used as an input to an Agent. To connect a Gmail account to an Agent: 1. Navigate to the Agent you wish to connect 2. From the Workflow graph, click the "Input" node and then "Import from Integration" 3. If a Gmail integration already exists, click "Select" under "Gmail" and choose an account. Otherwise, click "Connect" and click to authorize access 4. When prompted by Google, ensure you select the following required scopes: **View your email messages and settings.** 5. (Optional) Specify a sender (email address) or labels to filter emails. By default, all emails to the account will be brought in 6. Click "Confirm" ##
Google Drive
Google Drive can be used as an input to an Agent, or an output for its results. To connect a Google Drive to an Agent: 1. Navigate to the Agent you wish to connect 2. From the Workflow graph, click the "Input" node and then "Import from Integration", or click the "Output" node and then "Send to Integration" 3. If a Google Drive integration already exists, click "Select" under "Google Drive" and choose an account. Otherwise, click "Connect" and click to authorize access 4. When prompted by Google, ensure you select the following required scopes: **See, edit, create, and delete all of your Google Drive files.** 5. Select the folder you wish to connect to ####
Google Sheet
Results from an Agent can be exported to a spreadsheet in your Google Drive. Add Google Drive under "Output Integrations" using the instructions above, then: 1. Select "xlsx" as the export format 2. Click "Export as Single Excel File" The results of the Agent will be sent to a single spreadsheet in the specified location. Each row will represent the results of a Run for the Agent. Adding or removing Runs from the Agent will add or remove rows from the Google Sheet, respectively. ##
Notion (KMS)
Knowledge Management Systems (KMS) can be configured as prompt documents for your Agents. Supported systems: * Notion To connect a KMS platform: 1. While editing a Prompt, open the attachments menu and click "Connect Cloud Documents" 2. Click the "KMS" card 3. If a KMS integration already exists, click "Select" under "KMS" and choose an account. Otherwise, click "Connect" and click to authorize access ##
Salesforce / HubSpot (CRM)
CRM (Customer Relationship Management) systems can receive an Agent's results. Supported systems: * Salesforce * HubSpot To connect a CRM platform to an Agent: 1. Navigate to the Agent you wish to connect 2. From the Workflow graph, click the "Output" node and then "Send to Integration" 3. Click the "CRM" card 4. If a CRM integration already exists, click "Select" under "CRM" and choose an account. Otherwise, click "Connect" and click to authorize access Supported objects: * deal/opportunity * contact * company The results of the Agent will be used to create or update supported objects. ##
Sharepoint
Sharepoint can be used as an input to an Agent, or an output for its results. To connect a Sharepoint drive to an Agent: 1. Navigate to the Agent you wish to connect 2. From the Workflow graph, click the "Input" node and then "Import from Integration", or click the "Output" node and then "Send to Integration" 3. If a Sharepoint integration already exists, click "Select" under "Sharepoint" and choose an account. Otherwise, click "Connect" and click to authorize access 4. Select the site you wish to connect to, followed by the drive, and then any directory within the drive ####
Excel
Results from an Agent can be exported to a spreadsheet in your SharePoint. Add SharePoint under "Output Integrations" using the instructions above, then: 1. Select "xlsx" as the export format 2. Click "Export as Single Excel File" The results of the Agent will be sent to a single spreadsheet in the specified location. Each row will represent the results of a Run for the Agent. Adding or removing Runs from the Agent will add or remove rows from the SharePoint Excel file, respectively. ##
Webhook
Check out the [Integrate using Webhooks](/webhook) section for details on setting up your service to receive webhook deliveries. Once the your service is ready, you can follow the steps in this section to register your webhook. A webhook can receive an Agent's results. To connect a webhook URL to an Agent:
  1. Navigate to the Agent you wish to connect
  2. From the Workflow graph, click the "Output" node and then "Send to Integration"
  3. If a Webhook integration already exists, click "Select" under "Webhook" and choose an account. Otherwise, click "Connect" and follow the configuration steps below:

    4. Step 1: Specify Webhook URL

    1. Enter the webhook URL you wish to connect, e.g. `https://example.com/webhook/document-agent/results`
    2. Click "Continue"

    Step 2: Save the Secret

    1. Copy the "secret" and save it securely. Use the secret to validate authenticity and integrity of requests from Kolena
    2. Click "Finish"
  4. (Optional) Specify an additional path to the selected webhook URL. The final URL would be `/`
  5. Click "Confirm"
# Credit Limits Source: https://docs.agents.kolena.com/credit-limits Control and manage spending with credit limits ## Overview Credit limits allow you to set spending limits on credit usage at both the Organization and Workspace levels. When a credit limit is reached, Kolena will automatically prevent further credit consumption to help you stay within budget. Credit limits are an optional feature available to Organizations on credit-based pricing plans. All limits are set on a monthly-basis. Usage resets back to zero at the start of each calendar month. ## How Credit Limits Work Credit limits enforce spending limits by tracking cumulative credit usage and comparing it against configured thresholds: * **Organization-level limits:** limit total overage credits across the entire Organization * **Workspace-level limits:** limit total credits (monthly quota + overage) for specific Workspaces When a limit is reached: * New Runs cannot be created * Prompts already running finish, and are billed as usual * Prompts that have not started yet fail, including Prompts in a Run that is already in progress * Failed Prompts are not resumed automatically once the limit is raised or the month rolls over — re-run them from the Agent * Administrators receive email notifications at 90% and 100% of the limit ## Setting Up Credit Limits ### Organization-Level Overage Limit The Organization-level limit limits how many overage credits can be consumed beyond your monthly quota. **To set an Organization-level overage limit:** 1. Click "Manage Organization" from your user profile at the bottom of the sidebar, or navigate to [your Organization page](https://agents.kolena.com/organization) 2. Click the "Usage" button 3. Go to the **Usage Limits** section 4. Click the **Configure Overage Limit** button to set the Organization-level overage limit For example, if your monthly quota is 10,000 credits and you set an overage limit of 5,000 credits: * You can use up to 15,000 total credits per month (10,000 quota + 5,000 overage) * After 15,000 credits, new Prompts and Runs will be blocked until the next month * Prepaid credits are consumed but not counted toward the overage limit ### Workspace-Level Limit Workspace-level limits limit the total credits (monthly + overage) that can be consumed by a specific Workspace. **To set a workspace-level limit:** 1. Click "Manage Organization" from your user profile at the bottom of the sidebar, or navigate to [your Organization page](https://agents.kolena.com/organization) 2. Click the "Usage" button 3. Go to the **Usage Limits** section 4. Click the **Configure Limits** button to set the Workspace-level limit For example, if you set a Workspace limit at 2,000 credits: * The Workspace can consume up to 2,000 credits from monthly quota and overage combined * After 2,000 credits, new Prompts and Runs in that Workspace will be blocked * Other Workspaces remain unaffected Workspace-level limits are useful for: * Allocating budgets across different teams or projects * Limiting usage for experimental or test Workspaces * Providing guardrails for new users or pilot projects ## Notifications Administrators receive email alerts when credit usage approaches or exceeds limits: ### Organization-Level Alerts * **90% threshold**: Email sent when overage usage reaches 90% of the limit * **100% threshold**: Email sent when overage usage reaches or exceeds 100% of the limit Organization administrators receive these notifications. ### Workspace-Level Alerts * **90% threshold**: Email sent when Workspace usage reaches 90% of the limit * **100% threshold**: Email sent when Workspace usage reaches or exceeds 100% of the limit Both Organization administrators and Workspace administrators receive these notifications. Notifications are sent once per threshold per month. If usage fluctuates below and back above a threshold, a new notification will not be sent until the next month. ## Monitoring Credit Usage To monitor your credit usage and limits: 1. Visit [your Organization page](https://agents.kolena.com/organization?tab=data-and-security) 2. View the **Usage** section to see: * Current month's credit consumption * Monthly quota and remaining credits * Overage credits used (if applicable) * Progress toward any configured limits You can also view detailed credit usage by: * Individual Agent * Individual Run * Workspace * Time period See [Tracking Usage](/tracking-usage) for more details on viewing and analyzing credit consumption. ## Responding to Limit Alerts When you receive a 90% threshold alert: 1. Review current usage patterns in [your Organization page](https://agents.kolena.com/organization?tab=data-and-security) 2. Consider increasing the limit if usage is expected to continue 3. Investigate and optimize prompts or workflows if usage is higher than expected When a limit is reached (100%): 1. Prompts and Runs cannot proceed until the limit is raised or the next billing period begins 2. Contact your Organization administrator to adjust limits if needed # Custom Roles Source: https://docs.agents.kolena.com/custom-roles Combine Allowed Actions into Custom Roles This is available on the Enterprise Plan. [Contact Kolena](mailto:support@kolena.com) if you’re not on an Enterprise plan but would like to try this feature. Kolena has three [default Roles](/user-management#assign-roles) which can be applied to Users or Teams. In some cases you may wish to define customized Roles. Example use cases include: * Restricting access to a true "read-only" role. * Allowing administrative users the ability to manage billing without being able to modify Agents. ## Defining Custom Roles Custom Roles can be defined from your [Organization page](https://agents.kolena.com/organization?tab=custom-roles). Click "Add Custom Role" and then provide a name for the Role and select all actions which the Role will be allowed to perform. All actions have a **scope** associated to them. This defines the extent in which the action is allowed. Actions can be scoped to the **Organization** or to the **Workspace**. For example: * "Manage User" with Organization scope allows inviting new Users and controlling membership within the Organization. * "Manage User" with Workspace scope allows modifying the Roles of all Users and Teams within the Workspace. ### Available Actions The following actions can be assigned to Custom Roles: | Scope | Action | Description | | - | - | - | | Workspace | View Agent | Allows viewing Agents and all associated data including Prompts, Results, and Dashboards within the Workspace. | | Workspace | Create Agent Run | Allows uploading files to an Agent and creating new Agent Runs within the Workspace. | | Workspace | Delete Agent Run | Allows deleting files from an Agent and deleting Agent Runs within the Workspace. | | Workspace | Create Agent Comment | Allows adding comments to results of Agent Runs within the Workspace. | | Workspace | Delete Agent | Allows deleting Agents within the Workspace. | | Workspace | Override Agent Result | Allows overriding the result of Agent Runs within the Workspace. | | Workspace | Manage Agent Data Retention Policy | Allows managing data retention policies for Agents within the Workspace. | | Workspace | Manage Agent Connections | Allows connecting new Integrations and attaching them to Agents within the Workspace. Updating or removing an Integration afterwards is limited to the person who connected it, or to a Role with the Organization scoped Manage Integration action. | | Workspace | Manage Agent Dashboards | Allows managing Dashboards for Agents within the Workspace. | | Workspace | Manage Agent Prompts | Allows managing Prompts for Agents within the Workspace. | | Workspace | Manage Agent Model Routing | Allows changing the model routing for Agents within the Workspace, including migrating an Agent to the latest generation of models. | | Workspace | Manage Agent Permissions | Allows managing permissions for Agents within the Workspace. | | Workspace | Manage Agent Metadata | Allows managing Metadata (including name, notes, icon) for Agents within the Workspace. | | Workspace | Manage Agent Validation | Allows managing Ground Truths and Validations for Agents within the Workspace. | | Workspace | Create Agent | Allows creating new Agents within the Workspace. | | Workspace | Manage Folder | Allows creating, renaming, and deleting folders within the Workspace, and moving Agents between them. | | Workspace | View Usage | Allows viewing usage statistics for the Workspace. | | Workspace | Manage Workspace Data Retention Policy | Allows managing data retention policies for the Workspace. | | Workspace | ⚠️ Manage User | Allows adding and removing Users and Teams in the Workspace and assigning any Workspace Role. **Equivalent to the `admin` Role within the Workspace** (a holder can grant themselves access to every Agent in it). | | Organization | View Access Logs | Allows viewing access logs for the Organization. Also allows listing all Workspaces in the Organization. | | Organization | Manage Data Retention Policy | Allows managing data retention policies for the Organization. | | Organization | Manage IP Whitelist | Allows managing the IP whitelist for the Organization. | | Organization | Use API Key | Allows managing and using API keys **associated to your User** within the Organization. | | Organization | View API Key | Allows viewing all API keys within the Organization. | | Organization | Manage API Key | Allows creating and revoking all API keys within the Organization. | | Organization | View Usage | Allows viewing usage statistics for the Organization. Also allows listing all Workspaces in the Organization. | | Organization | Manage Usage | Allows managing usage settings (limits) for the Organization. Also allows listing all Workspaces in the Organization. | | Organization | View Integration | Allows viewing every Integration connected in the Organization, including who connected each one and which Agents use it. Also allows listing all Workspaces in the Organization. | | Organization | Manage Integration | Allows updating, testing, and removing any Integration in the Organization, including ones connected by someone else. | | Organization | ⚠️ Manage User | Allows adding, removing, and modifying Users, Service Users, and Teams, managing Custom Roles, and configuring directory sync. **Equivalent to the `admin` Role** (a holder can assign any Role, including `admin`, to themselves or anyone else). | **⚠️ `Manage User` is an administrative action.** At Organization scope it is equivalent to the `admin` Role: a holder can assign any Role, including `admin`, to themselves, and so can reach every action in the Organization. At Workspace scope it is equivalent to `admin` within that Workspace. A Custom Role containing `Manage User` cannot be used to restrict what its holder can reach. Grant it only to Users you would make administrators. ## Assigning Custom Roles Custom Roles can be assigned in all the same places as the default `viewer`, `editor`, `admin` Roles. Custom Roles can be assigned to individual Users or to Teams. Assignments can happen at the Organization level from the [Users tab](https://agents.kolena.com/organization?tab=users) or within individual Workspaces. If your Organization contains multiple Workspaces, any Custom Role which implements an `Organization` scoped action must be assigned at the Organization level to a User or Team. **Example:** Suppose you have a Custom Role named `Security Auditor` which contains the `View Access Logs` action (Organization scope) and the `View Agent` action (Workspace scope). You should assign this role in two places: 1. To Users or Teams from the Organization Users/Teams tab *and* 2. To the same Users or Teams from each Workspace's Roles tab. # Data Retention Source: https://docs.agents.kolena.com/data-retention Automatically Purge Data From Kolena When you upload files to an Agent, Kolena stores both the files and the Prompt results in cloud storage. Kolena also retains the source file behind any Ground Truth you convert (for example the spreadsheet or CSV a Ground Truth was created from). * Deleting an Agent Run (via UI or API) immediately deletes its files **and** results. * If you do nothing, the data remains until a retention policy triggers or you delete it manually. ## Setting Retention Policies This is available on the Enterprise Plan. [Contact Kolena](mailto:support@kolena.com) if you’re not on an Enterprise plan but would like to try this feature. Data retention policies can be set at three levels: Organization, Workspace, and Agent. These policies dictate the maximum amount of time data can exist on Kolena before it is automatically purged. The amount of time is measured from the time the file is initially uploaded to Kolena. When setting a retention policy, any files, Runs, and Ground Truth source files which are older than the new policy will be immediately and permanently deleted. For example, setting an Organization policy of one year will delete all files and Runs across **all** Agents which were uploaded more than one year ago. Ground Truth source files older than the policy are removed as well; the Ground Truth itself (its converted values and versions) is kept, but its original source file can no longer be downloaded or re-converted. ### Organization-Level Policy An Organization policy can be set by `admin` users through the "Data & Security" tab on [your Organization page](https://agents.kolena.com/organization?tab=data-and-security). This is the highest-level policy and applies to all Workspaces and Agents within the Organization. ### Workspace-Level Policy Workspace policies can be set by `admin` users through the "Data & Security" section on the Workspace settings page. A Workspace policy: * Applies to all Agents within that Workspace * Must be equal to or more restrictive than the Organization-level policy (if one is set) * Overrides the Organization policy for Agents in that Workspace (by being more restrictive) * Can be removed, in which case the Organization policy will apply This allows different Workspaces to have different data retention requirements while still maintaining compliance with Organization-wide policies. ### Agent-Level Policy Agent policies can be set individually on each Agent. This setting can be found on the main page of the Agent. An Agent policy: * Applies only to that specific Agent * Must comply with both the Workspace policy and Organization policy (if set) * Provides the most granular control over data retention * If no Agent policy is set, the Workspace policy (if any) will apply, otherwise the Organization policy will apply ## Chat History Leonard chat sessions are purged automatically as well: * If an Organization or Workspace retention policy is set, chats are deleted according to the strictest applicable policy. * If no retention policy is set, chats are deleted 30 days after creation. As with files and Runs, the retention window is measured from creation time. Agent-level policies do not apply to chats. # Data Privacy & Security Source: https://docs.agents.kolena.com/faq/security Please see [https://trust.kolena.com/](https://trust.kolena.com/) for privacy policies and security reports, including: * SOC 2 Type 2 reports * HIPAA compliance reports * Pen testing reports ## Is my data used to train AI models? Data uploaded to Kolena is never used for AI model training. User interactions and input within Kolena are also never used for AI model training. ## Where is my data stored? Data uploaded to Kolena is stored in US-based cloud data centers. All data is encrypted at rest and in transit. ## How can I restrict access to my data? Access to Kolena can be restricted using the following means: * **User Access Control:** Manage user roles and permissions to control who can access specific Agents and data within your Organization. Learn more [here](/user-management). * **IP whitelisting:** Restrict access to Kolena to specific IP addresses or CIDR ranges. This is configurable from the "Data & Security" tab on [your Organization page](https://agents.kolena.com/organization?tab=data-and-security). ## Can I control how long my data stays in Kolena? Yes. Retention policies for uploaded data can be set. This allows data to automatically be deleted from Kolena's cloud storage based on fixed time intervals. Learn more about data retention [here](/data-retention). ## Can I view audit or access logs for usage on Kolena? This is available on the Enterprise Plan. [Contact Kolena](mailto:support@kolena.com) if you’re not on an Enterprise plan but would like to try this feature. Yes. All access to your data is logged and auditable. The following attributes are recorded for each user event on Kolena: * Timestamp * Workspace * User * IP address * Action (e.g., view agent, upload file, delete prompt) * HTTP method and path * HTTP response code These access logs can be retrieved programmatically via our [Query Access Logs API](/api-reference/query-access-logs) or through the [Python client](/python-client/quickstart). ## How do I reset my password? See [Resetting Your Password](/get-access#resetting-your-password). # Support Source: https://docs.agents.kolena.com/faq/support ## How can I contact Kolena support? On [Kolena](https://agents.kolena.com/) you will see a "Support" button at the bottom of the sidebar. Clicking this button will open a chat window where you can ask questions and report issues. Our support team is available during business hours to assist you. ## How can I see the status of Kolena services? Kolena maintains a [status page](https://agents-status.kolena.com/) where you can see the current status of our services, as well as any past incidents and maintenance events. Click "Subscribe to updates" on the status page to receive notifications about incidents and maintenance events via email. In the event that an outage occurs and it is not reported on the status page, an incident can be reported by either: 1. Visiting our [status page](https://agents-status.kolena.com/) and click "Report a problem" to submit a report. 2. Directly contacting our incident response line at **[incidents@kolena.com](mailto:incidents@kolena.com)**. # File Uploads Source: https://docs.agents.kolena.com/faq/supported-formats ## What file formats does Kolena support? Kolena aims to support all data formats from all data sources, without conversion. If you do not see a format listed here, connect with us and we will prioritize support! | File Type | File Extension | | - | - | | Scanned Documents | `.pdf`, all image extensions | | PDFs | `.pdf` | | Emails | `.eml`, `.msg` | | Office Documents | `.docx`, `.doc`, `.pptx`, `.ppt`, `.xlsx`, `.xls`, `.rtf`, `.odt` | | Spreadsheets \* | `.csv`, `.xlsx`, `.xls`, `.xlsm` | | Images | `.jpg`, `.jpeg`, `.gif`, `.png`, `.webp`, `.tiff`, `.tif`, `.bmp`, `.heic`, `.heif`, `.svg`, `.jfif`, `.avif` | | Webpages | `.html`, `.htm`, `.xhtml` | | Text | `.txt`, `.tsv`, `.json`, `.jsonl`, `.md`, `.markdown`, `.yaml`, `.yml`, `.xml`, `.xsd`, `.xbrl`, `.log`, `.srt`, `.vtt`, `.py` | | Audio | `.mp3`, `.mp4`, `.mpeg`, `.mpga`, `.m4a`, `.oga`, `.ogg`, `.opus`,`.wav`, `.webm` | | Archive | `.zip` |

\* Macros and formulas are removed upon import

## Are there limits on file uploads? Some limits are applied when uploading files to a run: * **Number of Files Per Run:** A maximum of 300 files can be uploaded within a single Agent Run. * **Total File Size Per Run:** A maximum of 2 GB of files can be uploaded within a single Agent Run. * **Maximum File Size:** Individual files can be up to 250 MB in size. * **Number of Pages Per Run:** A maximum of 1,500 pages of content can be uploaded within a single Agent Run. ## Are there limits on prompt attachments? When attaching files to a Prompt, up to 5 files per Prompt can be attached. Each file can be up to **5 MB** in size. ## Are there limits on files I can use when creating prompts? When [uploading a file to create Prompts](/prompts-from-file), a single file can be uploaded with a maximum size of **20 MB**. # Language Support Source: https://docs.agents.kolena.com/faq/supported-languages ## Which languages does Kolena support? Kolena supports a wide variety of world languages:1 | | | | | | - | - | - | - | | Afrikaans | Albanian | Amharic | Arabic | | Armenian | Assamese | Azerbaijani | Basque | | Belarusian | Bengali | Bosnian | Bulgarian | | Catalan | Cebuano | Chinese (Simplified) | Chinese (Traditional) | | Corsican | Croatian | Czech | Danish | | Dhivehi | Dutch | English | Esperanto | | Estonian | Filipino (Tagalog) | Finnish | French | | Frisian | Galician | Georgian | German | | Greek | Gujarati | Haitian Creole | Hausa | | Hawaiian | Hebrew | Hindi | Hmong | | Hungarian | Icelandic | Igbo | Indonesian | | Irish | Italian | Japanese | Javanese | | Kannada | Kazakh | Khmer | Korean | | Krio | Kurdish | Kyrgyz | Lao | | Latin | Latvian | Lithuanian | Luxembourgish | | Macedonian | Malagasy | Malay | Malayalam | | Maltese | Maori | Marathi | Meiteilon (Manipuri) | | Mongolian | Myanmar (Burmese) | Nepali | Norwegian | | Nyanja (Chichewa) | Odia (Oriya) | Pashto | Persian | | Polish | Portuguese | Punjabi | Romanian | | Russian | Samoan | Scots Gaelic | Serbian | | Sesotho | Shona | Sindhi | Sinhala (Sinhalese) | | Slovak | Slovenian | Somali | Spanish | | Sundanese | Swahili | Swedish | Tajik | | Tamil | Telugu | Thai | Turkish | | Ukrainian | Urdu | Uyghur | Uzbek | | Vietnamese | Welsh | Xhosa | Yiddish | | Yoruba | Zulu | | | ## Is translation supported? Yes, translation between English and the languages listed above is also well-supported, with performance considered state-of-the-art.2 ## Can Kolena transcribe audio? Yes, all supported languages listed above are also supported during audio transcription.3 *** 1 Supported with at least 90% accuracy according to language benchmarks, relative to performance using English. 2 Performance for a tested subset of these languages was found to be state-of-the-art when compared against other available AI solutions (as of August 2025). 3 Audio transcription accuracy varies by language, with high accuracy (≤10% [WER](https://en.wikipedia.org/wiki/Word_error_rate)) for primarily widely spoken and well-resourced languages like English, Spanish, French, German and Japanese; good accuracy (10–25% [WER](https://en.wikipedia.org/wiki/Word_error_rate)) for languages such as Arabic, Hindi, Korean, and Vietnamese. # Usage Source: https://docs.agents.kolena.com/faq/usage ## What is a Credit? A **credit** is the unit of usage in Kolena. Credits are consumed whenever an Agent executes a Prompt. See more details on how credits are consumed, managed, and tracked in [Tracking Usage](/tracking-usage). The amount of credit used by a Prompt depends on several factors, including the complexity of the task, the number and type of files processed, and the length of the output generated. As a rule of thumb: * Complex tasks, larger input files, and lengthier outputs will consume **more credits** * Simple tasks, smaller input files, and shorter outputs will consume **fewer credits** Credits are similar to getting a quote to off-shore or out-source a task: the more complex the task and the greater volume of data, the higher the cost. For users familiar with the concept of "tokens" in large language models, credits can be thought of as a bundle of tokens encompassing the various operations performed by Kolena Agents, including input analysis, reasoning, and creating output. ### Credit Usage By Common Use Cases Here are some common use cases and their typical credit consumption per Run: | Use Case | Credits per Run | | - | - | | Lease Abstraction | 1 - 3 Credits per Property | | Loss Run Analysis | 3 - 4 Credits per Loss Run | | Compliance Testing | 0.5 - 1 Credit per Account Statement | ## How to Optimize Credit Usage? Credit usage depends primarly on * The size of your input files into an Agent * The length of the output from an Agent * The number and complexity of Prompts being executed Below are tips to optimize credit usage. #### Avoid Sending Unnecessary Files Uploading only files which are relevant to your task will both improve the quality of your results and lower credit usage. When possible, avoid sending files which you know beforehand will be irrelevant to the task at hand. #### Group together Prompts When extracting "simple" values from documents, you can often use [Form Prompts](/prompts#form) to group multiple "key value" pairs of data. Prefer to use one Form Prompt instead of many Number or Text Prompts. #### Use Appropriate Advanced Tools Some advanced [settings and tools](/prompts#tools) impact credits usage. Use appropriate settings when you expect they will materially impact performance. For example: * Enhanced vision will consume additional credits. Make use of this feature when checkbox states are important and expected to be present. * If you have a chained Prompt which only needs to analyze the output of other Prompts (not the source files), use [Ignore Run files](/prompts#ignore-run-files). ## Legacy Plans: Page-Based Usage Some existing customers are on page-based pricing plans. Kolena will continue to support these plans, but new customers will be on the new user-based pricing plans described above. Under page-based pricing plans, usage for your Organization is tracked from the number of pages uploaded. Your Organization's plan comes with a number of new page uploads allowed each month. See [Tracking Usage](/tracking-usage#legacy-plans%3A-page-based-usage) for details. # Agent-Level Access Control Source: https://docs.agents.kolena.com/fine-grained-access-control Control Agent Level Access on Kolena This is available on the Enterprise Plan. [Contact Kolena](mailto:support@kolena.com) if you’re not on an Enterprise plan but would like to try this feature. Access can be controlled at the Agent level. This allows restricting access to specific Agents at a granular level, allowing specific Users or Teams `viewer` or `editor` access. ## Manage Agent Access Starting from the main page for an Agent, the `owner`s of the Agent or Workspace `admin`s can manage access by clicking the "eye" icon near the top of the page. There are two access controls on an Agent. Under **"Users With Access"**, you can explicitly add Users and Teams as `viewer`, `editor`, or assign someone as the Agent’s owner. You can also configure the **"General Access"** setting: * **General (View-Only)**: All Workspace users have `viewer`-only access. * **General (Viewer/Editor)**: Workspace `viewer`s and `editor`s receive their respective roles. This is the default setting for new Agents. * **Restricted**: Only Organization and Workspace `admins` and explicitly added Users/Teams can access the Agent. ## Agent-Level Permissions Users with access to an Agent are assigned one of three roles: `viewer`, `editor`, or `owner`: | Action | `viewer` | `editor` | `owner` | | :- | :-: | :-: | :-: | | View Agent | ✅ | ✅ | ✅ | | View Integrations | ✅ | ✅ | ✅ | | View Dashboards | ✅ | ✅ | ✅ | | View Runs | ✅ | ✅ | ✅ | | Create Runs | ✅ | ✅ | ✅ | | Comment on Prompts results | ✅ | ✅ | ✅ | | Override Prompts results | ✅ | ✅ | ✅ | | Create/Modify/Delete Data Retention Policies | ❌ | ✅ | ✅ | | Create/Modify/Delete Prompts | ❌ | ✅ | ✅ | | Create/Modify/Delete Integrations | ❌ | ✅ | ✅ | | Create/Modify/Delete Dashboards | ❌ | ✅ | ✅ | | Delete Agents | ❌ | ✅ | ✅ | | Manage Agents permissions | ❌ | ❌ | ✅ | By default, the User who created the Agent is its `owner`, though ownership can be transferred later. Note that Workspace `admin` Users have `owner` access to all Agents in the Workspace. Moving an Agent between folders is governed by the Workspace-level `Manage Folder` permission. It also requires view access to the Agent, so Users reorganize only the Agents they can see. # Get Access Source: https://docs.agents.kolena.com/get-access Create an Account on Kolena ## Requesting Access If your Organization is not yet a Kolena customer, you can request access to Kolena by [following this link](https://www.kolena.com/request-access/). Kolena will create a new Organization and an administrator account. You will receive an email with a link to verify your email address and join the Organization. ## Accepting An Invitation If you received an invitation email from Kolena, accept by clicking "Join Kolena". This will take you to Kolena. On Kolena, click "Join ..." to accept the invitation. This will take you to a page to [create your account](#creating-an-account). ### What If I Did Not Receive an Invitation? Invitation emails may be filtered by your Organization's email security settings. If you did not receive an invitation email, please check your spam folder or contact your Kolena representative. If you have been invited to join an Organization but did not receive an invite email, you can still create an account by going directly to [agents.kolena.com](https://agents.kolena.com) and following the steps below. ## Creating an Account You can create an account by using your email address, Google account, or Microsoft Account. To create an account with your email address, enter your address and click "Continue". Next, create a password for your account and click "Create Account". You will receive a verification email in your inbox. Open this email and click "Confirm my account". Click "Accept" on the authorization page and you will be redirected to Kolena. ## Resetting Your Password If you forget your password or want to reset it, you can do so by logging out and returning to the [Kolena login page](https://agents.kolena.com). Click "Log in" and enter your email address. Next, click "Forgot password?". You will receive an email with a link to reset your password. # Measuring Accuracy Source: https://docs.agents.kolena.com/how-to/measuring-accuracy Use Agent Validation to Compare Agent Output Against Known Answers Contact Kolena to enable this feature for your Organization. **Agent Validation** lets you compare your Agent's output to known correct answers (**Ground Truths**). Kolena will score how well the Agent matches these Ground Truths. This allows you to: * Estimate the **overall accuracy** of the Agent at a given task * Perform **change management** by testing accuracy before and after changes to your Prompts ## Overview Validation has three steps: 1. Create a Ground Truth for your Agent 2. Perform Validation (evaluation between Ground Truth and Agent output) 3. Review results of the Validation ## Prerequisites To perform validation on an Agent, you must ensure: * The Agent has Prompts created * Runs are uploaded to the Agent using inputs for which you have known correct outputs For example, if you wish to validate a Lease Abstraction Agent: * Upload the lease documents you wish to abstract into Runs * Define all Prompts necessary to perform the abstraction * Ensure you have known answers to compare against for those input documents ## Creating a Ground Truth Using the UI, navigate to the "Validation" tab for your Agent. Click "Create New Ground Truth". Provide a Name for your Ground Truth and click "Continue". ### Associate Ground Truth to Runs In order to compare Agent outputs to Ground Truths, you need a way to associate the two. Kolena uses a label on each Run called `user_defined_id` to achieve this. Both your ground truths and the Agent Runs must use this label to join the two. Click "Bulk Label Runs" and provide natural language instructions on how to assign this label to each Run on your Agent. Kolena will take your instruction and define the label for each Run. You can check progress and then continue when complete. For example, if you have a Loan Review Agent, use an identifier like the loan ID as the label. Assign labels to each run using instructions like "Grab the loan ID from the cover sheet". ### Upload Ground Truth Upload a single file containing your correct answers. Kolena checks whether it already matches the expected [schema](#ground-truth-schema): * **If it matches exactly**, the file is saved directly as your Ground Truth. * **Otherwise**, Kolena converts it for you, mapping your data to the correct Prompt names and generating the Ground Truth JSON. You can optionally add instructions to guide the conversion (for example, how to associate ground truth data to particular runs). Supported file types are `.xlsx`, `.xls`, `.xlsm`, `.csv`, `.json`, and `.txt`. #### Ground Truth Schema The expected schema is below. A file that already matches this structure is uploaded directly; anything else is converted into it. ```json theme={null} { "evaluation_instructions": "Values should match exactly.", "runs": [ { "user_defined_id": "lease-001", "data": { "tenant_name": "Acme Corp", "lease_start_date": "01/15/2024", "monthly_rent": 4500 } }, { "user_defined_id": "lease-002", "data": { "tenant_name": "Globex LLC", "lease_start_date": "03/01/2024", "monthly_rent": 6200 } } ] } ``` **Fields:** * `evaluation_instructions` — Natural language guidance for how Kolena should compare outputs to ground truths. Useful for specifying acceptable formats, equivalences (e.g. "\$4,500" vs `4500`), or what counts as a correct partial match. * `runs` — A list of expected results, one per Agent Run. * `user_defined_id` — A stable identifier that matches the ground truth to a Run in the Agent. * `data` — A map from Prompt name to expected value. ## Run a Validation 1. Open a Ground Truth from the **Validation** tab. 2. Click **Run Validation**. 3. Results stream in real-time as each cell is evaluated. When complete, you'll see: * An **overall Score** (0–100) for the Agent, with its matched, mismatched and skipped field counts * A **breakdown by field**, ranked worst-first, so the weakest fields surface immediately * **Per-Prompt** and **per-Run scores** showing where the errors concentrate * **Cell-level reasoning** explaining why a value was marked incorrect ## Editing Ground Truth You can update individual expected values without re-uploading the entire file: 1. Open a Validation and click on a cell. 2. Click "Edit Ground Truth" and Edit the expected value in the side pane. 3. Click **Save**. Kolena creates a new version of the Ground Truth, preserving history. ## How Scoring Works Outputs that match Ground Truth exactly are matched immediately and skip evaluation. For the rest, an AI coding agent inspects your data and writes and runs a script to compare outputs **field-by-field**, producing deterministic match / no-match results. Your `evaluation_instructions` guide this script, including how to normalize formats and how to align table rows. A natural-language second pass runs only on the mismatches for fields you *explicitly* ask to compare by meaning (see [When the second pass runs](#when-the-second-pass-runs)). Field-level results roll up into per-cell, per-Prompt, per-Run, and overall Scores (0–100). ### How the Score is calculated The Score is the share of compared fields that match: ``` Score = matched fields / (matched fields + mismatched fields) x 100 ``` Fields that your Evaluation Instructions exclude are **skipped**: they count towards neither side, so excluding a field never helps or hurts the Score. A Validation where every field is skipped has no Score at all. Every field carries the same weight, whichever Prompt it belongs to. A Prompt extracting twenty fields therefore moves the Score ten times as much as one extracting two — the Score tracks how much of your data is right, not how many Prompts are doing well. Watch the per-Prompt scores alongside it to see whether one Prompt is responsible for most of the errors. The `score` returned by the API on a completed Validation is this same number. ```mermaid theme={null} flowchart TD A[Agent outputs + Ground Truth] --> B{Matches
exactly?} B -->|Yes| M[✓ Match] B -->|No| C[Coding agent writes & runs a script:
aligns table rows, normalizes formats
per evaluation_instructions] C --> D{Field result?} D -->|Excluded by
instructions| S[— Skipped ] D -->|Match| K[✓ Match] D -->|Mismatch| E{Field flagged for
semantic comparison?} E -->|No| F[✗ Mismatch] E -->|Yes| G{Same meaning?} G -->|Yes| H[✓ Match] G -->|No| I[✗ Mismatch] M --> Z[Aggregate scores] K --> Z F --> Z H --> Z I --> Z S -.excluded.-> Z ``` #### When the second pass runs The natural-language second pass is **not** automatic. It only re-judges mismatches on fields you explicitly ask to be compared by meaning — using language like "semantically", "same meaning", or "paraphrase" in your `evaluation_instructions`. Everything else (date, currency, number, and boolean equivalence, synonym lists, casing, whitespace) is handled deterministically by the script. If you never request semantic comparison, a script mismatch stays a mismatch. ### Custom instructions By default comparison is as literal as possible. **Evaluation Instructions** can be set to customize comparison logic. Use these to tell Kolena how to handle acceptable variations — for example, equivalent date formats, optional whitespace, or acceptable abbreviations. This prevents the evaluator from penalizing correct-but-differently-formatted outputs. **Evaluation Instructions** can be used to provide custom logic per Prompt or to ignore differences in specific outputs. For example, > When comparing percentages, convert to numeric and match to 2 decimal places (treat "50%" and 50 as equal) > > When comparing currency, convert to numeric and treat equal to the nearest dollar ("\$1,000" == 1000) > > When comparing dates/datetimes, treat as equal if equivalent to the nearest hour > (2025-01-08 02:45PM == 2025-01-08 14:45:00) > > When comparing addresses, ignore casing and abbreviations ("123 Main St" == "123 Main Street") > > Treat null and None as equal; treat a null ground truth and a false output as equivalent > > When comparing the "Summary" field, treat as correct if it conveys the same meaning # triggers the second pass > > Skip any "Comments" prompts in the comparison Most rules are applied deterministically by the script. Only rules that ask for meaning-based comparison trigger the natural-language [second pass](#when-the-second-pass-runs): ## Using the API Validation can also be performed programmatically using [Kolena's API](/api-reference/ground-truths/create-ground-truth). # Introduction Source: https://docs.agents.kolena.com/introduction Automate Document-Heavy Workflows with AI **Kolena** is a platform for creating and running automations powered by state of the art AI. We call these automations **AI Agents**. Agents are capable of understanding complicated [documents, images, audio recordings and more](/faq/supported-formats). Tasks which are well suited for Agents include: * abstracting legal agreements with amendments like leases * performing extensive diligence reviews of large documents * eliminating data entry into financial models * drafting documents from templates and more. AI Agents are a collection of **Prompts**, which are instructions that guide the AI on how to process and analyze your data. Kolena provides tools to write effective prompts as well as a library of pre-built prompts for common use cases and a means to evaluate their performance. Agents can be connected to your existing data using our supported [Integrations](/connections) with popular cloud storage, document management platforms, and email. In addition, Kolena supports a [public API](/connecting-to-kolena) to interact with Agents programmatically. # IP Whitelists Source: https://docs.agents.kolena.com/ip-whitelist Configure Allow List by IP Address or CIDR Range IP whitelisting allows your Organization to restrict access to the Kolena so that only traffic originating from approved IP addresses or networks is permitted. This is useful for enforcing security policies, limiting access to corporate networks, or complying with regulatory requirements. ## How to Configure an IP Whitelist To configure or update the IP whitelist for your organization: 1. Navigate to "Data & Security" tab on [your Organization page](https://agents.kolena.com/organization?tab=data-and-security). 2. Under **IP Whitelist**, click **Configure Whitelist**. 3. In the **IP Addresses** field, enter one or more IP addresses or CIDR ranges. * Examples: * `192.0.2.1` * `192.168.0.0/24` * Multiple entries can be separated by commas. 4. Click **Set IP Whitelist** to apply the policy. Your organization’s access will now be restricted to the addresses or ranges you specify. ## Important Notes * **Be careful not to lock out your Organization.** Ensure that the IP you are currently using is included in the whitelist before saving. * Changes take effect immediately. * Removing all entries will revert the organization back to allowing access from any IP address. # Leonard Source: https://docs.agents.kolena.com/leonard Work with Kolena's built-in AI assistant to build, explain, and improve your Agents Leonard is Kolena's AI assistant, built into the platform. He works alongside you in a side panel: he can read the Agents in your Workspace, explain what a Prompt did, propose edits for you to review, build new Agents, and answer how-to questions with links to this documentation. This feature is in beta and is enabled per Organization. [Contact Kolena](mailto:support@kolena.com) if you'd like it turned on for your Organization. ## Opening Leonard Click **Work with Leonard** at the bottom of the sidebar, or press `Ctrl+Shift+L` (`⌘⇧L` on Mac). The panel opens beside your work, so the Agent, Run, or Prompt you were looking at stays visible. Leonard knows which page you have open, so you can refer to what's in front of you (for example: "why did this Prompt return null?", "add a Prompt here for the lease end date", "how many credits did this Run cost?") without pasting ids or instructions into the chat. ## Examples
## What Leonard can do * **Build Agents:** Describe the outcome; Leonard creates the Agent and proposes its Prompts. * **Explain and improve Prompts:** Review an instruction, add a missing field, or fix a Prompt returning the wrong value. Edits are surgical. He can also edit **Agent Guidelines**. * **Connect Prompts and narrow documents:** [Chain Prompts](/prompts#prompt-inputs-chaining) so one reads another's output, set [Document Filters](/prompts#document-filters) so a Prompt only sees the documents that matter, and add [Conditionals](/prompts#conditionals) so a Prompt only runs when it applies. * **Explain results:** He reads a Run's results and its source documents. Verify an extracted value, compare two files, or find something no Prompt captures. * **Search your Workspace:** Ask which Agents exist, where one lives, or which Runs it has. * **Answer how-to questions:** He searches this documentation and links the page he used. * **Report credit usage:** Workspace, Organization, per-Agent, or per-Run (limited to usage you can view). * **Create files to download:** `.xlsx`, `.docx`, `.pptx`, or `.pdf`, attached to the conversation. * **Start a Validation:** Against an Agent's [Ground Truth](/how-to/measuring-accuracy), after you confirm. ## Nothing changes until you accept Leonard never edits an existing Agent directly. Every change arrives as a **Proposed Changes** card in the conversation, listing each Prompt being added, modified, or removed. * Click any item to open the full diff and see the instruction and settings before and after. * **Generate a preview** to run the proposed Prompt against a real Run and see the value it produces, side by side with the current value, before you commit to it. * **Accept all** applies the update; **Reject all** discards it. If part of an update isn't right, tell Leonard what to change and he'll propose a revised version. Leonard can create a **new, empty** Agent when you ask him to build one but all Prompts still arrive as a proposal for you to review. Accepting a Prompt change marks existing results for that Prompt out of date. Regenerate them from the Agent when you're ready — Leonard cannot create Runs or re-run existing ones. ## Attachments and dictation Attach files to a message when a screenshot or sample document is the fastest way to explain what you want: up to 10 files per message, 10 MB per file and 20 MB in total. Leonard keeps them for the whole conversation, so you can refer back to a file you attached earlier without uploading it again. You can also dictate a message with the microphone in the chat input instead of typing it. ## Chats and history Each conversation is saved. Use the history menu to search and reopen past chats, or delete ones you no longer need; **New chat** starts fresh. Long conversations are summarized automatically as they grow, so Leonard keeps track of what you're working on. Very long chats eventually reach a limit and ask you to start a new one — start a new chat per task for the best results. A thumbs up or down on any response (with an optional comment) tells us what to improve. ## What Leonard can't do * Change an existing Agent without your approval. * Create Runs, upload documents to a Run, or re-run an existing Run. * See anything you can't see. Leonard runs with your permissions in your current Workspace. ## Permissions and privacy Leonard enforces exactly the same access rules as the rest of the platform. He can only read Agents you have access to, can only propose Prompt changes on Agents you may edit, and can only start a Validation if your role allows it — including under [fine-grained access control](/fine-grained-access-control). Conversations with Leonard are **not billed** and do not consume your credits. As with the rest of the platform, your data and your interactions are never used to train AI models — see [Data Privacy & Security](/faq/security). ## Tips for better results * **Work from the page you're on.** Open the Agent, Run, or Prompt first, then ask — Leonard resolves "this Prompt" or "this Run" from what you're viewing. * **Say what's wrong, not just what to write.** "This returns the tenant's name instead of the landlord's" gets a better edit than "rewrite this Prompt". * **Point at a Run when accuracy is the problem.** Leonard can read the source documents and see what the Prompt actually had to work with. * **Batch related edits.** Ask for all the changes you want in one message and review them as a single update. * **Preview before accepting** anything you're unsure about. * **Start a new chat** when you switch tasks. # Add Styling to Your Prompt Source: https://docs.agents.kolena.com/llm-styling-tutorial Learn how to prompt AI to generate structured, styled reports When you ask AI to create a report, presentation, or summary, you don't have to settle for plain, boring text. With the right instructions, you can get beautifully formatted documents that look professional and are easy to read. Think of it like instructing a junior employee; the more specific you are about what you want, the better your results will be. Here's a step-by-step guide to help you design effective prompts for generating reports with headers, bullet points, and other formatting elements. ### Step 1: Specify the Report Structure Define the structure of your report. For example, you might want the output to include headings, subheadings, bullet points, and tables. Example Prompt: > Generate a report summarizing the results of a customer survey. The report should include the following sections:
> > 1\. Executive Summary
> 2\. Key Findings
> 3\. Recommendations
> 4\. Detailed Analysis Consider the desired style of your output and include instructions which reflect that style. Here are some examples for different report stuctures and styles: | Style | Description | Sample Prompt Addition | | - | - | - | | **Executive Dashboard** | High-level KPIs, insights, actions | “Create a dashboard-style summary with KPIs, key findings…” | | **Slide-Style Report** | Each section = one slide (for Google Slides / PowerPoint) | “Format each section like a slide with a title + 3 bullets…” | | **Analyst Bullet Report** | Dense bullets, bolded labels, zero fluff | “Use a clean bullet-point format with bolded highlights…” | | **Comparison Table** | Compare multiple products or groups side-by-side | “Include comparison tables and insights per group…” | | **Q\&A Format** | Conversational, like an interview | “Write the summary as a Q\&A between researcher and analyst…” | | **Timeline Report** | Chronological milestones, testing phases, or journeys | “Summarize events in a timeline-style with emojis…” | | **Storytelling Format** | Narrative arc for presentations or internal buy-in | “Write as a story with sections: Background, Discovery, etc.” | *** ### Step 2: Set the Tone and Style Be specific about the style you want, such as professional, concise, or detailed. For best requests, request the output to be formatted as Markdown. Example Prompt: > Format the report in Markdown. Use \*\*bold\*\* for section headers, bullet points for findings, and italics for recommendations. Include a table for the detailed analysis section. *** ### Step 3: Include Clear Instructions on Formatting For each section, specify how the content should be structured. You may ask the AI to use bullet points, tables, or numbered lists. Example Prompt: > \- In the Executive Summary section, summarize the main findings in 3-4 sentences.
> \- In the Key Findings section, list the findings as bullet points.
> \- In the Detailed Analysis section, provide detailed descriptions in paragraphs. *** ### Step 4: Provide Sample Prompts for Clarity Here's a complete prompt example that follows these steps. Example Prompt: > Generate a report summarizing the survey results. The report should have the following sections: > > \# Executive Summary
> \- Provide a brief summary of the main findings in 3-4 sentences. > > \# Key Findings
> \- List the key findings using bullet points. Use bullet points for each finding.
> > \# Recommendations
> \- Provide a list of recommendations based on the findings, formatted as bullet points.
> \- Make sure to write recommendations in \*\*bold\*\*. > > \# Detailed Analysis
> \- For each question in the survey, include a detailed analysis. Write paragraphs explaining the results and what they imply.
> \- If a table is needed for data, include it with the column names: "Question", "Response", and "Percentage". Example Output: > # Executive Summary > > This report provides an overview of the recent customer survey results, highlighting key insights and actionable recommendations. > > # Key Findings > > 80% of customers are satisfied with our product. > > 15% of customers noted issues with the website's navigation. > > 5% of respondents have never used the product. > > # Recommendations > > Enhance website navigation to improve the user experience. > > Focus on customer engagement for the 5% who haven't used the product. > > # Detailed Analysis > > Question 1: How satisfied are you with the product? > 80% of respondents reported being satisfied with the product. This is a positive outcome, but there is still room for improvement to achieve even higher satisfaction levels. > > Question 2: What issues have you faced with the product? > 15% mentioned issues with navigation. This suggests that the interface might be complex for some users. We recommend a review of the UI/UX. > > | Question | Response | Percentage | > | - | - | - | > | How satisfied are you with the product? | Satisfied | 80% | > | What issues have you faced with the product? | Navigation | 15% | > | Have you used the product? | No | 5% | ### Conclusion By clearly structuring your prompt and specifying how you want the content formatted, you can easily generate detailed and professional reports. *** ## Advanced: Markdown Cheatsheet Markdown is a format which is well understood by AI and can be used to create structured, styled reports. When asking for Markdown formatting, you can use specific keywords to get the desired output. Here's a quick reference: | Element | Prompt Keyword | Example Output | | - | - | - | | Headings | `## Executive Summary` | ## Executive Summary | | Bold Text | `**Key Insight:**` | **Key Insight:** | | Bullet List | `- Item 1` | – Item 1 | | Numbered List | `1. First` | 1. First | | Tables | Ask for: “Markdown table” | Structured rows + columns | # Prompts Source: https://docs.agents.kolena.com/prompts Learn about Prompts, the building blocks of AI Agents in Kolena Prompts are instructions that guide your AI Agent on how to process and analyze your data. This page will explain the basics of Prompts including defining **output types**, **attaching files**, and advanced usage like **chaining Prompts** together and performing complex math. ## Output Types Each Prompt has an output type. This type specifies the format of the response you expect. When creating a Prompt, Kolena will intelligently guess the output type based on your instructions, but you can also select the desired output type from the dropdown menu. Click to expand each output type for more details: **Text Prompts** are the most flexible output type. They allow the Agent to generate free-form text responses based on the Prompt instructions. Text output can also be formatted using Markdown syntax. This is useful for creating structured documents with headings, lists, links, and other formatting elements. **Table Prompts** enable structured data representation. It is useful for extracting and organizing information in a tabular format. When Table is selected, you must define the columns that the Agent should fill in. Accuracy will be highest when your Prompt includes clear instructions on what data should go into each column as well as instructions for when to create a row. You can use Table Prompts to directly extract tabular data from documents, such as a rent roll from a PDF, or to organize unstructured information into a table, such as gathering a list of all critical dates within a legal document. The number of rows returned by the Agent will depend on the content of the input document and your Prompt instructions. Accuracy of Table Prompts will decrease with very large (20+) numbers of columns or when each row requires many paragraphs of text to be extracted. **Recommendation**: if the number of columns becomes too large, split your instruction into multiple Prompts. **Form Prompts** return a set of predefined field/value pairs. Each field in the Form corresponds to a specific piece of information that the Agent is expected to extract or infer. When Form is selected, you must define the field that the Agent should fill in. Accuracy will be highest when your Prompt includes clear instructions on what data should go into each field. Form Prompts are very efficient because they allow you to group multiple outputs into a single Prompt. You can use Form prompts to extract many different pieces of information such as key details from a contract (e.g., parties involved, dates, amounts) by section. Accuracy of Form Prompts will decrease with large (20+) numbers of fields. **Recommendation**: if the number of fields becomes too large, split your instruction into multiple Prompts. **Number Prompts** should be used when the expected response is a single numeric value. **True/False (Boolean) Prompts** should be used when the expected response is a true or false answer. **Classification Prompts** are a special form of Text Prompt where the Agent is required to choose from a predefined set of categories. This is useful for tasks like sentiment analysis, topic categorization, or any scenario where the response must belong to a specific set of options. ## Inputs to Your Prompts In addition to the text instructions, you can provide additional information to your Prompts using file attachments or even the results of other Prompts. ### Attaching Files Attaching a file to your Prompt allows to provide longer context that may be impractical to include directly in the Prompt instructions. You can attach files of various types including PDFs, images, spreadsheets, and more. Some examples of useful attachments include: * CSVs of lookup tables or reference data * Guidelines or policy documents you want the Agent to follow When attaching files, consider the following **best practices**: * Ensure the attached files are relevant to the Prompt and contain information that will help the Agent generate accurate responses. * If the file is large or complex, provide additional instructions in the Prompt to guide the Agent on which sections to focus on. * Use clear and concise language in your Prompt to specify how the Agent should utilize the information from the attached files. #### Connecting Cloud Documents If you wish to attach a document stored in a cloud service, you can do so by first adding an integration for that service (see [Supported Integrations](/connections/supported)), then clicking that integration from the Prompt and selecting the file. Supported integrations include: * Google Drive * Notion (KMS) * SharePoint ### Prompt Inputs (Chaining) Sometimes a task is too complex to be handled reliably by a single Prompt. Kolena allows you to define and chain multiple Prompts together, where the output of one Prompt can serve as the input to another. This can be used in combination with other tools, for example: 1. Use a Table Prompt to extract structured data from a document. 2. Use a Data Analysis tool-enabled Prompt to perform calculations or analysis on the extracted data. To use another Prompt as the input to your current Prompt, simply select it from the **Prompt Inputs** dropdown item or use the hotkey `@` when editing the Prompt text. ## Tools Advanced tools can be enabled on your Prompts to enhance their capabilities. Each tool is designed to overcome a natural limitation of state of the art AI models by leveraging specialized techniques or services. ### Data Analysis Certain operations, such as mathematical calculations are best handled by specialized tools rather than relying solely on AI models' pattern matching capabilities. Selecting **Data Analysis** for your Prompt will have the Agent write a piece of code which is then executed to produce the final output. This is especially powerful for tasks involving numerical data or complex calculations on tabular data. **When You Should Use Data Analysis:** * When you want to perform calculations, aggregations, or statistical analysis on data extracted from tabular data. **How Data Analysis Works:** 1. The Agent will analyze any input document(s) and your Prompt and write a piece of code. 2. This code will be executed and the results returned as the final output of the Prompt. **When Data Analysis Is Not Suitable:** * When you require natural language analysis. **Recommendation**: perform the task using two Prompts chained together, the first to extract the data and the second to analyze it using natural language. If computation logic is complex, and you already have the code implemented in Python, you can provide the script as a [Prompt attachment](#attaching-files), and add instructions in your Prompt to guide the Agent to use it. For example, putting the desired processing logic in `transaction_processing.py`: ```python theme={null} import pandas as pd def process(history): df = pd.DataFrame(history) # perform data processing based on input df output_df = pd.DataFrame(columns=['Date', 'Amount', 'Interests']) # ... return output_df ``` We can create a Prompt with the above code as a Prompt attachment, and automatically instruct the Agent: > Use the `process` function in `transaction_processing.py`, pass all transaction history in the document as > `history` argument. Return the result as a table. This can provide strong guidance for the Agent to run the exact computation. ### Enhanced Vision State of the art AI models excel in many vision tasks. However, for a specific subset of tasks, such as accurately reading checkbox states from documents, specialized vision models will provide superior accuracy. **When You Should Use Enhanced Vision:** * Prompts which require correctly reading checkbox states **How Enhanced Vision Works:** 1. The Agent will identify the regions of interest in the document or image based on your Prompt instructions. 2. These regions are then processed using specialized vision models to extract the required information. **When Enhanced Vision Is Not Suitable:** * When checkboxes exist on many pages for extraction (5+ pages) ### Web Search Web Search allows your Agents to find information from the internet to answer questions with verified references. **When You Should Use Web Search:** * When your Prompt requires current information from the web or verification of facts. * When the information needed is likely to be found on publicly accessible web pages through a search engine. **How Web Search Works:** 1. Based on your Prompt, the Agent will decide if searching the internet is necessary. 2. If so, the Agent will make search engine queries to gather information and refine searches for up to 10 of the most relevant web pages. 3. The Agent will extract at most 120k words and analyze the content to answer your Prompt. 4. The final response will use any documents plus these search results to generate a comprehensive answer with citations. **When Web Search Is Not Suitable:** * Web Search cannot access private or paywalled content, nor can it download files like PDFs or images. * Web Search relies on search engine results and cannot access pages that block bots or crawlers. **Effective Web Search Prompts** Craft your Prompts to steer the Agent's search for information by: * Asking for current information (e.g., "What are the latest developments at Kolena in 2025?" instead of "What's Kolena doing?") * Using time-sensitive language like "latest," "in the past decade," "breaking news," or specific time periods. * Requesting verification and fact-checking (e.g., "Verify the current stock price of Company-Name and cite your sources.") * Hinting at specific sources or types of sources (e.g., "Search for information on Zillow about property prices in NYC" or "Find recent news articles about Topic-Name") ## Advanced Settings ### Inline Citations Embed file and page references directly within the output text, showing which sources were used for each part of the response. **Use this when:** You need to trace the source of specific information or when compliance requires detailed source attribution. Inline Citations are only available for **Text**, **Table**, and **Form** output types. Inline Citations are enabled by default. ### Ignore Run Files By default, when a Prompt with Input Prompts executes, two sources of information are used as input: 1. The files uploaded to the Run 2. The results of any Input Prompts When enabled, only the second source will be used as input for the Prompt. **Use this when:** You are chaining Prompts together in a multi-step workflow, and the initial Run files are no longer relevant to later steps. This helps ensure that later Prompts operate strictly on transformed or refined intermediate outputs, rather than being influenced by the original files. Suppose your goal is to produce a final summarized report based purely on the results of earlier transformation Prompts rather than the original uploaded materials. Here is an example flow: > **Prompt A:** Extracts structured data from the uploaded files into a normalized format. > > **Prompt B:** Final summarization step. If Prompt B still has access to the original Run files, the model may accidentally pull details directly from those files instead of relying solely on the refined output from Prompt A. To avoid this, you would enable Ignore Run Files on Prompt B. This ensures the final summary is based only on the transformed, cleaned, or reduced information produced by the previous Prompts. This option is only available when **Input Prompts** are used. ### Filter Documents (deprecated) **Deprecated:** This feature is deprecated and may be removed in a future release. Avoid using it in new Agents. The recommended way to filter documents is now a dedicated [**Document Filter**](#document-filters) step, which you define once and connect to any number of Prompts. When enabled, the system automatically selects only the relevant documents for your Prompt. This can improve extraction quality and reduce noise when a Run includes many files. **Use this when:** There are many Run files, but only a few contain what you need. You want to exclude irrelevant files without manually selecting documents for every Run. For best results, be explicit about which documents should be included (and, if helpful, which should be excluded). Mention the document type or identifying cues like filenames or keywords. Here is an example: > Only use invoices from 2026. Ignore receipts, statements, email threads, and invoices from other years. This is only applied to Runs with more than 10 files or multiple files with more than 200 total pages. This feature is unavailable when [**Ignore Run Files**](#ignore-run-files) is enabled. ## Control Steps Beyond the Prompts themselves, you can add steps to your Agent that control what runs. ### Document Filters A **Document Filter** is a dedicated step you add to your Agent that narrows down which documents your Prompts will see. It is the recommended way to control document selection: you define a filter once, write instructions describing which documents to include, and connect it to the Prompts that should receive only those documents. Connecting a Document Filter to your Prompts optimizes both **extraction quality** and **credit usage**, since each connected Prompt only processes the documents that pass the filter rather than every file in the Run. **When You Should Use a Document Filter:** * When a Run includes many files but only some are relevant to a given Prompt. * When several Prompts should all operate on the same relevant subset of documents. * When you want to reduce credits by preventing Prompts from processing irrelevant files. **How Document Filters Work:** 1. Add a Document Filter to your Agent and write instructions describing which documents to include. 2. In the filter's **Input** field, choose what the filter reads: **All Run Files** (the default) or [**All Run Filenames**](#all-run-filenames). 3. In the filter's **Output** field, select the Prompts that should receive the filtered documents. 4. When a Run executes, the filter analyzes the Run's documents and passes only the matching subset to each connected Prompt. 5. The filter's result is shown as the number of documents that passed out of the total (for example, `3 / 12 passed`). Be explicit about which documents should be included (and, if helpful, which should be excluded). Mention the document type or identifying cues like filenames or keywords. Here is an example: > Only include invoices from the current year. Exclude receipts, statements, email threads, and invoices from other years. #### All Run Filenames By default a Document Filter's **Input** is **All Run Files**, so it reads the contents of each file. Switch the Input to **All Run Filenames** to filter using only the filenames, without reading file contents. It is faster and uses fewer credits. This works best when filenames are consistent and descriptive. For example: > Include files whose names contain `Invoice`. Exclude files containing `Receipt` or `Statement`. If filenames are generic (`scan1.pdf`, `document.pdf`), keep the Input on **All Run Files** so the filter can read the contents. ### Conditionals A **Conditional** is a step you add to your Agent that decides which of your Prompts run for a given Run. It works much like a Classification Prompt. You define the set of **conditions** it can choose from (for example, `Invoice`, `Receipt`, `Other`) and write instructions describing how to choose between them. The difference is what the chosen condition does. When a Run executes, the Conditional picks the matching condition, and each Prompt you attached to that condition runs. Prompts attached to the other conditions are skipped. Like Document Filters, this improves both extraction quality and credit usage. Each Prompt only runs where it applies, and a skipped Prompt consumes no credits. **When You Should Use a Conditional:** * When your Runs contain mixed inputs, such as different document types, and different Prompts apply to each kind. * When a Prompt only applies in certain scenarios, such as when an optional section is present, or a review step that should only run when an earlier Prompt's check fails. **How Conditionals Work:** 1. Add a Conditional to your Agent and write instructions describing how to choose the matching condition (for example, "Categorize the files by which company they belong to: Company A, Company B, or another company"). 2. Define the **Conditions** the Conditional can choose from. 3. Attach Prompts to conditions, either from the Conditional itself (each condition has an "If ... then run ..." row) or from a Prompt's **Condition** field. Prompts left unattached always run. Like any Prompt, a Conditional reads the Run's documents, can use other Prompts' results as [inputs](#prompt-inputs-chaining), and can be connected to a [Document Filter](#document-filters). A Prompt can also carry conditions from more than one Conditional. These combine with OR, so the Prompt runs when any one of its conditions is met. If a Run doesn't clearly match any condition, the Conditional returns "No condition matched" and every attached Prompt is skipped. If you want certain Prompts to run in that case, add an explicit catch-all condition such as `Other` and attach them to it. Avoid repeating the decision inside your Prompt instructions. Instead of writing "If this is an invoice, extract X, otherwise return nothing" into several Prompts, create one Conditional that decides once and attach those Prompts to its `Invoice` condition. A skipped Prompt produces no output. If another Prompt uses a skipped Prompt as an input, it will see no value from it, so when a whole chain of Prompts belongs to one condition, attach every Prompt in the chain, not just the first. # Creating Many Prompts Source: https://docs.agents.kolena.com/prompts-from-file Learn how to create many Prompts at once by providing your desired output Kolena provides tools to create multiple Prompts very quickly. You can upload an example of the output you want to create and Kolena will construct Prompts to achieve this output. These Prompts can subsequently be edited and refined. ## Create Prompts From File The Create Prompts From File feature allows you to upload a reference file to guide the creation of many Prompts. For example, you can: * Upload an abstract template and ask to create Prompts necessary for filling in the template (for example a lease abstract) * Upload an example spreadsheet and ask to create Prompts necessary to populate a table of data ### Upload Your File 1. On your Agent, click on a Run to edit or create Prompts 2. Click on the "Create Prompt" button Uploaded files can be a maximum of 10MB. All [Office documents, text, pdf, and images are supported](/faq/supported-formats). 3. Attach your reference file 4. (Optional) Provide instructions on how to interpret the uploaded file, specify formatting requirements, or express preferences about the created Prompts. Some example instructions could include > Format all dates as "MM/DD/YYYY" > Generate a Prompt to populate the table found in the spreadsheet tab called "Master Template" > Write Prompts to populate the "Covenants" section of my Loan Abstract 5. Click "Send" Kolena will analyze the uploaded file along with any provided instructions and suggest appropriate Prompts. Once you’re satisfied with the suggested Prompts, you can save them by clicking "Create". **What happens behind the scenes:** * Kolena identifies useful fields to extract from your uploaded file * The documents in the run are treated as examples of the input the agent will process * Kolena suggests generic Prompts that work across multiple similar documents **Example:** If you upload a resume, Kolena will identify fields such as the candidate's name, contact information, experience, and skills, selecting the most suitable type (such as number, text, or table) for each Prompt. If you already have Prompts for experience or GPA, the system recognizes their existence and avoids creating duplicate Prompts. ### Best Practices * **Focused content**: Upload files that contain the right amount of information. If you have a complex file with multiple sections but only need to extract information from one specific area, consider uploading a screenshot or simplified version of only the relevant section. For instance, if you have an Excel file with 10 sheets but only need to extract data from one sheet, upload a screenshot of that sheet. This prevents having too many Prompts being generated. # Quickstart Guide Source: https://docs.agents.kolena.com/python-client/quickstart Call Agents from Python Follow our quickstart guide below or use an [interactive notebook](https://colab.research.google.com/github/kolenaIO/agents-notebooks/blob/main/quickstart.ipynb). ## Installation To connect to your Kolena Agents using Python, install the `kolena-agents` client from [PyPI](https://pypi.org/project/kolena-agents/) using any Python package manager such as [pip](https://pypi.org/project/pip/) or [poetry](https://python-poetry.org): ```shell theme={null} pip install kolena-agents ``` ```shell theme={null} poetry add kolena-agents ``` ## Initialization An [API Key](/api-keys) is required to use the python client. Create and copy a key, then store the value in a `KOLENA_API_KEY` environment variable: ```shell theme={null} 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: ```python theme={null} 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"]) # each entry may be a path, an open binary file object, bytes, or a (filename, bytes_or_file_object) tuple with open("path/to/large_file", "rb") as f: streamed_run = client.agent_run.add(agent_id=1, files=[f]) # 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](/api-reference/update-agent) for more details. ```python theme={null} # 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](/api-reference/add-agent-run-wait#rate-limits). ```python theme={null} # 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) ``` ### Download Templated Output When an Agent has an [Output Template](/templated-outputs) configured, Runs can be downloaded into the Template. ```py theme={null} agent = client.agent.get(agent_id=...) output_template_id = agent.output_templates[0].id # download Agent Run output as PDF client.agent_run.download_templated_output( agent_id=..., run_id=..., output_template_id=output_template_id, output_format="pdf", filename="output.pdf", ) ``` ### Query Access Logs This is available on the Enterprise Plan. [Contact Kolena](mailto:support@kolena.com) if you’re not on an Enterprise plan but would like to try this feature. ```py theme={null} 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) ``` ### View Credit History Pull credit history to get insights on usage. See the [API reference](/api-reference/list-usage-records) for more details. ```python theme={null} # list usage records usage = client.usage.list(page_size=50) # filter by date range import datetime now = datetime.datetime.now(datetime.timezone.utc) usage = client.usage.list( created_gte=now - datetime.timedelta(days=30), created_lte=now, ) # filter by agent or user usage = client.usage.list(agent_id=1) usage = client.usage.list(user="user@example.com") ``` ### Manage API Keys Programmatically manage API keys for automated rotation and monitoring. See the [API reference](/api-reference/create-api-key) reference for more details. ```python theme={null} from datetime import datetime, timezone new_key = client.api_key.create(name="New Key", expiration_days=10) print(f"New key: {new_key.api_key}") # save this immediately! # monitor keys for expiration utc_now = datetime.now(timezone.utc) response = client.api_key.list(page_number=0, page_size=50) for key in response.api_keys: if key.status == "active" and key.expires_at: days_until_expiry = (key.expires_at - utc_now).days if days_until_expiry < 30: print(f"Warning: {key.name} expires in {days_until_expiry} days") key = client.api_key.get(key_id=new_key.id) print(f"Key status: {key.status}") # delete an API key client.api_key.delete(key_id="old-key-id") ``` ### Serializing to JSON All `kolena-agents` objects are standard [`Pydantic`](https://docs.pydantic.dev/latest/) data objects and can be easily converted to and from JSON: ```python theme={null} 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 ``` ## Timeouts and Retries By default the client waits up to 10 minutes for a response, and retries failed requests up to 3 times with exponential backoff. Connection errors, dropped connections and transient HTTP statuses (`408`, `429`, `500`, `502`, `503`, `504`) are retried automatically for idempotent requests. Connections that cannot be established normally fail after 5 seconds so they are retried promptly rather than hanging. The timeout applies to each network operation rather than to the request as a whole, so a large upload that is still making progress will not time out. Streaming uploads use the operation timeout while connecting and sending so the shorter connection timeout cannot interrupt the request body. ```python theme={null} from kolena_agents import Client # wait up to 30 seconds for a response client = Client(timeout=30) # wait indefinitely client = Client(timeout=None) # override the timeout for a single call run = client.with_options(timeout=5).agent_run.get(agent_id=1, run_id=2) ``` [`add_wait`](#synchronous-usage) is the one exception: the server holds the connection open for the poll window you request, so the client never gives up before that deadline even if you set a shorter `timeout`. Requests that create or modify data, such as `agent_run.add`, are retried only when it is certain the server did not act on them: failures before the request reaches the server, and responses (`408`, `429`) where the server rejected the request without processing it. They are not retried if the connection drops after the request was sent, or on `500`/`502`/`503`/`504`, since the server may have already applied the request. ## Webhook Kolena provides a helper function to handle signature verification and parsing. See [Webhook Integration](/connections#webhook) for more information. ```python theme={null} 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. # Quickstart Source: https://docs.agents.kolena.com/quickstart Set Up Your first Agent in Minutes ## Quick Start Tutorial Welcome to your getting-started guide for Kolena's **Agents** tool. This tutorial walks you through the steps to build your first Agent. In this example, we will create one that focuses on analyzing customer interactions. If you'd like to follow along, the files used in the tutorial may be downloaded [here](https://kolena-public-datasets.s3.us-west-2.amazonaws.com/agents/docs/quickstart-customer-support-issues.zip).