Typedef的愿景：构建数据智能体的信任层

本次工作坊由Typedef联合创始人Yoni Michael与创始工程师Brandon Callender共同主持。尽管现场气氛轻松，甚至有人因世界杯比赛分心，但团队致力于通过技术演示保持参与度。Typedef的核心使命是为数据智能体构建企业级信任层（Enterprise Trust Layer），使AI能够安全、准确地访问和执行数据平台上的高复杂度任务。他们提出的核心概念是“数据上下文层”（Data Context Layer），这是实现这一使命的关键基础设施。Yoni指出，模型本身并非瓶颈，随着大语言模型能力的持续增长，真正限制智能体有效性的缺失环节在于上下文工程。只有解决了如何让智能体理解数据系统全貌的问题，才能释放其在数据分析领域的潜力。

编码智能体与数据智能体的关键差异

团队在过去两年中深入研究了代码智能体（如Anthropic的Claude、Cursor等）的上下文工程，发现将同样的方法直接应用于数据领域存在显著不足。当智能体在数据任务中“自信地犯错”时，后果远比代码错误严重，可能导致财务报表、董事会演示文稿或关键数据管道出现静默失败。因此，Typedef的核心赌注是：智能体将成为数据系统的核心操作者。为了让人类信任这些AI，必须赋予它们类似资深数据工程师的推理能力——即理解从底层存储到上层指标的全链路逻辑。如果智能体无法可靠地执行日常数据团队的核心工作，人类将不敢赋予其读写权限。这种从“问答型”向“操作型”智能体的转变，要求系统具备极高的可靠性。

数据智能体面临的三大核心挑战

在构建过程中，团队识别出当前编码智能体在处理数据任务时的三个主要失败领域：影响分析（Impact Analysis）、连接推荐（Join Recommendations）以及安全代码变更。首先，智能体需要知道修改某处逻辑会破坏哪些下游依赖；其次，它必须判断跨表连接是否安全且符合业务语义；最后，它需确保转换逻辑的修改不会改变指标的定义。这些并非边缘任务，而是数据团队日常工作的核心。如果智能体无法可靠地推理和执行这些任务，人类很难信任它进行任何数据操作。Yoni强调，目标不是让AI仅仅回答问题，而是让它成为能够安全读写数据的核心操作者（Core Operators）。

上下文分散难题与“粒度”概念

数据所需的上下文并非集中存储，而是分散在多个不同的系统中。例如：数仓（Warehouse）存储原始行数据；转换代码包含关键的业务逻辑；BI工具中定义了指标和维度；而文档、Slack频道甚至员工头脑中的“部落知识”也承载着重要信息。智能体需要一种中间层来整合这些信息，理解模型的含义、关联关系以及变更后果。Yoni特别引入了“粒度（Grain）”这一关键概念，即表中每一行所代表的实际含义。如果将粒度从“按月”错误地变为“按周”，即使SQL编译通过，下游的所有求和计算都将出错。这种细微的语义差异是智能体必须掌握的核心知识，也是构建数据上下文层以解决上述分散问题的关键所在。

核心痛点：有效SQL不足以支撑正确的根因分析

当用户询问AI Agent为何某数据流水线的行数在一夜之间激增40%时，Agent虽然能编写并运行有效的SQL代码、渲染出精美的图表，但最终往往会报告错误的根本原因。这是因为Agent无法区分真正的数据量激增与因上游列变化导致的“粒度改变”（Grain Change）。例如，一个原本是一对一的连接可能变成了一对多连接，导致行数翻倍，但数据本身并不包含“一行代表什么”的语义信息。Agent可以读取SQL、获取样本行，但它不知道这一行原本的含义以及现在含义的彻底改变。因此，仅仅拥有有效的SQL是不够的，语义理解对于Agent的有效性至关重要。正如演讲者所言：

"It says, 'Looks like there's more data that came in. Um, but what actually happened is there was an upstream column that uh turned a one-to-one join into a one to many join... the agent literally cannot tell a real spike like a real data spike and differentiate between that from an actual grain change.'"

现有方案的局限性与缺失的四个关键事实

针对上述场景，常见的两种修复方案均存在缺陷：一是将DBT或Airflow代码直接提供给Agent，但这会导致每次提示都需要从头重建上下文，受限于上下文窗口大小且具有概率性不确定性；二是让Agent直接连接Snowflake或Databricks等数据库查看数据，但这仅能让其看到数字而无法理解每行数据的实际含义。这两种方式都缺乏对系统行为模式的持久化模型。要解决这一问题，必须明确决定答案正确性的四个关键事实，而这些事实在查询时往往无法被Agent轻易推断： 1. 一行数据在表中代表什么（粒度）。 2. 连接是否安全。 3. 指标的实际含义及其关联关系。 4. 数据资产之间的依赖与领域归属。这些事实通常以“部落知识”的形式存在于人的头脑或文档中，而非显式记录在代码里。

连接安全性的语义困境与领域自动聚类

以SQL中的“等值连接”（equi join）为例，相同的语法可能产生四种完全不同的结果：保留行数、查找维度、或在从一对多关系发生时静默复制每一行。同样，BETWEEN子句可能是安全的查找，也可能是导致粒度爆炸的日期脊柱（date spine）。这证明语法本身不足以让Agent有效运作，这是一个上下文问题而非模型能力问题。此外，对于数据资产的组织（如收入域、产品域），传统上依赖文件夹名称或部落知识。通过利用表级血缘、列级血缘、共享键和命名规范，系统可以自动将模型聚类到特定领域。这使得Agent能够将“哪些模型属于收入域”转化为一个可查询的问题，而非需要反复与人类确认的模糊问题。这种思路体现了上下文工程的核心原则：将部落知识计算化并使其可查询。

核心架构：从实现推导上下文以防止漂移

