Skip to main content
View as Markdown

Agent / LLM Integration Notes - Content Management

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.