Add provenance recording to React agent loop

Enables agent sessions to be traced and debugged using the same
explainability infrastructure as GraphRAG. Agent traces record:
- Session start with query and timestamp
- Each iteration's thought, action, arguments, and observation
- Final answer with derivation chain

Changes:
- Add session_id and collection fields to AgentRequest schema
- Add agent predicates (TG_THOUGHT, TG_ACTION, etc.) to namespaces
- Create agent provenance triple generators in provenance/agent.py
- Register explainability producer in agent service
- Emit provenance triples during agent execution
- Update CLI tools to detect and render agent traces alongside GraphRAG

trustgraph-base/trustgraph/messaging/translators/agent.py

@@ -13,7 +13,9 @@ class AgentRequestTranslator(MessageTranslator):
             group=data.get("group", None),
             history=data.get("history", []),
             user=data.get("user", "trustgraph"),
-            streaming=data.get("streaming", False)
+            collection=data.get("collection", "default"),
+            streaming=data.get("streaming", False),
+            session_id=data.get("session_id", ""),
         )
 
     def from_pulsar(self, obj: AgentRequest) -> Dict[str, Any]:
@@ -23,7 +25,9 @@ class AgentRequestTranslator(MessageTranslator):
             "group": obj.group,
             "history": obj.history,
             "user": obj.user,
-            "streaming": getattr(obj, "streaming", False)
+            "collection": getattr(obj, "collection", "default"),
+            "streaming": getattr(obj, "streaming", False),
+            "session_id": getattr(obj, "session_id", ""),
         }
 
 

trustgraph-base/trustgraph/provenance/__init__.py

@@ -45,6 +45,10 @@ from . uris import (
     exploration_uri,
     focus_uri,
     synthesis_uri,
+    # Agent provenance URIs
+    agent_session_uri,
+    agent_iteration_uri,
+    agent_final_uri,
 )
 
 # Namespace constants
@@ -65,6 +69,9 @@ from . namespaces import (
     TG_SOURCE_TEXT, TG_SOURCE_CHAR_OFFSET, TG_SOURCE_CHAR_LENGTH,
     # Query-time provenance predicates
     TG_QUERY, TG_EDGE_COUNT, TG_SELECTED_EDGE, TG_REASONING, TG_CONTENT,
+    # Agent provenance predicates
+    TG_THOUGHT, TG_ACTION, TG_ARGUMENTS, TG_OBSERVATION, TG_ANSWER,
+    TG_AGENT_SESSION, TG_AGENT_ITERATION, TG_AGENT_FINAL,
     # Named graphs
     GRAPH_DEFAULT, GRAPH_SOURCE, GRAPH_RETRIEVAL,
 )
@@ -83,6 +90,13 @@ from . triples import (
     set_graph,
 )
 