Typedef 提出的“数据上下文层”（Data Context Layer）旨在解决 AI Agent 在处理企业级数据时容易偏离实际代码实现的问题。该架构的核心逻辑是将所有的转换逻辑解析到底层，使 Agent 能够真正理解数据的结构。Agent 不会凭空猜测数据关系，而是基于从实际代码实现中派生的图和上下文进行操作。这种设计确保了 Agent 的行为始终与底层数据资产保持一致，避免了因语义误解导致的错误。为了进一步验证数据的准确性，系统会对仓库中的表进行配置分析（profiling），例如检查连接键是否唯一。这使得 Agent 能够基于真实数据分布而非假设来判断基数（cardinality），从而消除不确定性。通过这种方式，LLM 仅负责处理人类可读的部分，如理解业务名称、总结模型用途或解决歧义，而将事实性数据与代码实现紧密绑定。这些计算出的事实在图构建过程中被验证，确保 Agent 不会偏离核心实现。

技术选型：为何选择图数据库而非文本文件

数据上下文层本质上是一个在每次提交时原子刷新、增量更新的图结构。它代表了生产环境中企业数据的最新状态。选择图而非一堆文本或 Markdown 文件，主要基于访问模式的考量。Agent 能够通过一次遍历精确提取所需的子图，这避免了提示词填充（prompt stuffing）或上下文过载的问题。这种架构能够轻松扩展至超过 500 个模型，因为 Agent 无需每次重新阅读整个项目来构建上下文。近年来图数据库的复兴证明了其在 AI 领域的价值，因为模型擅长抓取上下文、编写查询并遍历关系。数据资产天然具有依赖性特征，非常适合转化为图中的类型化对象、节点和边。边缘携带大量血缘信息，定义了数据资产间的关系（如“由...物化”、“具有语义定义”），节点则代表不同的数据资产类型（如逻辑视图或物理表）。这种结构使得 Agent 能够清晰地看到从源系统到 BI 仪表板的完整数据生命周期。

应用场景一：变更前的影响分析与爆炸半径评估

利用上下文层，Agent 可以在执行任何代码变更前进行预飞行（pre-flight）影响分析。关键优势在于 Agent 在行动前就能知晓爆炸半径，而非在构建时或生产事故中才发现错误。例如，当 Agent 提议修改模型的粒度（如从月度改为周度）时，它会沿着图向下遍历所有下游依赖节点。Agent 会询问每个受影响的节点：“如果我改变上游粒度，是否会破坏你当前的表示？”在一个具体案例中，Agent 发现如果将月度粒度改为周度，下游某个按月汇总的 ARR（年度经常性收入）指标会在每周行中重复计算。这会导致最终度量值变为实际准确值的 4 倍。由于上下文图包含了从源系统到仪表板的所有数据资产，Agent 能够追踪这种错误如何传播至最终的 BI 层。这种在代码编写前捕获逻辑错误的机制，极大地降低了生产环境的风险。

应用场景二：基于数据事实的安全连接推荐与代码变更

除了影响分析，Agent 还能提供有证据支持的建议。在“连接推荐”场景中，当 Agent 试图按营销渠道对 ARR 进行归因时，它不会仅凭列名猜测路径。Agent 会验证每个连接键是否唯一，这是通过配置分析实际表数据完成的。系统能够识别出哪些路径会导致“扇出”（fan-out），例如导致行数增加 7 倍，或者哪些路径会静默丢弃下游 12% 的行数据。通过提供这些基于事实的推理，Agent 能够推荐安全的连接路径。在安全代码变更方面，由于业务定义往往嵌套在 SQL 中，Agent 可以利用上下文层理解这些语义。这使得 Agent 能够更准确地整理度量标准或指标，确保代码变更既符合业务逻辑又保持数据一致性。这种基于数据和事实的推理能力，使得 Agent 从简单的代码生成器转变为具备数据治理意识的智能助手。

语义重构陷阱与数据上下文层的防御机制

在构建代理（Agent）处理SQL时，最危险的并非语法错误，而是语义层面的静默重构。当代理移除一个谓词（predicate）时，SQL代码虽然能正常编译运行，但实际上它破坏了业务定义的核心逻辑。以“付费流失率”（paid churn）为例，代理可能无意中移除了定义该指标的关键条件，导致下游三个仪表板所展示的数据含义发生根本性改变。这种业务定义的静默重定义极具隐蔽性，因为从代码语法上看它是“无害”的。

数据上下文层（Data Context Layer）的核心价值在于，它将这些业务定义和指标约束作为一等公民（first-class constraints）嵌入系统，而不仅仅是YAML文件中的注释。这划清了语法重构与人类可信任变更之间的界限：只有当代理理解并遵守这些上下文约束时，它才能被视为具备操作数据系统的资格。通过捕获这种变更意图并在实施前进行拦截，系统确保了业务逻辑的一致性不被破坏。

评估驱动开发与基准测试方法论

为了验证数据上下文层的有效性，团队采用了评估驱动开发（eval-driven development）的方法论。他们构建了涵盖从简单到困难的各种真实生产数据工程用例、任务和流程，并在隔离的数据环境克隆体中多次运行这些测试。这种隔离至关重要，因为它防止了不同测试环境之间的数据泄露（data leakage），确保了评估结果的纯净性。

在评估过程中，团队结合了传统的通过/失败（pass/fail）检查与基于LLM的裁判机制，后者主要用于进行影响分析。实验的核心变量仅有一个：代理是否拥有数据上下文层的访问权限。其他条件如模型类型、任务难度均保持一致。这种严谨的实验设计旨在量化上下文信息对代理性能的具体贡献，从而证明引入结构化数据背景并非锦上添花，而是提升可靠性的关键手段。

基准测试核心发现：上下文带来的性能跃升

实验结果揭示了数据上下文层对代理推理能力的巨大提升。尽管使用的是相同的模型和任务，但在拥有丰富上下文的条件下，代理能够处理极其复杂的变更逻辑。数据显示，当代理被赋予数据上下文层时，任务成功率提升了近35个百分点。这一显著的性能跃升表明，提供丰富、结构化的上下文比单纯更换更强大的模型或添加更多通用工具（如MCP工具）更为有效。

"The key findings here is that although the same models, it's the same task, the only variable that's changing is where the agent has access to the data context layer. And so you see a material lift... task success rate goes up tremendously. It's almost 35 points higher when it's armed with the data context layer."

