trustgraph/docs/tech-specs/agent-explainability.zh-cn.md

layout	title	parent
default	Agent Explainability: Provenance Recording	Chinese (Beta)

Agent Explainability: Provenance Recording

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

概述

为使代理会话可追溯和可调试，并将代理循环中的溯源记录添加到 React 代理中，从而使用与 GraphRAG 相同的可解释性基础设施。

设计决策： 写入 urn:graph:retrieval (通用可解释性图) 目前采用线性依赖链 (分析 N → wasDerivedFrom → 分析 N-1) 工具是不可见的黑盒 (仅记录输入/输出) DAG 支持计划在未来迭代中实现

实体类型

GraphRAG 和 Agent 都使用 PROV-O 作为基础本体，并具有 TrustGraph 特定的子类型：

GraphRAG 类型

实体	PROV-O 类型	TG 类型	描述
问题	prov:Activity	tg:Question, tg:GraphRagQuestion	用户的查询
探索	prov:Entity	tg:Exploration	从知识图谱检索的边
重点	prov:Entity	tg:Focus	带有推理的选定边
合成	prov:Entity	tg:Synthesis	最终答案

Agent 类型

实体	PROV-O 类型	TG 类型	描述
问题	prov:Activity	tg:Question, tg:AgentQuestion	用户的查询
分析	prov:Entity	tg:Analysis	每个思考/行动/观察周期
结论	prov:Entity	tg:Conclusion	最终答案

Document RAG 类型

实体	PROV-O 类型	TG 类型	描述
问题	prov:Activity	tg:Question, tg:DocRagQuestion	用户的查询
探索	prov:Entity	tg:Exploration	从文档存储中检索的块
合成	prov:Entity	tg:Synthesis	最终答案

注意： Document RAG 使用 GraphRAG 类型的子集 (没有“重点”步骤，因为没有边选择/推理阶段)。

问题子类型

所有“问题”实体都共享 tg:Question 作为基本类型，但具有特定的子类型以标识检索机制：

子类型	URI 模式	机制
tg:GraphRagQuestion	urn:trustgraph:question:{uuid}	知识图谱 RAG
tg:DocRagQuestion	urn:trustgraph:docrag:{uuid}	文档/块 RAG
tg:AgentQuestion	urn:trustgraph:agent:{uuid}	ReAct 代理

这允许通过 tg:Question 查询所有问题，同时通过子类型过滤特定机制。

溯源模型

Question (urn:trustgraph:agent:{uuid})
    │
    │  tg:query = "User's question"
    │  prov:startedAtTime = timestamp
    │  rdf:type = prov:Activity, tg:Question
    │
    ↓ prov:wasDerivedFrom
    │
Analysis1 (urn:trustgraph:agent:{uuid}/i1)
    │
    │  tg:thought = "I need to query the knowledge base..."
    │  tg:action = "knowledge-query"
    │  tg:arguments = {"question": "..."}
    │  tg:observation = "Result from tool..."
    │  rdf:type = prov:Entity, tg:Analysis
    │
    ↓ prov:wasDerivedFrom
    │
Analysis2 (urn:trustgraph:agent:{uuid}/i2)
    │  ...
    ↓ prov:wasDerivedFrom
    │
Conclusion (urn:trustgraph:agent:{uuid}/final)
    │
    │  tg:answer = "The final response..."
    │  rdf:type = prov:Entity, tg:Conclusion

文档检索增强生成（RAG）溯源模型

Question (urn:trustgraph:docrag:{uuid})
    │
    │  tg:query = "User's question"
    │  prov:startedAtTime = timestamp
    │  rdf:type = prov:Activity, tg:Question
    │
    ↓ prov:wasGeneratedBy
    │
Exploration (urn:trustgraph:docrag:{uuid}/exploration)
    │
    │  tg:chunkCount = 5
    │  tg:selectedChunk = "chunk-id-1"
    │  tg:selectedChunk = "chunk-id-2"
    │  ...
    │  rdf:type = prov:Entity, tg:Exploration
    │
    ↓ prov:wasDerivedFrom
    │
Synthesis (urn:trustgraph:docrag:{uuid}/synthesis)
    │
    │  tg:content = "The synthesized answer..."
    │  rdf:type = prov:Entity, tg:Synthesis

需要修改的内容

1. 模式更改

文件: trustgraph-base/trustgraph/schema/services/agent.py

向 AgentRequest 添加 session_id 和 collection 字段：

@dataclass
class AgentRequest:
    question: str = ""
    state: str = ""
    group: list[str] | None = None
    history: list[AgentStep] = field(default_factory=list)
    user: str = ""
    collection: str = "default"  # NEW: Collection for provenance traces
    streaming: bool = False
    session_id: str = ""         # NEW: For provenance tracking across iterations

文件: trustgraph-base/trustgraph/messaging/translators/agent.py

更新翻译器，使其能够处理 session_id 和 collection，并在 to_pulsar() 和 from_pulsar() 中均能正确处理。

2. 向 Agent Service 添加可解释性生产者

文件: trustgraph-flow/trustgraph/agent/react/service.py

注册一个“可解释性”生产者（与 GraphRAG 相同模式）：

from ... base import ProducerSpec
from ... schema import Triples

# In __init__:
self.register_specification(
    ProducerSpec(
        name = "explainability",
        schema = Triples,
    )
)

3. 溯源三元组生成

文件: trustgraph-base/trustgraph/provenance/agent.py

