Add agent_id field to analytics events and integrate usage across modules

- Introduced an optional `agent_id` field in `kb.query_executed` and `kb.content_indexed` analytics events to support per-agent KB usage metrics.
- Updated event payload generation in `tilellm/analytics/events.py` to handle `agent_id`.
- Integrated `agent_id` field propagation in `tilellm/models/llm.py` and `tilellm/__main__.py`.

Author: nc-infotechconsults

tilellm/__main__.py

@@ -277,6 +277,7 @@ async def reader(channel: Redis):
                             chunks_indexed=getattr(pc_result, "chunks", 0) or 0,
                             error_message=_idx_error,
                             request_id=item_single.request_id,
+                            agent_id=item_single.agent_id,
                         )
                         analytics.publish_nowait(_et, item_single.id_project, _pl)
 
@@ -655,6 +656,7 @@ async def create_scrape_item_single(
                 else 0,
                 error_message=_idx_error,
                 request_id=item.request_id,
+                agent_id=item.agent_id,
             )
             analytics.publish_nowait(_et, item.id_project, _pl)
 
@@ -772,6 +774,7 @@ async def create_scrape_item_hybrid(
                 else 0,
                 error_message=_idx_error,
                 request_id=item.request_id,
+                agent_id=item.agent_id,
             )
             analytics.publish_nowait(_et, item.id_project, _pl)
 
@@ -838,6 +841,7 @@ async def post_ask_with_memory_main(question_answer: QuestionAnswer):
             reranker_model=_reranker_model,
             latency_ms=_chunks_latency_ms,
             request_id=question_answer.request_id,
+            agent_id=question_answer.agent_id,
         )
         analytics.publish_nowait(_et, question_answer.id_project, _pl)
         return _chunks_result
@@ -890,6 +894,7 @@ async def post_ask_with_memory_main(question_answer: QuestionAnswer):
                     latency_ms=0,
                     request_id=question_answer.request_id,
                     success=result.success,
+                    agent_id=question_answer.agent_id,
                 )
                 analytics.publish_nowait(_et, question_answer.id_project, _pl)
                 return result
@@ -965,6 +970,7 @@ async def post_ask_with_memory_main(question_answer: QuestionAnswer):
         latency_ms=_qa_latency_ms,
         request_id=question_answer.request_id,
         success=result_success,
+        agent_id=question_answer.agent_id,
     )
     analytics.publish_nowait(_et, question_answer.id_project, _pl)
     return result

tilellm/analytics/events.py

@@ -104,6 +104,7 @@ def kb_query(
     reranker_latency_ms: Optional[int] = None,
     request_id: Optional[str] = None,
     success: Optional[bool] = None,
+    agent_id: Optional[str] = None,
 ) -> Tuple[str, dict]:
     """
     Build a kb.query_executed event payload.
@@ -120,6 +121,7 @@ def kb_query(
         request_id:          Tiledesk conversation/request ID.
         success:             Whether the LLM produced an answer from retrieved chunks.
                              Use None when no LLM answer exists (e.g. chunks_only).
+        agent_id:            Tiledesk agent/bot ID. Used for per-agent KB usage metrics.
     """
     payload: dict = {
         "kb_id":             kb_id,
@@ -130,6 +132,7 @@ def kb_query(
         "reranker_model":    reranker_model,
         "latency_ms":        latency_ms,
         "request_id":        request_id,
+        "agent_id":          agent_id,
     }
     if reranker_latency_ms is not None:
         payload["reranker_latency_ms"] = reranker_latency_ms
@@ -150,6 +153,7 @@ def content_indexed(
     chunks_indexed: int = 0,
     error_message: Optional[str] = None,
     request_id: Optional[str] = None,
+    agent_id: Optional[str] = None,
 ) -> Tuple[str, dict]:
     """
     Build a kb.content_indexed event payload.
@@ -166,6 +170,7 @@ def content_indexed(
         chunks_indexed: Number of chunks successfully indexed.
         error_message:  str(e) on exception, else null.
         request_id:     Tiledesk conversation/request ID.
+        agent_id:       Tiledesk agent/bot ID. Used for per-agent KB usage metrics.
     """
     return "kb.content_indexed", {
         "kb_id":           kb_id,
@@ -179,6 +184,7 @@ def content_indexed(
         "success":         success,
         "error_message":   error_message,
         "request_id":      request_id,
+        "agent_id":        agent_id,
     }
 
 

tilellm/models/llm.py

@@ -158,6 +158,10 @@ class ItemSingle(BaseModel):
         description="Tiledesk conversation/request ID. Links indexing operations to a "
         "specific customer conversation in the analytics platform.",
     )
+    agent_id: Optional[str] = Field(
+        default=None,
+        description="Tiledesk agent/bot ID for analytics. Enables per-agent KB usage metrics.",
+    )
     situated_context: Optional[SituatedContextConfig] = Field(
         default=None,
         description="Dedicated LLM configuration for Contextual Retrieval (situated context). Allows using a different/cheaper LLM for generating contextual sentences.",