这一信号是一致的：更好的上下文带来截然不同的结果。随着团队与更多用户合作定制用例，该基准测试将持续演进，但核心结论已明确：上下文的质量直接决定了代理在复杂数据工程任务中的成败。这一发现为后续构建更智能、更可靠的数据代理系统提供了坚实的理论依据和数据支持。

五大设计模式与从代码阅读到系统操作的跨越

基于一年的构建经验，团队总结了五个关键的设计模式。首先，尽可能保持确定性（deterministic）：不要将整个DBT项目或Airflow逻辑直接扔给模型，而应通过解析AST来理解结构、关系和依赖，利用关系代数计算粒度（grain）。其次，存储证据而非结论：保留信号让代理在查询时推理，利用其强大的逻辑能力。第三，遍历优于提示填充（traversal beats prompt stuffing）：让代理按需拉取子图并遍历依赖，而非一次性加载整个仓库，从而保持上下文的高效与精简。

第四，掌控工具表面（own the tool surface）：经过策展的定制化工具集优于现成的MCP工具堆砌，团队甚至需要重写部分标准接口以匹配特定需求。第五，持续投资评估基础设施（eval infrastructure）：无法测量就无法学习，评估体系必须是软件中持续维护的活体部分。最终结论指出，代理失败的原因通常不是不会写SQL，而是不理解数据的含义、流向及变更后果。通过提取、计算并持久化上下文，代理从“仅阅读代码”进化为能实际操作数据系统的智能体。

"The agents don't really fail at data engineering or data task because they can't read or write SQL... They do a very good job of that. They fail because they don't have or they don't understand what the data actually means, how it flows, or what breaks when it changes."

总结与过渡

演讲者强调了将上下文作为一等公民的重要性，指出通过图结构高效查询已持久化的上下文，是跨越从代码阅读到系统操作鸿沟的关键。随后，演讲者将舞台交给Brandon进行实操工作坊演示，并简要回顾了前文提到的五大模式作为理论铺垫。整个部分旨在确立数据上下文层在AI代理架构中的核心地位，为后续的技术落地展示奠定概念基础。

构建代码智能体的数据上下文层：从痛点到实践

本次演讲由 Typedef 的 Brandon Callender 主讲，旨在通过实际操作演示如何为编码智能体（Coding Agent）构建一个真实的上下文层。演讲者指出，当前会议中许多讨论都围绕着一个核心观点：智能体的表现取决于你赋予它的上下文质量，而构建这种上下文本身就是实际的工作任务。在接下来的环节中，团队将基于 Quadrant 代码库，共同构建一个具体的上下文层。Brandon 强调，即使开发了强大的工具，如果无法引导智能体有效使用这些工具，努力也将付诸东流。获取智能体实际使用工具的权限和机制，才是真正的工作难点所在。为了便于听众跟随，演讲者提供了包含 Jupyter Notebook 的 GitHub 仓库，支持使用 Docker Compose 运行 Neo4j 图数据库，并可选配 Open Router API Key 进行在线 LLM 测试。

文本搜索的局限性：缺乏结构化的身份认知

演讲从编码智能体最基础的起点——文本搜索（Text Search）开始分析。当用户询问代码中名为 posting_list 的结构体时，基于 ripgrep 的搜索会返回多个精确匹配项以及十几个相似名称（如 posting_list_view、posting_list_iterator 等）。智能体在没有额外上下文的情况下，只能随机选择其中一个进行探索，这可能导致错误的方向或需要反复回溯。Brandon 指出，文本本身无法传达代码的结构化信息，例如哪些方法使用了该符号、它在哪个 crate 中定义或它的具体身份标识。这些关键信息隐藏在代码的结构而非单纯的文本字符串中。如果智能体每次运行都重新读取整个系统而没有任何记忆，不仅成本高昂（重复读取相同文件），而且极其脆弱。智能体可能会以不同的顺序读取文件，或者因先读入某个误导性文件而陷入错误的推理路径。因此，工程化上下文的核心目标并非仅仅提高准确率或效率，而是引入确定性（Determinism），以对抗智能体固有的非确定性行为。

上下文分层理论：从原始字符串到图数据库

为了解决上述问题，演讲者引入了上下文的层级概念。第一层是原始的文本搜索（Glob/Grep），仅包含无结构的原始字符串；第二层则是当前大多数 RAG 解决方案所处的阶段，包括语义搜索、代码嵌入和词法索引。然而，要构建真正稳健的代码智能体上下文层，需要更深层次的抽象。我们需要提取代码中的符号（类型、特征、函数）及其真实身份和位置，并计算它们之间的关系边。这些关系在图数据库中被预先计算一次，随后被多次查询。这种方法与处理复杂数据架构的思路一致：提取（Extract）、持久化（Persist）和查询（Query）。通过这种方式，智能体不再需要每次猜测代码结构，而是基于一个持久且可信的代码模型进行交互。Brandon 提到，虽然业界正在讨论更高级的上下文层级（如四层或五层），但掌握从原始文本到结构化图数据的这一基础跃迁，是构建可靠编码智能体的关键一步。

语义搜索的局限与图遍历的必要性

在构建代码理解系统时，传统的语义搜索（Semantic Search）虽然能返回按相关性排序的结果列表，但其本质仍是一个扁平的列表。这种结构无法展示不同代码片段之间的关系（Relationships），导致系统难以理解复杂的上下文。因此，作者提出将“可遍历图（Traversable Graph）”作为最高层级的理解方式。这种层级通过链接具有真实身份的符号，并在它们之间添加类型化边（Typed Edges），使得智能体能够真正地在代码库中进行路径遍历和逻辑推导。

"semantic search, you get ranked results... But at the end of the day, that's still going to be a flat list. It's not going to show you the relationships between these different code."

为了构建这样一个能回答代码库问题的智能体，需要逐步搭建不同层级的上下文理解。这一过程被划分为多个阶梯（Rungs），从最基础的语法解析开始，逐步深入到语义关联和最终的结构化图谱构建。

阶梯零：基于 Tree-sitter 的语法解析