创建辅助函数（类似于 GraphRAG 的 question_triples、exploration_triples 等）：

def agent_session_triples(session_uri, query, timestamp):
    """Generate triples for agent Question."""
    return [
        Triple(s=session_uri, p=RDF_TYPE, o=PROV_ACTIVITY),
        Triple(s=session_uri, p=RDF_TYPE, o=TG_QUESTION),
        Triple(s=session_uri, p=TG_QUERY, o=query),
        Triple(s=session_uri, p=PROV_STARTED_AT_TIME, o=timestamp),
    ]

def agent_iteration_triples(iteration_uri, parent_uri, thought, action, arguments, observation):
    """Generate triples for one Analysis step."""
    return [
        Triple(s=iteration_uri, p=RDF_TYPE, o=PROV_ENTITY),
        Triple(s=iteration_uri, p=RDF_TYPE, o=TG_ANALYSIS),
        Triple(s=iteration_uri, p=TG_THOUGHT, o=thought),
        Triple(s=iteration_uri, p=TG_ACTION, o=action),
        Triple(s=iteration_uri, p=TG_ARGUMENTS, o=json.dumps(arguments)),
        Triple(s=iteration_uri, p=TG_OBSERVATION, o=observation),
        Triple(s=iteration_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
    ]

def agent_final_triples(final_uri, parent_uri, answer):
    """Generate triples for Conclusion."""
    return [
        Triple(s=final_uri, p=RDF_TYPE, o=PROV_ENTITY),
        Triple(s=final_uri, p=RDF_TYPE, o=TG_CONCLUSION),
        Triple(s=final_uri, p=TG_ANSWER, o=answer),
        Triple(s=final_uri, p=PROV_WAS_DERIVED_FROM, o=parent_uri),
    ]

4. 类型定义

文件: trustgraph-base/trustgraph/provenance/namespaces.py

添加可解释性实体类型和代理谓词：

# Explainability entity types (used by both GraphRAG and Agent)
TG_QUESTION = TG + "Question"
TG_EXPLORATION = TG + "Exploration"
TG_FOCUS = TG + "Focus"
TG_SYNTHESIS = TG + "Synthesis"
TG_ANALYSIS = TG + "Analysis"
TG_CONCLUSION = TG + "Conclusion"

# Agent predicates
TG_THOUGHT = TG + "thought"
TG_ACTION = TG + "action"
TG_ARGUMENTS = TG + "arguments"
TG_OBSERVATION = TG + "observation"
TG_ANSWER = TG + "answer"

文件修改

文件	更改
trustgraph-base/trustgraph/schema/services/agent.py	向 AgentRequest 添加 session_id 和 collection
trustgraph-base/trustgraph/messaging/translators/agent.py	更新翻译器以适应新字段
trustgraph-base/trustgraph/provenance/namespaces.py	添加实体类型、agent谓词和 Document RAG 谓词
trustgraph-base/trustgraph/provenance/triples.py	向 GraphRAG 三元组构建器添加 TG 类型，添加 Document RAG 三元组构建器
trustgraph-base/trustgraph/provenance/uris.py	添加 Document RAG URI 生成器
trustgraph-base/trustgraph/provenance/__init__.py	导出新类型、谓词和 Document RAG 函数
trustgraph-base/trustgraph/schema/services/retrieval.py	向 DocumentRagResponse 添加 explain_id 和 explain_graph
trustgraph-base/trustgraph/messaging/translators/retrieval.py	更新 DocumentRagResponseTranslator 以适应可解释性字段
trustgraph-flow/trustgraph/agent/react/service.py	添加可解释性生产者 + 记录逻辑
trustgraph-flow/trustgraph/retrieval/document_rag/document_rag.py	添加可解释性回调并发出溯源三元组
trustgraph-flow/trustgraph/retrieval/document_rag/rag.py	添加可解释性生产者并连接回调
trustgraph-cli/trustgraph/cli/show_explain_trace.py	处理 agent 跟踪类型
trustgraph-cli/trustgraph/cli/list_explain_traces.py	在 GraphRAG 旁边列出 agent 会话

创建的文件

文件	目的
trustgraph-base/trustgraph/provenance/agent.py	Agent 相关的三元组生成器

CLI 更新

检测： 无论是 GraphRAG 还是 Agent 问题，都具有 tg:Question 类型。通过以下方式区分：

1. URI 模式：urn:trustgraph:agent: vs urn:trustgraph:question:
2. 派生实体：tg:Analysis (agent) vs tg:Exploration (GraphRAG)

list_explain_traces.py: 显示类型列（Agent vs GraphRAG）

show_explain_trace.py: 自动检测跟踪类型 Agent 渲染显示：问题 → 分析步骤(s) → 结论

向后兼容性

session_id 默认为 "" - 旧请求有效，但将不具有溯源信息 collection 默认为 "default" - 合理的备选方案 CLI 能够优雅地处理两种跟踪类型

验证

# Run an agent query
tg-invoke-agent -q "What is the capital of France?"

# List traces (should show agent sessions with Type column)
tg-list-explain-traces -U trustgraph -C default

# Show agent trace
tg-show-explain-trace "urn:trustgraph:agent:xxx"

未来工作（不在本次 PR 中）

DAG 依赖关系（当分析 N 使用来自多个先前分析的结果时） 特定于工具的溯源链接（KnowledgeQuery → 它的 GraphRAG 跟踪） 流式溯源输出（在过程中输出，而不是在最后批量输出）