---
title: Agent / LLM Integration Notes
url: https://docs.kaltura.com/docs/rich-media-cms-apis/content-management/esearch-agent-llm-integration-notes
---

## Agent / LLM Integration Notes


When exposing eSearch to an LLM via agent tools:

* **Accept nested JSON, flatten to bracket notation.** LLMs naturally generate nested JSON objects: `{"searchParams": {"searchOperator": {"objectType": "...", "searchItems": [...]}}}`. Auto-flatten to `searchParams[searchOperator][searchItems][0][objectType]=...` at the tool layer. Alternatively, send the JSON body directly with `Content-Type: application/json` — the API accepts both formats with identical results.

* **Split into simple + advanced tools.** Provide a simple `search(query, page_size, order_by)` tool for keyword searches (90% of requests) and an advanced `search(search_params)` tool for caption timestamps, date ranges, and complex logic. Both call the same underlying API.

* **Return the full API response including `itemsData`, `highlight`, and `aggregations`.** Downstream consumers rely on these fields for display and faceting: caption timestamps for clip playback, match context for summarization, faceted counts for dashboard queries.

* **Use concrete objectTypes for orderBy.** `KalturaESearchOrderByItem` is abstract and returns `OBJECT_TYPE_ABSTRACT`. Use `KalturaESearchEntryOrderByItem` for entry search, `KalturaESearchCategoryOrderByItem` for category search, `KalturaESearchUserOrderByItem` for user search, `KalturaESearchGroupOrderByItem` for group search.

* **Caption timestamps for clip playback.** When an LLM searches captions, the `itemsData[].items[]` array contains `KalturaESearchCaptionItemData` objects with `startsAt` and `endsAt` in milliseconds. Use these to seek a player to the exact moment a topic is discussed.

* **Aggregation double nesting.** The aggregations parameter path is `searchParams[aggregations][aggregations][0]` — easy for an LLM to get wrong. The simple tool should handle common aggregations (by media type, by category) without exposing this complexity.