阶梯零（Rung Zero）代表的是代码理解的句法层面（Syntactic Level）。这一层的核心任务是对目标代码进行解析，获取高层次的抽象语法树（AST）分解。作者推荐使用语言无关的工具 Tree-sitter 来实现这一目标，它能提供代码库各部分及其交互的基本视图。然而，仅停留在句法层面存在显著缺陷：它无法处理符号冲突（Collisions）。例如，在 posting_list.rs 和 quant.rs 中分别定义的名为 "PostingList" 的符号，在阶梯零看来是完全相同的实体。这种歧义性使得系统无法区分不同模块中同名但功能不同的代码结构，从而限制了理解的深度。

阶梯一：基于 rustdoc 的符号解析与消歧

阶梯一（Rung One）的核心目标是解决解析（Resolution）问题，这是大语言模型（LLM）难以独立完成的任务。通过引入 rustdoc 生成的 JSON 数据，系统能够将阶梯零中模糊的符号转化为具有唯一身份标识的类型。以 Rust 语言为例，编译器本身提供了强大的解析能力，使得这一过程相对“作弊”般轻松。通过 rustdoc 的信息，系统可以明确区分两个同名的 "PostingList"：一个是位于 posting_list.rs 的定义，另一个是位于其他位置的导出或重定义。这一层级确保了符号的唯一性（Distinct Identifiable Types），为后续建立准确的代码关系图谱奠定了确定性基础。

"resolution is the one thing that GP can't really do, right? It's the thing that turns those two ambiguous posting lists into two distinct identifiable types."

阶梯二：语义分类与 LLM 的介入潜力

阶梯二（Rung Two）旨在挖掘提取信息的实际含义，即从确定性的语法和解析数据中提炼出语义（Meaning）。前两个阶梯完全基于确定性方法，而这一层则探索如何利用 LLM 的优势进行分类和总结（Classify and Summarize）。作者指出，与其将所有原始数据扔给 LLM 让其自行理解，不如先通过 Tree-sitter 和 rustdoc 构建坚实的数据基础，再辅以 LLM 进行高层级的语义标注。虽然在本节演示中主要聚焦于前两个阶梯，但作者提到后续将展示如何利用 LLM 增强对代码意图的理解。

案例演示：PostingList 的解析差异与图谱构建

在 Jupyter Notebook 的实际操作中，作者展示了如何从五个 Crate 的样本代码中提取数据。通过对比阶梯零和阶梯一的结果，可以清晰看到差异：在阶梯零中查询 "PostingList" 只能看到一个导出版本，无法追溯其原始定义位置；而在阶梯一中，系统能够明确指出该符号的规范位置（Canonical Location）及其具体的文件路径和行号。这种能力使得智能体能够追踪跨 Crate 的重导出（Re-export）关系，并链接回原始定义。此外，作者还演示了基于全量文本搜索的索引构建，指出虽然这能提供有用信息（如结构体定义），但仍缺乏符号间的链接关系（Linkages），从而进一步论证了构建可遍历图的必要性。

"it's still not going to tell us the linkages between those different things, right? And the agent can infer that..."

作者强调，虽然本次演示主要使用 Rust 以利用其编译器优势简化开发，但代码库中也提供了 Python 语言的示例笔记本。这表明该分层架构具有通用性，旨在解决跨语言代码理解中的共性问题：即从扁平的文本或语法树中，构建出具有丰富关系和语义的结构化知识图谱。

构建代码知识图谱以消除歧义

在开发 AI Agent 处理复杂代码库时，最大的挑战在于符号的二义性。例如，posting_list 可能是一个结构体（struct），也可能被重新导出。如果仅依赖文本搜索，Agent 容易做出错误的逻辑跳跃，导致执行路径完全偏离。数据上下文层的核心第一步是构建图数据库。团队提取代码中的符号和元信息，将其转化为节点（Nodes）和边（Edges），并加载到 Neo4j 图数据库中。这种结构化的表示方式让代码库中的引用关系变得可视化且可查询，为后续的工具开发奠定了坚实基础。

"So that's probably the basis of it. But you don't want it to have to make that logical leap every single time because it's going to be that one time where it gets it wrong..."

利用图查询实现精确的爆炸半径分析

有了图谱后，团队开发了专门的工具来Harness（利用）图的能力。其中一个关键工具是爆炸半径分析（Blast Radius）。当用户询问“修改某个函数会破坏什么”时，Agent 不再需要跨文件猜测，而是通过传入限定名（Qualified Name），在图中遍历依赖边。这种基于图的路径分析能够精确识别所有受影响的符号，解决了传统方法中因同名不同义导致的冲突问题。例如，两个名为 posting_list 的结构体虽然名称相同，但通过规范化的解析（Canonical Resolution），Agent 能明确区分它们各自的依赖树，从而给出截然不同的破坏性分析结果。

"Changing one posting list is not going to in fact the same level of changes if you impact change the other posting list. So even though these things have the same underlying name..."

Agent 工具链与语义增强的进阶探索

基于上述图谱，团队构建了一个简单的 Pydantic Agent，通过系统提示词赋予其调用工具的能力。Agent 能够执行 Cypher 查询来检索依赖信息，例如找出修改 posting_list 后所有受影响的符号及其文件行号。演示显示，Agent 会通过多次工具调用（如先搜索再查爆炸半径）来构建对代码库的理解。这种确定性查询证明了图 Schema 设计的合理性：只要意图清晰，生成对应的查询语言并不困难。此外，团队还展示了更高级的“第二阶梯”能力：允许 Agent 根据自然语言请求（如“找出实现某 Trait 的所有 Struct”）自动生成 Cypher 查询，无需人工编写代码。

"So now if you go ahead and run this agent, this agent will actually spend a few turns um calling the tools and trying to figure things out..."

引入 LLM 进行语义嵌入与分类

最后，团队介绍了第三阶梯：语义意义（Semantic Meaning）。除了确定性的结构数据，还需要理解代码的意图。团队使用了开源库 Fenic（一个结合传统 DataFrame 操作与 LLM 的库）来处理这一任务。通过配置 OpenRouter，Agent 可以提取 Rust 项的种类、限定名和文档字符串（Doc String），并让 LLM 用一句话总结该 Rust 项的功能。这种将结构化数据与语义嵌入结合的方法，为 Agent 提供了更深层次的理解能力，使其不仅能知道代码在哪里，还能理解代码是做什么的。虽然演示中未完全展开第二阶梯的所有功能，但已展示了从确定性图查询到语义理解的完整技术路径。

"The third rung I was talking about was the actual semantic meaning. um you can actually have an LLM summarize these symbols and uh embed them..."

静态上下文图的审计优势与运行时更新策略

在构建面向 Agent 的数据上下文层时，核心思路是将 LLM（大语言模型）对代码库行的摘要输出烘焙进知识图谱中，使 Agent 能够直接获取这些结构化信息。这种方法的显著优势在于其可审计性（Auditable）：当生成摘要时，如果开发者发现某段函数解释错误，可以立即修正。相比之下，若依赖 Agent 在运行时动态推断功能，往往要等到代码生成失败后才能发现错误，滞后性极强。关于图谱的维护机制，演讲者指出理想状态下应基于主分支（main）缓存并保存为规范形式。在本地开发中，增量刷新（Incrementally Refreshed）是保持局部副本同步的关键策略。通过仅追踪和重新索引发生变化的部分，而非全量重建，可以在代码库规模扩大时有效平衡维护成本与性能收益。随着需要索引的上下文量增长，实时计算的边际成本急剧上升，因此智能增量更新变得尤为必要。

运行时上下文的价值与产品定位差异

在Agent实际运行（Runtime）阶段，利用预构建的图上下文工具能发挥最大效用。当Agent执行任务时，它会查询所有已构建的工具，此时实时查询能力成为核心价值所在。这种机制允许Agent在运行时动态获取信息，而无需一次性重新推导所有数据。避免重复计算是提升效率的关键。然而，在评估此类系统时，不能简单套用NL2SQL（自然语言转SQL）基准测试如Bird或Spider的标准。因为该产品的核心目标并非直接生成分析性SQL查询，而是侧重于数据工程侧的支持。虽然业界普遍追求Text-to-SQL能力，但更关键的是构建能让用户信任Text-to-SQL结果的工具链。重点在于协助维护数据架构的日常作业，而非仅仅优化查询编写能力。

工具效能与Agent“肌肉记忆”的冲突

尽管预计算的代码库图上下文工具能在单次调用中完成传统方法需多次迭代才能达成的任务，但Agent往往不会主动使用它。实验显示，即使提供了预计算的、可遍历的代码库模型以及强大的图工具，Agent仍倾向于使用grep和读取文件等传统方式。这是因为模型在训练过程中形成了强烈的工具调用肌肉记忆。正如演讲者所言：“你无法仅通过提供更优秀的工具来对抗这种反射。” 模型被训练为在特定情境下调用grep和读取文件，这种根深蒂固的行为模式使得Agent即便面对更高效的图工具，也会因困惑或习惯而退回旧路径。这类似于人类用户：强行改变其使用习惯往往导致抵触，而非效率提升。

顺应模型习惯的提示工程策略

要解决Agent不使用新工具的问题，不能硬碰硬地对抗其先验经验，而应顺应并引导模型的既有习惯。具体策略包括：将图查询工具命名为“search”，因为模型在无训练情况下总会以多关键词搜索的方式使用名为search的工具。同时，返回结果的结构和格式必须与模型熟悉的工具（如grep）保持一致。模拟熟悉工具的响应结构能让Agent无缝处理新数据，无需通过提示工程强行改变其自我认知。此外，工具必须在第一次调用时就提供高价值回报。如果Agent首次搜索无果或结果不佳，它会认为工具失效并永久放弃该路径。因此，确保工具每次调用都能返回即时且有用的结果是防止Agent退回旧习惯的关键。

评估体系与验证必要性

由于上述行为模式的复杂性，仅仅构建工具是不够的，必须建立严格的评估体系（Evals）来验证Agent是否按预期使用新工具。演讲者指出，构建图上下文本身可能只需一下午，但让Agent真正使用它才是最难的部分。这需要大量的提示工程、迭代和评估工作。通过专门的 Notebook 案例，可以聚焦于如何证明Agent确实执行了预期的操作路径，而非仅仅依赖工具本身的理论性能。这种评估不仅关乎准确性，更关乎行为引导的有效性。只有通过严谨的验证，才能确认新工具是否真正融入了Agent的工作流，从而在实际应用中实现超越传统方法的效率提升。

基准测试环境与数据构建策略

在评估新开发的 Graph Tools（图工具）与传统文件探测工具时，团队首先构建了严格的测试环境。评估基于一个包含 30 个真实任务问题的语料库，这些问题经过精心设计：有的专门针对图结构的优势设计（如查询公共类型变更的影响），有的则适合传统方法，还有控制组问题用于基准对比。为了确保评估的公正性，黄金数据（Gold Data）并非直接来自图输出，而是通过交叉引用源代码验证得出，从而防止上下文污染或作弊。评估过程在后台运行了一整夜，设置了 5 次重试机制以捕捉不同随机性下的表现。正如演讲者所强调的，理想的评估问题应当具备确定性评分标准，避免依赖另一个大模型去评判前一个模型的“观点”，因为这种非确定性评分会导致方差增大、成本上升且结果不可靠。

评估架构与工具对比设置

为了量化新工具的效用，团队使用 Pydantic Evals 构建了评估框架。该架构包含两个核心代理：一个是拥有相同模型访问权限并集成新 Graph Tools 的“图代理”，另一个是作为对照组的控制代理，它使用由 Pydantic 维护的传统文件系统探测工具。评估器通过比较代理的实际响应与预期的黄金答案来打分。这种结构化的对比方法不仅揭示了新工具在单次任务中的表现，更关键的是它能追踪长期使用的稳定性。通过这种设置，团队能够明确区分工具在特定场景下的优势以及未来需要改进的方向。评估的核心逻辑在于检查代理是否引用了所有预期的证据，这是一种确定性的验证方式，而非模糊的主观判断。

性能数据：Pass@K 与 Token 效率分析

在具体的运行结果中，团队采用了两种不同的统计指标来衡量代理的表现。首先测试的是 Pass@K 指标，即在一组测试中是否“曾经”正确过。在这种宽松的标准下，传统 Graph 代理略占优势或两者持平，因为图工具仅访问公共变量而忽略私有部分，导致在某些控制问题上表现稍弱。然而，当指标转变为更严格的 Pass@K（每次运行都正确） 时，结果发生了彻底反转。图代理在连续五次运行中均能给出正确答案的概率是传统 Graph 代理的两倍。这一数据表明，虽然新工具在单次尝试中可能不总是最优，但其一致性和可靠性显著更高。此外，效率方面也有显著提升：图方法平均消耗的传统 Graph 代理约三分之一的 Token（即减少了约 3.1 倍），这在大规模自动化编码场景中意味着巨大的成本节约。

工具采用率评估与结论

除了准确性和效率，演讲者还强调了如何衡量代理对特定工具的采用率。这需要编写专门的评估脚本，检查执行轨迹（Trace）中工具调用的频率。例如，即使提示词中没有明确指令使用新工具，通过评估也能发现代理是否自发地选择了更高效的路径。这种基于轨迹的分析是验证新工具实际落地效果的关键环节。最终，评估的目的不仅是证明某次测试的成功，而是确保在重复调用（如 10-20 次）中保持一致的正确率。通过这种多维度的评估——包括确定性评分、Pass@K 一致性以及 Token 消耗效率——团队能够科学地证明 Graph Tools 在长期、高频使用的编码代理场景中的优越性，并为后续的迭代优化提供数据支持。

构建诚实且具挑战性的评估体系

在Agent开发中，评估（Evals）是理解Agent是否正确使用工具的唯一途径。演讲者分享了一个具体案例：通过调整提示词，将工具的使用率从34%提升至72%。为了验证这一改进，他们设计了针对同一问题、相同工具集但不同提示词的测试场景。理想的“引导”后，Agent应主动执行搜索并使用get_symbol获取确切答案，而非盲目抓取数据。构建坚实评估体系的核心配方包括：从真实任务语料中挖掘候选案例、建立尽可能确定性的锚定评分器，并首先对评分器本身进行单元测试。推荐使用如pantic eval等工具，其核心结构均包含数据集、案例和评估器。关键在于多次运行评估并报告Pass@K等指标。更重要的是，必须故意加入Agent可能不擅长的案例，避免其获得100%通过率。>

数据上下文层与元数据目录的互补关系

在构建企业级 AI Agent 时，数据上下文层（Data Context Layer）与传统的 元数据目录（Data Catalog）并非冗余替代关系，而是回答不同维度的问题并协同工作。元数据目录提供的是关于数据仓库中“存在什么”的固定且静态的理解，而上下文图（Context Graph）则致力于从代码和数据中动态提取更丰富的语义关联。两者共存，目录为上下文图提供基础事实支撑。

以 dbt 项目为例，系统首先解析 SQL 代码并构建模型与物理表（如 Snowflake 中的表和视图）的映射关系。随后，系统会查询元数据目录，获取该物理表的列信息、配置文件（profiles）等Essential 的结构化数据。正如演讲者所言：> "I think they coexist you read information from the catalog to form the context graph"（我认为它们共存，你从目录中读取信息以形成上下文图）。这种结合确保了 Agent 既能理解代码逻辑，又能掌握底层数据的详细定义和统计特征。

数据工程 Agent 的评估场景设计：从 Bug 修复到根因分析

为了验证 AI Agent 在数据工程任务中的有效性，Typedef 采用了基于真实代码库和注入缺陷（Diff）的评估策略。核心场景包括基础的 Bug 修复以及更复杂的逆向根因分析。在基础场景中，向代码库注入一个引入 Bug 的 Diff，要求 Agent 定位并修复。评估重点在于验证 Agent 是否检查了正确的依赖路径，避免“头痛医头”式的上游或下游错误修复（Band-aid fix）。

在更具挑战性的场景中，评估者不提供具体模型名称，而是描述现象（如“仪表盘 Y 的数值翻倍”），迫使 Agent 自下而上地回溯依赖树，找到真正的根因模型。这种设计旨在测试 Agent 在缺乏明确指引时的推理能力。评估的难点在于防止 Agent “作弊”，例如通过查看 Git 分支名或回退到主分支来推断问题来源。因此，评估框架必须经过硬化处理（Hardening），以模拟真实且封闭的开发环境。

评估框架的现状与挑战：ADE Bench 与数据一致性难题

目前，ADE Bench被视为该领域的行业基准测试框架之一。它采用类似的方法：在仓库中注入问题，要求 Agent 结合代码和数仓数据进行修复。然而，构建此类基准测试的最大障碍在于基础设施的脚手架（Scaffolding）。

与纯代码评估不同，数据工程评估需要一个运行中的、包含正确错误数据的数据库。必须确保生成的测试数据集在内部逻辑上保持一致，避免 Agent 因数据时间范围不一致（如仅生成 2024 年数据）而产生幻觉或困惑。目前，缺乏一个大规模且标准化、可供他人复现的基准数据集。尽管已有框架存在，但在构建足够大且数据一致性高的测试集方面，行业尚未达到令人满意的标准化程度。这限制了评估结果的广泛可比性和可靠性。

工具采用率与确定性：超越单次准确率的关键指标

评估的最终目的不仅是提升 Agent 的单次回答准确性（Per-shot accuracy），更在于确保其行为的确定性（Determinism）和工具的实际采用率。多次运行评估显示，随着 Agent 使用工具能力的增强，其在回答同一组问题时的一致性显著提高。然而，最关键的性能指标并非单纯的准确率提升，而是 Agent 实际调用新工具的比例。