+# Agent provenance triple builders
+from . agent import (
+    agent_session_triples,
+    agent_iteration_triples,
+    agent_final_triples,
+)
+
 # Vocabulary bootstrap
 from . vocabulary import (
     get_vocabulary_triples,
@@ -107,6 +121,10 @@ __all__ = [
     "exploration_uri",
     "focus_uri",
     "synthesis_uri",
+    # Agent provenance URIs
+    "agent_session_uri",
+    "agent_iteration_uri",
+    "agent_final_uri",
     # Namespaces
     "PROV", "PROV_ENTITY", "PROV_ACTIVITY", "PROV_AGENT",
     "PROV_WAS_DERIVED_FROM", "PROV_WAS_GENERATED_BY",
@@ -120,6 +138,9 @@ __all__ = [
     "TG_SOURCE_TEXT", "TG_SOURCE_CHAR_OFFSET", "TG_SOURCE_CHAR_LENGTH",
     # Query-time provenance predicates
     "TG_QUERY", "TG_EDGE_COUNT", "TG_SELECTED_EDGE", "TG_REASONING", "TG_CONTENT",
+    # Agent provenance predicates
+    "TG_THOUGHT", "TG_ACTION", "TG_ARGUMENTS", "TG_OBSERVATION", "TG_ANSWER",
+    "TG_AGENT_SESSION", "TG_AGENT_ITERATION", "TG_AGENT_FINAL",
     # Named graphs
     "GRAPH_DEFAULT", "GRAPH_SOURCE", "GRAPH_RETRIEVAL",
     # Triple builders
@@ -131,6 +152,10 @@ __all__ = [
     "exploration_triples",
     "focus_triples",
     "synthesis_triples",
+    # Agent provenance triple builders
+    "agent_session_triples",
+    "agent_iteration_triples",
+    "agent_final_triples",
     # Utility
     "set_graph",
     # Vocabulary

trustgraph-base/trustgraph/provenance/agent.py

@@ -0,0 +1,136 @@
+"""
+Helper functions to build PROV-O triples for agent provenance.
+
+Agent provenance tracks the reasoning trace of ReAct agent sessions:
+- AgentSession: The root entity with query and timestamp
+- AgentIteration: Each think/act/observe cycle
+- AgentFinal: The final answer
+"""
+
+import json
+from datetime import datetime
+from typing import List, Optional, Dict, Any
+
+from .. schema import Triple, Term, IRI, LITERAL
+
+from . namespaces import (
+    RDF_TYPE, RDFS_LABEL,
+    PROV_ENTITY, PROV_WAS_DERIVED_FROM, PROV_STARTED_AT_TIME,
+    TG_QUERY, TG_THOUGHT, TG_ACTION, TG_ARGUMENTS, TG_OBSERVATION, TG_ANSWER,
+    TG_AGENT_SESSION, TG_AGENT_ITERATION, TG_AGENT_FINAL,
+)
+
+
+def _iri(uri: str) -> Term:
+    """Create an IRI term."""
+    return Term(type=IRI, iri=uri)
+
+
+def _literal(value) -> Term:
+    """Create a literal term."""
+    return Term(type=LITERAL, value=str(value))
+
+
+def _triple(s: str, p: str, o_term: Term) -> Triple:
+    """Create a triple with IRI subject and predicate."""
+    return Triple(s=_iri(s), p=_iri(p), o=o_term)
+
+
+def agent_session_triples(
+    session_uri: str,
+    query: str,
+    timestamp: Optional[str] = None,
+) -> List[Triple]:
+    """
+    Build triples for an agent session start.
+
+    Creates:
+    - Entity declaration for the session
+    - Query text and timestamp
+
+    Args:
+        session_uri: URI of the session (from agent_session_uri)
+        query: The user's query text
+        timestamp: ISO timestamp (defaults to now)
+
+    Returns:
+        List of Triple objects
+    """
+    if timestamp is None:
+        timestamp = datetime.utcnow().isoformat() + "Z"
+
+    return [
+        _triple(session_uri, RDF_TYPE, _iri(TG_AGENT_SESSION)),
+        _triple(session_uri, RDFS_LABEL, _literal("Agent Session")),
+        _triple(session_uri, PROV_STARTED_AT_TIME, _literal(timestamp)),
+        _triple(session_uri, TG_QUERY, _literal(query)),
+    ]
+
+
+def agent_iteration_triples(
+    iteration_uri: str,
+    parent_uri: str,
+    thought: str,
+    action: str,
+    arguments: Dict[str, Any],
+    observation: str,
+) -> List[Triple]:
+    """
+    Build triples for one agent iteration (think/act/observe cycle).
+
+    Creates:
+    - Entity declaration for the iteration
+    - wasDerivedFrom link to parent (previous iteration or session)
+    - Thought, action, arguments, and observation data
+
+    Args:
+        iteration_uri: URI of this iteration (from agent_iteration_uri)
+        parent_uri: URI of the parent (previous iteration or session)
+        thought: The agent's reasoning/thought
+        action: The tool/action name
+        arguments: Arguments passed to the tool (will be JSON-encoded)
+        observation: The result/observation from the tool
+
+    Returns:
+        List of Triple objects
+    """
+    triples = [
+        _triple(iteration_uri, RDF_TYPE, _iri(TG_AGENT_ITERATION)),
+        _triple(iteration_uri, RDFS_LABEL, _literal(f"Iteration: {action}")),
+        _triple(iteration_uri, PROV_WAS_DERIVED_FROM, _iri(parent_uri)),
+        _triple(iteration_uri, TG_THOUGHT, _literal(thought)),
+        _triple(iteration_uri, TG_ACTION, _literal(action)),
+        _triple(iteration_uri, TG_ARGUMENTS, _literal(json.dumps(arguments))),
+        _triple(iteration_uri, TG_OBSERVATION, _literal(observation)),
+    ]
+
+    return triples
+
+
+def agent_final_triples(
+    final_uri: str,
+    parent_uri: str,
+    answer: str,
+) -> List[Triple]:
+    """
+    Build triples for an agent final answer.
+
+    Creates:
+    - Entity declaration for the final answer
+    - wasDerivedFrom link to parent (last iteration or session)
+    - The answer text
+
+    Args:
+        final_uri: URI of the final answer (from agent_final_uri)
+        parent_uri: URI of the parent (last iteration or session if no iterations)
+        answer: The final answer text
+
+    Returns:
+        List of Triple objects
+    """
+    return [
+        _triple(final_uri, RDF_TYPE, _iri(TG_AGENT_FINAL)),
+        _triple(final_uri, RDFS_LABEL, _literal("Final Answer")),
+        _triple(final_uri, PROV_WAS_DERIVED_FROM, _iri(parent_uri)),
+        _triple(final_uri, TG_ANSWER, _literal(answer)),
+    ]

trustgraph-base/trustgraph/provenance/namespaces.py

@@ -68,6 +68,16 @@ TG_REASONING = TG + "reasoning"
 TG_CONTENT = TG + "content"
 TG_DOCUMENT = TG + "document"  # Reference to document in librarian
 
+# Agent provenance predicates
+TG_THOUGHT = TG + "thought"
+TG_ACTION = TG + "action"
+TG_ARGUMENTS = TG + "arguments"
+TG_OBSERVATION = TG + "observation"
+TG_ANSWER = TG + "answer"
+TG_AGENT_SESSION = TG + "AgentSession"
+TG_AGENT_ITERATION = TG + "AgentIteration"
+TG_AGENT_FINAL = TG + "AgentFinal"
+
 # Named graph URIs for RDF datasets
 # These separate different types of data while keeping them in the same collection
 GRAPH_DEFAULT = ""                       # Core knowledge facts (triples extracted from documents)

trustgraph-base/trustgraph/provenance/uris.py

@@ -138,3 +138,49 @@ def edge_selection_uri(session_id: str, edge_index: int) -> str:
         URN in format: urn:trustgraph:prov:edge:{uuid}:{index}
     """
     return f"urn:trustgraph:prov:edge:{session_id}:{edge_index}"
+
+
+# Agent provenance URIs
+# These URIs use the urn:trustgraph:agent: namespace to distinguish agent
+# provenance from GraphRAG question provenance
+
+def agent_session_uri(session_id: str = None) -> str:
+    """
+    Generate URI for an agent session.
+
+    Args:
+        session_id: Optional UUID string. Auto-generates if not provided.
+
+    Returns:
+        URN in format: urn:trustgraph:agent:{uuid}
+    """
+    if session_id is None:
+        session_id = str(uuid.uuid4())
+    return f"urn:trustgraph:agent:{session_id}"
+
+
+def agent_iteration_uri(session_id: str, iteration_num: int) -> str:
+    """
+    Generate URI for an agent iteration.
+
+    Args:
+        session_id: The session UUID.
+        iteration_num: 1-based iteration number.
+
+    Returns:
+        URN in format: urn:trustgraph:agent:{uuid}/i{num}
+    """
+    return f"urn:trustgraph:agent:{session_id}/i{iteration_num}"
+
+
+def agent_final_uri(session_id: str) -> str:
+    """
+    Generate URI for an agent final answer.
+
+    Args:
+        session_id: The session UUID.
+
+    Returns:
+        URN in format: urn:trustgraph:agent:{uuid}/final
+    """
+    return f"urn:trustgraph:agent:{session_id}/final"

trustgraph-base/trustgraph/schema/services/agent.py

@@ -23,7 +23,9 @@ class AgentRequest:
     group: list[str] | None = None
     history: list[AgentStep] = field(default_factory=list)
     user: str = ""              # User context for multi-tenancy
-    streaming: bool = False     # NEW: Enable streaming response delivery (default false)
+    collection: str = "default" # Collection for provenance traces
+    streaming: bool = False     # Enable streaming response delivery (default false)
+    session_id: str = ""        # For provenance tracking across iterations
 
 @dataclass
 class AgentResponse: