Semantica × Agno 集成实战为多智能体团队接入知识图谱记忆与决策智能【免费下载链接】semanticaGraph-Native Infrastructure for Context and Accountable AI Systems项目地址: https://gitcode.com/GitHub_Trending/sema/semanticaSemantica 提供面向上下文与可问责 AI 系统的图原生基础设施而 Agnoagno 1.0是广受欢迎的 Python 多智能体框架。integrations/agno提供了五个即插即用的组件把 Semantica 的知识图谱KG、向量记忆与决策智能直接注入任意 Agno Agent 或 Team。读完本文你将掌握如何用图结构记忆替换 Agno 的扁平存储、如何让 Agent 在推理循环中主动构建和查询上下文图以及如何为多智能体团队共享同一张上下文图并按角色隔离写入。集成总览五个组件解决什么问题Agno 原生的记忆与知识库是扁平化的记忆以文本行存储知识库以文档向量检索为主缺少实体之间的关联关系也难以沉淀决策这类结构化信息。Semantica × Agno 集成通过五个组件补齐了这一层组件Agno 侧接入点职责AgnoContextStoreAgentMemory(db…)实现agno.memory.db.base.MemoryDb用向量 上下文图混合记忆替换扁平存储AgnoKnowledgeGraphAgent(knowledge…)实现agno.knowledge.base.AgentKnowledge文档经完整抽取流水线进入可查询的ContextGraph支持多跳 GraphRAGAgnoDecisionKitAgent(tools[…])6 个决策智能工具记录决策、查找先例、追溯因果链、影响分析、策略校验、历史汇总AgnoKGToolkitAgent(tools[…])7 个知识图谱工具抽取实体、抽取关系、写入图、查询图、查找关联、推理事实、导出子图AgnoSharedContextTeam 级所有 Agent 共享一个ContextGraph通过bind_agent()获得按角色隔离的视图写入按角色打标签所有类都遵循 Agno 官方扩展点的Toolkit/MemoryDb/AgentKnowledge模式因此可以像使用 Agno 原生组件一样使用它们无需改动 Agent 的其余代码。安装核心集成与可选后端通过pyproject.toml中定义的 extras 安装源码中对应声明为agno [agno1.0.0]见 pyproject.toml# 核心集成 pip install semantica[agno] # 搭配图存储后端 pip install semantica[agno,graph-neo4j] pip install semantica[agno,graph-falkordb] # 全栈图存储 向量存储 pip install semantica[agno,graph-neo4j,vectorstore-pgvector]集成模块版本为0.3.0见 integrations/agno/init.py。组件一AgnoContextStore —— 图结构化的 Agent 记忆为什么需要它Agno 默认的AgentMemory(db…)是扁平的行存储。AgnoContextStore在进程内实现 Agno 的MemoryDb协议底层由 Semantica 的AgentContext驱动源码见 integrations/agno/context_store.py每次upsert_memory都把文本写入向量索引并同步抽取实体、扩充知识图谱节点每次read_memories则返回向量相似 一跳图邻居扩展的混合结果。基本用法from agno.agent import Agent from agno.memory import AgentMemory from agno.models.openai import OpenAIChat from semantica.context import ContextGraph from semantica.vector_store import VectorStore from integrations.agno import AgnoContextStore store AgnoContextStore( vector_storeVectorStore(backendfaiss), knowledge_graphContextGraph(advanced_analyticsTrue), decision_trackingTrue, # 每次 upsert 自动记录一条轻量决策 graph_expansionTrue, # read_memories 附带一跳图邻居 session_iduser_session_42, ) agent Agent( modelOpenAIChat(idgpt-4o), memoryAgentMemory(dbstore), descriptionA financially aware assistant with persistent decision intelligence., )参数与行为参数默认值说明vector_store自动创建VectorStore(backendfaiss)Semantica 向量存储实例knowledge_graph自动创建ContextGraph()上下文图实例decision_trackingTrue每次upsert_memory自动记录一条categorymemory的轻量决策条目graph_expansionTrue召回记忆时用一跳图邻居增强结果session_id自动生成 UUID图中节点的作用域标识核心方法AgnoContextStore完整实现了MemoryDb协议create、table_exists、memory_exists、read_memories、upsert_memory、delete_memory、drop_table、clear并在其之上扩展了 Semantica API方法说明upsert_memory()将文本存入AgentContext向量索引 图节点并对文本做 NER把抽取出的实体写入知识图谱read_memories()混合检索向量相似度 图跳扩展支持按user_id过滤、按时间排序默认新到旧与limit截断delete_memory()/drop_table()/clear()移除缓存并调用AgentContext.forget()record_decision()记录带推理与结果的结构化决策返回决策 IDfind_precedents()返回语义相似的历史决策默认最多 5 条retrieve()混合检索入口供应用层直接调用get_context_for_prompt()把相关历史决策格式化为多行文本用于注入系统提示词其中upsert_memory的底层链路见 context_store.py为AgentContext.store()持久化文本 →NERExtractor.extract_entities()抽取实体 →ContextGraph.add_node()写入图 →若开启record_decision()记录决策 → 更新进程内缓存。每条路径都有异常兜底失败仅记日志、不影响主流程。get_context_for_prompt(scenario, max_precedents3)特别适合在每次调用 LLM 前自动召回相关先例——无先例时返回空字符串不会污染提示词见 context_store.py。组件二AgnoKnowledgeGraph —— 基于知识图谱的 Agent 知识库从扁平文档库到可查询图AgnoKnowledgeGraph实现 Agno 的AgentKnowledge协议让 Agent 面向结构化的ContextGraph而不是扁平文档库做检索。注入的文档会经过 Semantica 完整抽取流水线源码见 integrations/agno/knowledge_graph.pyIngestion:parse → NER → relation extract → graph build → vector indexSearch:vector retrieval → entity lookup → graph hop expansion → context injectionfrom agno.agent import Agent from agno.models.openai import OpenAIChat from semantica.kg import GraphBuilder from semantica.semantic_extract import NERExtractor, RelationExtractor from integrations.agno import AgnoKnowledgeGraph kg AgnoKnowledgeGraph( graph_builderGraphBuilder(), ner_extractorNERExtractor(), relation_extractorRelationExtractor(), ) kg.load(regulatory_docs/, recursiveTrue) # 目录递归注入 kg.load(texts[Basel IV capital requirements apply from January 2026.]) # 直接注入文本 agent Agent(modelOpenAIChat(idgpt-4o), knowledgekg, search_knowledgeTrue)参数说明参数默认值说明graph_builder自动创建GraphBuilder()负责把文本 实体 关系构建成图其graph_store在初始化时被自动接到内部ContextGraphner_extractor自动创建NERExtractor()命名实体识别器relation_extractor自动创建RelationExtractor()关系抽取器context_graph自动创建ContextGraph()外部传入的已有图传入后与向量检索共享同一张图graph_store_backendinmemory图后端inmemory、neo4j、falkordbgraph_store_uriNone所选图后端的连接 URInum_documents5search()默认返回的文档数chunk_size1000注入时的最大文本分块字符数按段落边界切分加载方式与检索load()支持三种来源见 knowledge_graph.pypath文件、目录或 glob 模式目录配合recursiveTrue递归遍历逐文件以 UTF-8 读取texts原始字符串列表来源标记为inlineurls通过load_urls()抓取复用semantica.ingest.ssrf.request_with_ssrf_guard做 SSRF 防护——仅允许http/https协议默认拦截私有/回环/链路本地/云元数据地址校验 DNS 解析并逐跳复查重定向见 knowledge_graph.py。search(query, num_documentsNone, filtersNone)执行多跳 GraphRAG先用AgentContext.retrieve()做向量检索再对结果中的实体做一跳图邻居扩展把[Graph context]文本块附加到文档内容后返回 AgnoDocument对象当向量检索不可用时自动降级为对进程内文档缓存的关键词打分见 knowledge_graph.py。此外get_graph_context(entity)返回某个实体一跳子图的文本表示邻居节点与边类型适合结构化推理场景ctx kg.get_graph_context(Basel IV) # Entity: Basel IV # --[applies_to]-- EU Banks (type: Organization) # --[covers]-- Capital Requirements内部注入链路_ingest_text为段落分块 → NER → 关系抽取 →GraphBuilder.build()落图 →AgentContext.store()入向量索引 → 缓存文档见 knowledge_graph.py。组件三AgnoDecisionKit —— 决策智能工具集AgnoDecisionKit把 Semantica 的决策智能以 AgnoToolkit的形式暴露给 Agent让 Agent 在推理循环中主动记录、查询与校验决策源码见 integrations/agno/decision_kit.pyfrom agno.agent import Agent from agno.models.openai import OpenAIChat from semantica.context import AgentContext from integrations.agno import AgnoDecisionKit ctx AgentContext(decision_trackingTrue) agent Agent( modelOpenAIChat(idgpt-4o), tools[AgnoDecisionKit(contextctx)], show_tool_callsTrue, ) agent.print_response(Should we approve this mortgage application?)构造参数contextAgentContext或兼容对象缺省自动创建、max_precedents5find_precedents默认返回数、causal_depth3trace_causal_chain默认链深、enable_policy_checkTrue是否注册check_policy工具。六个工具工具说明关键实现细节record_decision记录决策及其推理、结果与置信度返回{decision_id: ..., status: recorded}JSONentities支持逗号分隔列表find_precedents按场景搜索相似历史决策调用find_precedents_advanced归一化为可序列化列表返回trace_causal_chain追溯决策的因果链调用图的trace_decision_causality(decision_id, depth…)缺该 API 时降级为按类别找先例analyze_impact用图中心性评估决策的下游影响调用AgentContext.analyze_decision_influence()check_policy校验决策是否符合策略规则支持 ! 六种比较运算符不可求值的规则进入warnings而非violationsget_decision_summary按类别汇总决策历史基于AgentContext.get_context_insights()check_policy 的规则语法check_policy(decision_data, policy_rules)的policy_rules是 JSON 规则字符串列表例如[confidence 0.7, category ! \test\]每条规则形如field op value。源码对边界情况处理得非常细致见 decision_kit.pydecision_data必须解码为 JSON 对象否则直接记为违规引用了缺失字段、字段值为null或格式无法识别的规则会进入warnings避免静默判为合规裸字符串policy_rulesconfidence 0.7视为单条规则而非逐字符遍历。组件四AgnoKGToolkit —— 让 Agent 主动构建与查询知识图谱AgnoKGToolkit让 Agent 在推理过程中直接操作上下文图既可以从文本中抽取实体/关系写入图也可以查询、推理与导出子图源码见 integrations/agno/kg_toolkit.pyfrom agno.agent import Agent from agno.models.openai import OpenAIChat from integrations.agno import AgnoKGToolkit agent Agent( modelOpenAIChat(idgpt-4o), tools[AgnoKGToolkit()], show_tool_callsTrue, )构造参数graph_store_backendinmemory/neo4j/falkordb、ner_extractor、relation_extractor、reasoner自动创建semantica.reasoning.Reasoner、context可传入已有AgentContext或ContextGraph复用。七个工具工具说明返回格式extract_entities从文本抽取命名实体{entities: [{name, type, confidence}], count}extract_relations抽取实体间关系可按实体列表限定{relations: [{source, relation, target, confidence}], count}add_to_graph把实体/关系写入上下文图{nodes_added, edges_added}query_graph自然语言关键词查询以MATCH开头走 Cypher需 Neo4j/FalkorDB 后端{results, query_type}find_related沿图跳默认 1 跳查找相关概念{entity, related, count}infer_facts用规则在图上演推新事实{inferred_facts, count}export_subgraph导出子图为 RDFjson-ld/turtle/ttl/xml/nt{format, data}其中infer_facts的规则形如IF Person(?x) THEN Human(?x)未显式提供事实时自动从图中取前 50 个节点生成Type(label)形式的事实集见 kg_toolkit.pyexport_subgraph底层复用semantica.export.RDFExporter导出失败时兜底返回图节点 JSON。组件五AgnoSharedContext —— 多智能体团队共享上下文在 AgnoTeam中多个 Agent 往往需要共享同一份知识与决策历史同时又不能互相污染写入。AgnoSharedContext用一个ContextGraph贯穿整个团队每个 Agent 通过bind_agent(role)获得一个按角色命名空间隔离的AgnoContextStore所有写入都带角色标签源码见 integrations/agno/shared_context.pyfrom agno.agent import Agent from agno.team import Team from agno.models.openai import OpenAIChat from semantica.context import ContextGraph from semantica.vector_store import VectorStore from integrations.agno import AgnoSharedContext, AgnoDecisionKit, AgnoKGToolkit shared AgnoSharedContext( vector_storeVectorStore(backendfaiss), knowledge_graphContextGraph(advanced_analyticsTrue), decision_trackingTrue, ) research_agent Agent( nameResearcher, modelOpenAIChat(idgpt-4o), memoryshared.bind_agent(researcher), tools[AgnoKGToolkit(contextshared)], ) decision_agent Agent( nameAnalyst, modelOpenAIChat(idgpt-4o), memoryshared.bind_agent(analyst), tools[AgnoDecisionKit(contextshared)], ) team Team( nameResearch Decision Team, agents[research_agent, decision_agent], modecoordinate, )团队级 APIdecision_id shared.record_decision( categorystrategy, scenarioExpand to EU market, reasoningStrong demand signals from Q1 survey, outcomeapproved, confidence0.87, agent_rolecfo, # 可选按角色给决策打标签 ) precedents shared.find_precedents(market expansion) insights shared.get_shared_insights()核心机制见 shared_context.py角色隔离bind_agent(role)幂等——同一role多次调用返回同一个_AgentScopedStore实例其session_id为{team_session}::{role}记忆以categoryfmemory:{role}写入决策以f{category}:{agent_role}打标签。共享可见每个角色的read_memories()返回自己的记忆 团队共享记忆池的并集_shared_memories保证 Researcher 的记忆对 Analyst 可见。线程安全内部用threading.RLock保护bind_agent与record_decision支持多 Agent 并发访问同一上下文对应测试见 tests/integrations/agno/test_shared_context.py其中包含并发绑定同一角色、角色标签、记忆跨角色可见等用例。API 参考与优雅降级from integrations.agno import ( AgnoContextStore, # MemoryDb implementation AgnoKnowledgeGraph, # AgentKnowledge implementation AgnoDecisionKit, # Decision intelligence Toolkit AgnoKGToolkit, # Knowledge graph Toolkit AgnoSharedContext, # Team-level shared context AGNO_AVAILABLE, # bool: True if agno is installed )五个类均可在未安装agno的情况下导入并使用它们携带完整的 Semantica API并在agno缺席时提供轻量替代类型如_MemoryRow、_Document仅在真正传给 Agno 的Agent/Team构造器时需要agno环境。每个模块都通过try/except ImportError设置AGNO_AVAILABLE标志Toolkit注册逻辑self.register()与_tools列表解耦保证无论agno是否安装_tools都可被应用层检视见 decision_kit.py。测试套件也专门使用 stub 模块模拟agno来验证这一点见 tests/integrations/agno/test_knowledge_graph.py。延伸阅读Context Module —— 支撑本集成的AgentContext与ContextGraphKnowledge Graph ——AgnoKnowledgeGraph使用的 KG 构建能力LLMs —— 为 Agno Agent 配置 LLM 提供商Vector Store ——AgnoContextStore的向量后端Agno 决策智能 Notebook 与 Agno GraphRAG 上下文 Notebook、多智能体共享上下文 Notebook —— 完整的可运行示例集成模块测试用例tests/integrations/agno/覆盖 MemoryDb 协议、KG 注入、决策工具、共享上下文与 SSRF 防护【免费下载链接】semanticaGraph-Native Infrastructure for Context and Accountable AI Systems项目地址: https://gitcode.com/GitHub_Trending/sema/semantica创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考