演讲者强调：> "An elegant tool that gets reached for a third of the time is just a third of a tool"（如果一个优雅的工具只被使用了三分之一的时间，那它只是三分之一的工具）。这意味着，如果 Agent 具备使用高级上下文层的能力却选择不使用，该能力在工程实践中并未产生价值。因此，评估体系必须重点关注工具采用率（Adoption numbers），确保 Agent 在需要时能够稳定、可靠地调用所需工具，从而实现从“有能力”到“被使用”的闭环。

评估陷阱与“图”的意外胜利

在构建代理工具时，开发者常陷入一种误区：认为只要持续优化和增加测试，就能证明新工具的优越性。然而，演讲者分享了一个令人沮丧却关键的发现：运行评估的结果显示，“图”（Graph）与直接让大模型生成代码（GP, Generate Code）的效果持平。这种结果违背了开发者希望证明新架构更优的初衷，但也揭示了一个重要真相：与其试图“战胜”GP，不如顺应其本能。代理天生倾向于直接生成代码，如果强行对抗这一趋势，只会陷入沉没成本陷阱。因此，设计的核心不应是阻止代理使用GP，而是通过设计让代理更顺畅地利用现有工具。这种“顺势而为”的策略比强行工程化更有效，因为它尊重了模型当前的行为模式。

评估数据的虚假繁荣与深度审查

演讲者强调，切勿盲目信任评分板（Scoreboard）。他曾多次在演示前重新运行评估，结果导致整个结论发生反转。原因在于初始的评估设置存在缺陷：例如，某个工具返回的文件路径不正确，导致代理在搜索时进入死胡同。如果仅看最终得分，可能会得出“图优于GP”的错误方向性结论。必须深入查看追踪日志（Traces），如使用Logfire等工具检查代理的实际执行路径。只有发现并修复这些底层架构中的错误（如错误的文件引用），才能构建出更严格的评估流程。正确的做法是：阅读追踪记录、找到错误点、加固测试框架，然后重新运行。简单的分数提升掩盖了架构中的重大隐患。

从Rust到Python：代码图的扩展性挑战

为了验证工具的有效性，演讲者选择使用Rust作为初始测试案例。这是因为Rust编译器已经完成了部分工作（如类型检查），相当于“预作业”，使得问题相对简单。在Rust中，查找实现特定接口的代码非常容易（如搜索impl）。然而，当扩展到Python时，情况变得复杂得多。Python代码库庞大且结构松散，直接让GP处理可能导致代理陷入数万个客户端的混乱中。此时，代码图（Code Graph）的优势凸显出来。对于结构较差的语言或大型项目，代码图比直接GP更有效。关键在于数据摄入（Ingest）过程的模块化设计。通过构建灵活的摄入流程，可以将不同语言和项目的代码数据整合到一个统一的图中，从而支持更广泛的适用性。

语义层：从结构连接意图理解

代码图不仅提供结构信息（什么连接到什么），还需要补充语义层以解释“为什么”。通过整合代码注释、文档字符串等信息，可以还原开发者的意图。演讲者建议添加小的处理步骤（如逐行摘要），使搜索不仅能返回代码位置，还能回答“这段代码是做什么的”。这种对意图的理解对于代理准确使用工具至关重要。虽然具体的实现细节（如Python摄入笔记）未在演讲中展开，但核心逻辑是：结构决定连接，语义决定理解。只有将两者结合，代理才能更智能地利用上下文。

核心策略：拆解大任务为小问题

在构建面向Agent的数据上下文层时，关键在于建立一种可审计的语义分析机制，该机制需建立在确定性结构分析之上。作者强调，处理复杂代码库时不应试图让大语言模型一次性回答一个宏大而模糊的问题。相反，正确的做法是提出许多小而具体的问题。如果直接将包含10个字段的SQL模型扔给LLM并要求其提取所有信息，模型极大概率会产生幻觉、编造数据或遗漏关键细节。因此，必须将代码块拆解为更小的部分，针对每个小部分提出特定的问题，从而发挥模型在分类和摘要方面的优势。这种策略的核心在于将确定性解析与聚焦的语义操作相结合。通过先对代码结构进行确定性的语法分析，再针对解析出的具体元素（如单个字段）询问其类型、注释及语义角色（是度量值还是维度），可以确保Agent获得准确且可验证的输入。

实施路径：从结构提取到语义增强

这一方法论的具体实践依赖于特定的工具库（如Fenic），其设计初衷正是为了支持这种小规模、基于事实且可审计的语义操作。实施过程遵循一个清晰的阶梯式路径：首先，从代码库中提取最基础的结构信息；其次，在此基础上叠加语义理解层。例如，在分析SQL时，系统先确定列的结构属性，然后引导Agent对该特定列进行分类和总结。为了进一步提升单个问题的回答质量，不应向模型塞入更多杂乱的问题，而是应为单一聚焦问题提供更丰富的上下文输入。这种分层架构的最终目标是构建一个Agent能够深入理解并安全进行修改的代码基底。通过这种方式，系统不仅能识别代码片段，还能理解其背后的业务含义和逻辑关联。

进阶应用：跨代码库与多源数据融合

当基础结构搭建完成后，可以进一步构建更强大的编码代码库图分析Agent。这类高级应用可以利用调用链（call graphs）来追踪函数间的依赖关系，并整合代码内外的多种数据源。具体而言，Agent可以读取代码注释、GitHub Issue以及Linear工单等外部上下文信息。这种多源数据的融合使得Agent的理解更加 grounded（接地气/有依据），从而在实际开发场景中提供更有价值的辅助。然而，这种跨边界分析并非易事。在涉及微服务或不同语言（如Python与Rust）交互的场景中，难点在于准确界定边界。例如，需要编写专门的分类器来理解Rust代码如何调用Python代码（或反之），以建立两者之间的链接层。虽然理论上可行，但这需要投入大量额外工作来解析复杂的跨语言或跨服务边界。

技术挑战：计算成本与增量式扩展

