How we built LangChain’s agent-first data stack我们是如何构建 LangChain 的“代理优先”数据栈的

How we define the data models我们如何定义数据模型

dbt is one of the main places where we manage context about our data models. That context exists in both SQL and written definitions.dbt 是我们管理数据模型背景信息的主要场所之一。这些背景信息既存在于 SQL 代码中，也存在于文字定义中。

Every table and column should help a person understand what the data represents, how it should be used, and where the edge cases are. Those same definitions also help the agent.每一张表和每一列都应帮助人们理解数据所代表的含义、使用方法以及边缘情况。这些定义同样有助于代理理解。

A weak column definition might say:一个薄弱的列定义可能是这样的：

account_status: The status of the account.account_status: 账户状态。

That is technically accurate, but it does not tell the reader much.这在技术上是准确的，但对读者来说信息量很少。

A stronger definition would say:一个更强的定义应该是：

account_status: The current lifecycle status of the account in Salesforce. Active means the customer has an active paid contract. Churned means the customer previously had a paid contract that has ended. Prospect means the account has not yet become a customer. For customer reporting, filter to Active unless the analysis explicitly includes churned or prospective accounts.account_status: 账户在 Salesforce 中的当前生命周期状态。Active 表示客户拥有有效的付费合同。Churned 表示客户之前的付费合同已结束。Prospect 表示账户尚未成为客户。在进行客户报表分析时，请过滤为 Active，除非分析中明确包含 Churned 或 Prospect 账户。

This definition gives the agent business context, allowed values, interpretation guidance, and a default filtering rule. It also reduces the chance that someone gets a technically correct answer based on the wrong business interpretation.这个定义为代理提供了业务背景、允许的值、解读指南以及默认的过滤规则。它还降低了因错误的业务解读而导致得到技术上正确但实际无用的答案的几率。

We apply the same approach at the table level. A good table definition should explain what grain the table represents, what kinds of questions it is designed to answer, and where people should be careful.我们在表级别也采用了相同的方法。一个好的表定义应该解释该表代表的数据粒度、旨在回答的问题类型，以及人们需要注意的事项。

The semantic model defines metrics and relationships语义模型定义了指标和关系

The semantic model gives the agent context about metrics and how models relate to each other.语义模型为代理提供了关于指标以及模型间如何关联的背景信息。

This is where we define concepts like ARR, pipeline, active usage, customer health, and other metrics that people ask about repeatedly. The semantic layer helps keep those definitions consistent, so the agent does not need to infer metric logic from scratch every time someone asks a question.我们在这里定义了 ARR、流水线、活跃使用量、客户健康度以及人们反复询问的其他指标。语义层有助于保持这些定义的一致性，因此代理无需在每次有人提问时都从零开始推断指标逻辑。

A semantic model is most useful when it sits on top of solid data modeling. If the underlying models are unclear, duplicative, or poorly documented, the semantic layer can only do so much. We found that the foundations still matter. Clean models, clear grains, and good definitions lead to higher quality at every downstream layer.语义模型只有建立在扎实的数据建模之上才最有效。如果底层模型不清晰、重复或文档记录不佳，语义层的作用将非常有限。我们发现基础依然重要。整洁的模型、清晰的粒度以及良好的定义能提升下游每一层的数据质量。

Capturing business context捕获业务背景

Some context might not belong neatly in a table or metric definition.有些背景信息可能无法整齐地归纳在表或指标定义中。

There are company processes, team-specific workflows, reporting conventions, and business rules that need more room. These would be like skills for the data agent. We use Hex workspace guides for this. They give the agent written instructions about parts of the business, specific metrics, common workflows, and how people should interpret certain data. We manage these guides in a GitHub repo that syncs directly into Hex. That lets us version them, review changes, and keep the context close to the rest of our data documentation.公司流程、团队特定的工作流、报表惯例和业务规则需要更多的空间。这些就像是数据代理的“技能”。我们为此使用 Hex 工作区指南。它们为代理提供了关于业务部分、特定指标、常用工作流以及人们应如何解读特定数据的书面说明。我们在一个同步到 Hex 的 GitHub 仓库中管理这些指南。这使我们能够对其进行版本控制、审查更改，并将背景信息与其余的数据文档保持一致。

A guide might explain:指南可以解释：

• How we define pipeline for weekly GTM reporting我们如何为每周 GTM 报表定义流水线
• Which dashboards are considered canonical for a given metric哪些仪表盘被视为特定指标的权威来源
• How to interpret product usage across different deployment types如何解读不同部署类型下的产品使用情况
• What filters to apply when analyzing customer health分析客户健康度时应应用哪些过滤器
• When a question should be routed to the data team for validation何时应将问题转交给数据团队进行验证

This layer has been especially useful because it lets us write business context in plain language, without forcing every detail into a model or column description.这一层尤其有用，因为它让我们能够用通俗的语言编写业务背景，而无需强行将所有细节塞进模型或列描述中。

Endorsements tell the agent what to trust背书（Endorsements）告诉代理什么值得信任

Endorsements help the agent understand which data sources and assets are trusted.背书有助于代理了解哪些数据源和资产是受信任的。

For example, if the ARR dashboard is endorsed, the agent can use that dashboard and the logic behind it when answering a question about ARR. Endorsement is an important signal because companies often have multiple tables, dashboards, or historical queries that touch the same concept. Without a trust signal, the agent may choose an asset that looks relevant but is not the best source.例如，如果 ARR 仪表盘被背书，代理在回答有关 ARR 的问题时可以使用该仪表盘及其背后的逻辑。背书是一个重要的信号，因为公司通常有多个表、仪表盘或历史查询涉及同一个概念。如果没有信任信号，代理可能会选择一个看起来相关但并非最佳来源的资产。

We keep guardrails around endorsements so they stay meaningful. Only the data team can mark something as endorsed. Endorsed dashboards also require data team review before changes go live. Our review process keeps endorsed assets trustworthy. If everything is endorsed, the signal stops being useful.我们对背书设置了护栏，以确保其意义。只有数据团队才能将某项内容标记为已背书。已背书的仪表盘在更改生效前也需要数据团队的审查。我们的审查流程确保了已背书资产的可信度。如果所有内容都被背书，那么这个信号就不再有意义了。

GitHub provides deeper implementation contextGitHub 提供了更深层的实现背景

The agent can also look at our dbt repo for deeper context about how a data point is sourced.代理还可以查看我们的 dbt 仓库，以获取关于数据点来源的更深层背景。

The dbt repo gives it access to the SQL and logic that define a column or metric from start to finish. This is useful when a question requires more than a surface-level definition. The agent can inspect the underlying model logic, understand joins and transformations, and trace how a field is produced.dbt 仓库使其能够访问定义列或指标的完整 SQL 和逻辑。当问题需要的不仅仅是表面定义时，这非常有用。代理可以检查底层的模型逻辑、理解连接（join）和转换，并追踪字段是如何生成的。

For more technical users, this is one of the most important parts of the setup. The agent can move between business-level context and implementation-level context, which makes it more useful for debugging, validation, and deeper analysis.对于技术用户来说，这是设置中最重要的部分之一。代理可以在业务级背景和实现级背景之间切换，这使其在调试、验证和深度分析方面更加有用。

Evaluating context changes评估背景信息的变更

Next, we want to start leveraging evals, which will help us understand whether context changes are improving agent responses.接下来，我们希望开始利用评估（evals），这将帮助我们了解背景信息的变更是否改善了代理的回答。

Today, we can look at usage patterns, warnings, and qualitative feedback. Evals will give us a more structured way to test changes. If we update a metric definition, add a guide, or change an endorsement, we want to know whether the agent produces better answers as a result.今天，我们可以查看使用模式、警告和定性反馈。评估将为我们提供一种更结构化的方式来测试变更。如果我们更新了指标定义、添加了指南或更改了背书，我们希望知道代理是否因此产生了更好的回答。

This will make context management feel more like software development. We can make a change, test it, and build more confidence before rolling it out broadly.这将使背景管理感觉更像软件开发。我们可以进行更改、测试，并在广泛推广之前建立更多信心。

Improving our context workflow改进我们的背景信息工作流

We also want to automate more of the process around context suggestions.我们还希望将围绕背景信息建议的流程实现更多自动化。