在规模化部署此类系统时，存储并非主要瓶颈，真正的挑战在于图分析所需的计算资源。随着代码库的增长，生成的图谱会迅速变得庞大且复杂（sprawly），垃圾回收也变得困难。因此，在扩展过程中，必须重点关注增量式重建（incrementalism）策略。即如何在不重新生成整个图谱的情况下，仅对变更部分进行更新和分析，以控制计算开销。此外，关于检索增强生成（RAG）与结构化分析的区别也值得注意：像Cursor等工具主要依赖语义搜索和向量嵌入来定位代码位置，这虽然能有效找到相关片段，但Agent仍需逐一检查这些片段。而结构化图分析的目标是在一步操作中直接呈现函数的所有调用点及其语义背景，无需Agent手动遍历大量搜索结果。这种从“查找”到“直接理解”的转变，是提升Agent工作效率的关键所在。

增量索引是应对大规模数据架构的核心策略

在构建跨越大型数据架构的Agent系统时，开发者面临的最大痛点之一是避免对数据仓库进行高频次的重复查询。例如，如果系统需要执行500次查询或重新编译所有SQL代码，效率将极其低下。因此，设计必须优先考虑增量索引（Incremental Indexing），将其视为一等公民处理。Brandon Callender指出，解决信息同步（Sync）问题必须优先于存储或计算层面的扩展性问题。只有先确保数据更新的实时性和一致性，才能有效应对后续的大规模扩展挑战。这种架构思维旨在让系统能够随着数据的流入动态更新索引，而非每次请求都重新扫描整个数据集。

黄金测试集应基于代码快照以保持评估确定性

在维护“黄金数据集”（Golden Dataset）时，最大的难题在于代码库的持续变更会导致测试用例失效。针对这一问题，Yoni Michael提出了一种基于特定代码快照（Snapshot）的评估策略。他认为，为了获得确定性的测试结果，应该固定一个特定的代码版本作为基准。这样，评估问题（Evals）也是固定的，从而确保Agent在回答相同任务时表现的一致性。改变测试问题以适应不断变化的语料库并不能真正反映Agent能力的提升。相反，让Agent在相同的固定任务上反复表现，才是衡量其是否进步的最佳方式。即使代码重构后某些旧Bug不再存在，该测试用例依然有效，因为它验证的是Agent在特定情境下修复问题的能力，而非对当前代码状态的即时反应。

知识图谱与本体层赋予Agent高层语义理解能力

Typedef的产品核心在于构建上下文图（Context Graph）和本体层（Ontology Layer）。这一层级旨在围绕数据架构组织所有信息，明确数据的指向、位置及含义。通过提供这些高层构建块（Higher Constructs），Agent能够以类或对象的概念与LLM进行交互，而非仅仅处理底层数据。这种设计使得Agent不仅能回答关于数据架构的问题，还能在受控范围内进行修改操作。这与Neo4j等知识图谱工具的理念相似，但Typedef更强调为Agent提供经过语义关联的工具集。对于拥有复杂第三方SaaS（如Salesforce）和内部系统的团队来说，一次性定义语义关系并建立版本控制是关键。这不仅为AI Agent提供了分析上下文和偶尔回写数据的工具，也为人类用户（如新员工入职）提供了一站式的系统文档和交互界面。

构建统一的数据上下文图以替代传统语义层

Typedef 的核心愿景是整合企业内分散的数据架构，包括 Airflow 等工具生成的元数据，将其融合为一个单一且可遍历的上下文树或上下文图。这一架构旨在让 AI Agent 能够基于该图谱进行推理，从而精准定位数据源头。传统的数据语义层（Semantic Layer）虽然构建初期效果显著，但维护成本极高，被称为“噩梦”，因为每次模型更新都需要人工介入调整。Typedef 试图解决这一痛点，通过构建一个从 Salesforce 到 BI 报表层的全链路数据流向追踪能力，实现自动化的上下文理解。这种统一视图使得系统能够清晰地展示数据是如何从源头经过多层处理最终呈现在报表中的，从而为上层应用提供坚实的数据基础。

利用数据血缘实现自动化的故障根因定位与工单路由

在业务场景中，当分析师发现报表数据异常时，传统流程往往涉及繁琐的跨部门沟通。Typedef 的目标是让业务人员能够直接向 Agent 报告问题，例如指出某个 Dashboard 数据错误。Agent 随即介入，自动追溯多层背后的逻辑链条。例如，当被问及应收账款（AR）数据的来源时，Agent 可以明确指出数据源自 Stripe，随后与 Salesforce Lead 数据进行关联计算。通过这种深度的血缘追踪，Agent 不仅能识别出问题所在（如某处 SQL 查询错误），还能检测到负责该模型的具体团队。这种能力将原本需要人工排查的复杂过程自动化，使得 Agent 能够直接生成包含根因分析和解决方案建议的工单。

消除沟通壁垒，实现从问题发现到修复的高效闭环

Typedef 致力于成为业务人员（如会计师、分析师）与数据工程师之间的翻译层和桥梁。在传统模式下，一个错误报告可能在五个不同团队间流转，耗费大量时间。而通过 Typedef 的上下文图，Agent 能够立即理解问题本质并直接路由至正确的责任团队。更理想的情况下，如果产品功能完善，目标团队可以直接采纳 Agent 提出的修复方案（如“Check plus”）并实施。这种机制不仅减少了沟通噪音，还通过捕获 Airflow 运行记录等运行时信息来辅助定位变更历史（如上周提交的代码更改）。最终目标是实现一个高效、自动化的数据治理闭环，让业务人员无需依赖人工协调即可快速解决数据质量问题。

结论

Typedef的“数据上下文层”通过图结构持久化代码与数据的语义关联，显著提升了AI智能体在企业级数据工程中的可靠性。基准测试显示，该架构使复杂任务成功率提升近35个百分点，且在严格的一致性评估中表现优于传统文件探测工具。其核心优势在于通过预计算消除歧义，实现精准的影响分析与安全变更推荐。

然而，技术落地面临两大挑战：一是需克服模型固有的工具调用习惯（如偏好grep），通过顺应而非对抗的策略引导使用；二是评估体系需从单次准确率转向长期一致性与工具采用率。该方案适用于高复杂度、强依赖血缘关系的数据场景，但需解决增量更新成本及跨语言扩展的工程难题。