Observability already helps us find gaps. The next step is making it easier to turn those gaps into reviewed changes across dbt definitions, workspace guides, semantic model updates, and endorsements.可观测性已经帮助我们发现了差距。下一步是让这些差距更容易转化为跨 dbt 定义、工作区指南、语义模型更新和背书的已审查变更。

We are exploring ways to make context improvements easier to track, review, and ship.我们正在探索让背景信息的改进更易于追踪、审查和发布的方法。

Continuing to learn持续学习

Agent workflows are evolving quickly, and we are still learning what works, what needs guardrails, and where the product should improve.代理工作流正在迅速演进，我们仍在学习什么有效、什么需要护栏，以及产品应在哪些方面进行改进。

Small improvements in context retrieval, trust signals, evaluation, and user experience can make a big difference in whether people use the agent confidently.在背景检索、信任信号、评估和用户体验方面的微小改进，都能对人们是否能自信地使用代理产生重大影响。

Solid data modeling foundations make everything easier扎实的数据建模基础让一切变得更容易

Agent access does not remove the need for good data modeling. It raises the value of good data modeling.代理访问并不能消除对良好数据建模的需求。它反而提升了良好数据建模的价值。

Clear grains, well-named models, consistent definitions, and reliable transformations make the agent more useful. If the data model is confusing to humans, it will be confusing to agents too.清晰的粒度、命名规范的模型、一致的定义和可靠的转换使代理更有用。如果数据模型对人类来说是困惑的，那么对代理来说也是一样的。

Good context is one of the highest leverage investments良好的背景信息是最高杠杆的投资之一

The agent performs better when it understands the business. That means writing clear definitions, explaining company vocabulary, documenting metric logic, and giving guidance on how data should be interpreted.当代理了解业务时，其表现会更好。这意味着编写清晰的定义、解释公司词汇、记录指标逻辑，并提供关于如何解读数据的指导。

The best context is specific. It explains how the business works, what values mean in practice, which filters are expected, and where the data should or should not be used.最好的背景信息是具体的。它解释了业务如何运作、数值在实践中意味着什么、预期使用哪些过滤器，以及数据应该或不应该用在哪里。

The semantic model works best on top of strong foundations语义模型在坚实的基础上效果最好

A well-defined semantic model is important, especially for common metrics. But it depends on the quality of the underlying models and documentation.定义良好的语义模型很重要，尤其对于通用指标而言。但它取决于底层模型和文档的质量。

If you are starting this work, fix the foundations first. Then use the semantic layer to make the most important metrics consistent and easier for the agent to use.如果你正在开始这项工作，请先修复基础。然后利用语义层使最重要的指标保持一致，并更易于代理使用。

Start with the questions that matter most从最重要的问题开始

You do not need perfect context everywhere on day one.你不需要在第一天就拥有完美的背景信息。

Start with the questions people ask most often. Identify the models they hit most often. Go deep on those areas first.从人们最常问的问题开始。识别他们最常访问的模型。先在这些领域深入挖掘。

If you can cover roughly 80% of the questions people ask, you’ll create a much better experience for most users. Then you can work through the long tail over time.如果你能覆盖人们所提问题的 80% 左右，你就能为大多数用户创造更好的体验。然后你可以随着时间的推移处理剩下的长尾问题。

Self-service still needs data education自助服务仍然需要数据教育

Self-service works best when users understand both the power and the limits of the system.当用户了解系统的能力和局限性时，自助服务效果最好。

We are clear that agent responses should be treated with judgment, especially when the answer will inform an important decision. Data team members should always be looped in when questions need validation. We also share periodic reminders and best practices in Slack as we learn more about how to best interact with the agent and our tooling. 我们明确表示，代理的回答应谨慎对待，尤其是在回答将为重要决策提供依据时。当问题需要验证时，应始终让数据团队成员参与进来。随着我们对如何与代理和工具进行最佳交互的了解加深，我们也会在 Slack 中分享定期的提醒和最佳实践。

Our goal is not to make every person a data expert, but we want to give people better access to data while preserving trust.我们的目标不是让每个人都成为数据专家，而是希望在保持信任的同时，让人们更好地获取数据。