DataHub Agent Registry 深度指南：将 AI Agent、Skill 与 Tool 纳入统一元数据治理体系

DataHub Agent Registry 深度指南将 AI Agent、Skill 与 Tool 纳入统一元数据治理体系【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahubDataHub 的Agent RegistryAgent 注册表把 AI 智能体Agent、它们采用的技能Skill以及调用的工具Tool作为一等公民、受治理、带版本化的元数据实体纳入编目并使其与所消费的数据共享同一张血缘图。本文以该功能官方指南为骨架结合仓库中的元数据模型定义metadata-models/docs/entities/与 Python SDK 实现metadata-ingestion/src/datahub/api/entities/agent/展开讲解读完你将掌握 Agent Registry 的核心概念、元数据模型、UI 使用方法以及通过 SDK、CLI 和 agent context kit 完成显式注册与自动注册的完整实战方案。什么是 Agent RegistryAgent Registry随 DataHub Cloud v2.1 引入它将 AI 智能体、智能体采用的技能、以及智能体调用的工具作为一等公民、受治理、带版本化的元数据实体与它们消费的数据一起放进同一张血缘图lineage graph中。这让你可以在管理数据的同一个目录里回答一类此前难以回答的问题当前有多少个 Agent 在生产环境中运行每个 Agent 分别触及了哪些数据每个 Agent 由谁负责由于 Agent 与数据集共享同一张图数据侧已有的治理能力——所有权ownership、分级分类classification、血缘lineage、事件incidents与变更历史change history——无需额外配置即可自然延伸到 AI 层。换言之你不需要为 AI 资产另建一套治理体系沿用数据治理的同一套机制即可。Agent Registry 与 Agents 功能的区别在深入之前需要先厘清两个易混淆的概念详见 Agents 功能指南功能定位Agents关注构建AI 智能体使其能够按计划或响应事件自主执行任务支持任务 Task、人机协同决策 Decision 等能力当前在 DataHub Cloud 上以 Private Beta 提供Agent Registry关注编目AI 智能体无论其构建于 DataHub 内部还是外部使其可被发现、有归属、被版本化并与所触及的数据建立连接两者互补你构建出来的 Agent 可以在这里完成编目完成编目后的 Agent 则可以像任何资产一样被治理。核心概念四类实体Agent Registry 引入两类全新的实体类型并复用 Service Catalog 的 API 与 Service 实体来建模 Agent 的工具实体代表什么AI Agenturn:li:aiAgent:id一个 AI 智能体包含指令instructions、作用域scope与依赖dependencies。可以是 nativeDataHub 托管、system系统引导或 external外部编目Skillurn:li:agentSkill:id一个可复用的能力包提示词 工具 领域知识定义在 git 仓库中由 Agent 采纳Toolurn:li:api:idAgent 调用的一个能力——建模为带类型化签名的 API 实体MCP Server暴露 Agent 工具的服务端——建模为 Service 实体子类型为 MCP一个 Agent 的依赖以及它读取的数据全部汇入同一张血缘图repository ─▶ service (MCP) ─▶ api (tool) ◀─invokes─ aiAgent ─adopts─▶ skill ─requires─▶ api (tool) │ └─reads──▶ dataset (upstream lineage)从源码结构可以清晰看到这套关系在数据模型层面的落地metadata-models/docs/entities/aiAgent.md定义了aiAgentDependenciesaspect其中 skills 通过AgentHasSkill关系指向 Agent Skill 实体、tools 通过AgentUsesTool关系指向 API 实体、models 通过AgentUsesModel关系指向mlModel实体而metadata-models/docs/entities/api.md则记录了反向的入边——服务组合 APIServiceComposesApi、Agent 将其作为工具调用AgentUsesTool、Skill 依赖它SkillRequiresTool。Agent → Skill → Tool 的链路可以从任意一端开始遍历。安装前置、权限要求与启用方式AI Agent、Skill 与 Tool 与其它资产一样可以通过**摄取ingestion**填充也可以通过SDK/API 直接发射emit——具体操作参见 注册 AI Agent、Skill 与 Tool 的 API 教程其中涵盖 Python SDK、CLI以及从 LangChain 和 Google ADK 的自动注册。要在 UI 中浏览和管理这些实体用户需要标准的实体权限View Entity Page用于发现并打开 Agent、Skill 和 Tool 的详情页Edit Entity以及相应的子权限用于为它们补充所有权、标签、术语表词条与文档等元数据。Agent Registry 目前仅在 DataHub Cloud 上提供SaaS 功能需要联系你的 DataHub 代表为组织启用。使用 Agent Registry从 Agent 详情页出发Agent 详情页Agent Profile打开任意一个 Agent——例如官方指南示例中的FX Risk Scoring Agent——即可看到它的详情页页面集中展示该 Agent 做什么职责描述与指令使用的 Skill 与工具可点击跳转的依赖链读取的数据跨 BigQuery、Snowflake 与 dbt 的上游数据集可靠性信号eval 分数、调用量invocation volume与延迟latency归属方这里归属于 Quant Risk Team量化风控团队——保证每个 Agent 都有可找到、可问责的负责人。依赖DependenciesAgent 的依赖是显式且可点击的——它采纳的skill、调用的tools、以及运行的model各自都是目录中的独立实体。由于每项依赖都是可独立发现的编目实体新团队可以直接发现并复用它们而无需从零重建一个 Agent。从模型实现看这些依赖统一承载在aiAgentDependenciesaspect 中由 SDK 的Agent类 通过skills、tools、models三个字段接收 URN 列表并发射为类型化关系边。技能SkillsSkill 同样是编目实体。打开一个 Skill——例如FX Risk Scoring skill——你可以看到它的定义instructions一份权威规范source-of-truth spec通常来自 git 仓库中的SKILL.md它确切依赖的工具。一个 Skill 是一个可复用、经过验证的能力单元团队应当采纳adopt而非重复实现reimplement。metadata-models/docs/entities/agentSkill.md给出了更细的模型说明agentSkillInfoaspect 包含 name、description、instructionsSKILL.md中去除 YAML frontmatter 后的 markdown 正文、sourceRepository指向定义所在仓库优先引用已编目的 Repository 实体的repositoryUrn否则用外部url 文件path、requiredToolsSkillRequiresTool关系以及 created/lastModified 审计时间戳。这正对应官方指南所说的git as source of truth模式。工具、签名与契约Tools, Signatures, and ContractsAgent 调用的每一个工具都是一个API实体带有类型化签名——输入参数与输出形状——并使用与数据集相同的 schema 组件渲染。而暴露这些工具的MCP Server则被编目为Service实体每个 Server 在图中携带其完整契约contract实时工具列表、JSON Schema 形式的输入输出、就地版本化。REST API 工具则渲染其 OpenAPI 规范。metadata-models/docs/entities/api.md对此给出了精准的建模描述API 的种类由标准的subTypesaspect 记录规范子类型为MCP_TOOL、REST_ENDPOINT、GRPC_METHOD、GRAPHQL_OPERATION、FUNCTIONapiPropertiesaspect 保存目录身份信息name、description、externalUrl、sourceRepository 等签名单独放在apiSignatureaspect 上——schemaDefinition保留完整 JSON Schema 原始串inputFields/outputFields复用 DataHub 的 schema-field 模型给出结构化、类型化的视图fieldPath即参数名nullablefalse表示必填参数。签名与身份分离的意义在于契约变更时只需重新摄取 signature不影响目录身份对REST_ENDPOINT子类型restApiPropertiesaspect 记录 HTTPmethod与path其 URN 由服务 方法 路径派生如order-entry-api/GET/orders/{orderId}同一路径下的不同方法建模为独立 API 实体。对应地SDK 的Api类 将这些子类型常量、合法 HTTP 方法集合、以及友好类型提示 → SchemaField 类型的映射表直接固化在代码中string/number/integer/float/boolean/object/struct/array/date/datetime会被解析为对应的类型联合成员而诸如arrayOrder这样的参数化提示则按基础类型array解析同时原始字符串保留在nativeDataType中按原样展示。到数据的血缘Lineage to Your DataAgent 位于血缘图中它所消费的 BigQuery、Snowflake、dbt 表下游。这带来双向的追溯能力正向追踪某个 Agent 读取了哪些数据反向运行血缘反向查询找出哪些 Agent 读取了某张表。这一切都发生在与数据影响分析impact analysis相同的 lineage 图上。SDK 层面Agent类的consumes_datasets字段接受数据集 URN 列表并以upstreamLineageaspect默认血缘类型COPY发射使 Agent 出现在数据下游——这解释了官方指南中reads──▶ dataset (upstream lineage)这条边的来源。版本化与变更历史Versioning and Change HistoryAgent 是带版本的版本1.0至2.0归入同一个版本集合version set最新版本被明确标记原因在于生产环境中常常多版本并行运行SDK 的version_sort_id会在版本号为点分数字时自动派生因此1.9 1.10 2.0的正确排序开箱即用。每一次变更都会出现在**时间线timeline**上——标签变更、所有权更新、eval 分数提升、新增文档、以及版本里程碑本身。这是一条完整、可信的 AI 审计轨迹正如数据质量历史之于数据只是对象换成了 Agent。底层实现上Agent类通过version、version_set缺省时由 Agent 自身 id 派生、version_comment字段配合versionProperties/VersioningSchemeClass完成版本集的写入见 agent.py。跨血缘的治理自动化Governance Across Lineage由于 Agent 处在血缘图中治理自动化无需额外配置即可延伸至 AI 层。官方指南给出的示例极具代表性开启一个 Glossary Term Propagation 自动化有人将源表fx-positions分类为Highly Confidential高度机密由于FX Risk Scoring Agent消费了该表DataHub 将分类沿着血缘传播到 Agent 上Agent 随即携带同样的Highly Confidential标签Agent 的健康状态转为红色并自动开启一个 incident 等待审查。这样一来敏感数据进入 AI 系统的那一刻就会被看见——这正是把 Agent 放进血缘图最直接的价值。metadata-models/docs/entities/aiAgent.md也确认了这一点AI Agent 支持标准治理 aspect所有权、标签、术语、域、结构化属性、institutional memory并通过共享的 incidents 子系统incidentsSummary参与健康状态管理同时通过upstreamLineage参与血缘。程序化注册Python SDK 与 CLI 实战除了 UI 浏览Agent Registry 的价值更体现在程序化填充上。有两种方式详见 API 教程显式注册用 Python SDK 或datahubCLI 描述 Agent、Skill 与工具——适用于从自己的脚本或 CI 中编目 Agent自动注册用agent context kit指向已有的 LangChain 或 Google ADK Agent由它替你注册 Agent、工具与模型——适用于从现有框架代码中编目。两种方式都适用于任何 DataHub 实例本地、DataHub Core 或 DataHub Cloud。前置准备pip install acryl-datahub datahub init # 写入 ~/.datahubenv包含 GMS URL 与 tokenPython 侧发射目标是 graph clientfrom datahub.ingestion.graph.client import get_default_graph graph get_default_graph() # 读取 ~/.datahubenv或 DATAHUB_GMS_URL / DATAHUB_GMS_TOKEN 环境变量注意注册顺序实体关系是类型化的必须先注册工具再注册依赖它的技能最后注册采纳技能的 Agent——引用方会校验 URN 格式是否合法。注册一个工具API 实体工具是API实体urn:li:api:id——一个带类型化签名的可调用项。同一实体可以建模 MCP 工具、REST 端点、gRPC 方法、GraphQL 操作与普通函数由subtypes字段区分。Python SDKfrom datahub.api.entities.agent.api import Api, ApiParam get_orders Api( idorder-svc.get_orders, nameget_orders, subtypes[MCP_TOOL], # 或 REST_ENDPOINT, GRPC_METHOD, GRAPHQL_OPERATION, FUNCTION descriptionFetch orders in a date range., parameters[ ApiParam(namestart_date, data_typestring, requiredTrue), ApiParam(nameend_date, data_typestring, requiredTrue), ApiParam(nameregion, data_typestring, descriptionOptional region filter.), ], returns[ApiParam(nameorders, data_typearrayOrder)], external_urlhttps://github.com/acme/order-svc, ) tool_urn get_orders.emit(graph) # urn:li:api:order-svc.get_ordersApiParam.data_type接受友好类型提示string、integer、boolean、object、arrayOrder……原始值会被保留因此arrayOrder这样的提示会按撰写原文展示机制见上文对 api.py 类型映射的分析。若为 REST 端点再添加methodGET与path/orders即可发射 HTTP 绑定restApiPropertiesaspect。CLIdatahub api register --id order-svc.get_orders --name get_orders \ --subtype MCP_TOOL \ --param start_date:string:required \ --param end_date:string:required \ --param region:string \ --returns orders:object \ --description Fetch orders in a date range.参数规格为NAME:TYPE[:required]返回规格为NAME:TYPE。注册一个技能AgentSkill 实体skillurn:li:agentSkill:id是可复用的能力包——专门化指令加上它所依赖的工具——定义在 git 中、编目进 DataHub。Python SDKfrom datahub.api.entities.agent.agent_skill import AgentSkill, SkillSourceRepository discovery AgentSkill( iddata-discovery, nameData Discovery, descriptionFinds and summarizes relevant datasets., instructionsUse get_orders to retrieve orders, then summarize by region., source_repositorySkillSourceRepository( urlhttps://github.com/acme/skills, pathdata-discovery/SKILL.md, ), required_tools[tool_urn], # API urns ) skill_urn discovery.emit(graph) # urn:li:agentSkill:data-discoveryCLIdatahub agent-skill register --id>from datahub.api.entities.agent.agent import Agent agent Agent( idorders-assistant, nameOrders Assistant, descriptionAnswers questions about orders., instructionsYou are an assistant for the orders team., owners[urn:li:corpgroup:orders-team], domainSales, skills[skill_urn], # agentSkill urns tools[tool_urn], # api urns models[urn:li:mlModel:(urn:li:dataPlatform:openai,gpt-4o,PROD)], consumes_datasets[ urn:li:dataset:(urn:li:dataPlatform:snowflake,prod.sales.orders,PROD), ], platformlangchain, # 在 profile 上展示框架 Logo ) agent_urn agent.emit(graph) # urn:li:aiAgent:orders-assistantsource_type默认为EXTERNAL外部托管、仅编目的 AgentDataHub 托管的 Agent 使用NATIVE或SYSTEM。这正对应metadata-models/docs/entities/aiAgent.md中关于三种来源的说明SYSTEM为部署时引导如通过 YAML且终端用户不可编辑NATIVE为终端用户在 DataHub 上创建并管理EXTERNAL为 DataHub 之外管理但在此编目——这是一个来源/治理轴而非功能轴单 Agent / 多 Agent / copilot 的区分可另行通过subTypesaspect 叠加。:::note 关于 CLI 的 agent 命令datahub agent命令datahub agent register …/datahub agent upsert -f agent.yml仅在未安装 agent context kit 时才是 SDK 内置命令一旦安装 kitdatahub agent就变成该包的命令。拿不准时始终从 Python SDK如上或 YAML 文件注册 Agent——这两者任何时候都可用。datahub api与datahub agent-skill不受影响。 :::自动注册从 LangChain 或 Google ADK与其手写描述不如让agent context kit读取你正在运行的 Agent 并自动注册——Agent 本身、它暴露的工具、以及它使用的模型。注册是**fail-open故障开放**的DataHub 不可达时仅记录日志并继续绝不会中断你的 Agent。安装对应框架的 extrapip install datahub-agent-context[langchain] # 或 [google-adk]用datahub_tool一次性注解工具即可挂接它触及的数据集与所属技能——这两者会成为 Agent 的血缘与技能链接from datahub_agent_context.langchain_registration import datahub_tool datahub_tool( datasets[urn:li:dataset:(urn:li:dataPlatform:snowflake,prod.sales.orders,PROD)], skilldata-discovery, ) def get_order_stats(start_date: str, end_date: str) - str: ...LangChainfrom datahub_agent_context._registration_core import AgentRegistrar from datahub_agent_context.langchain_registration import ( DataHubCallbackHandler, register_langchain_agent, ) # Pattern 1 —— 回调处理器Agent 运行时自动注册 registrar AgentRegistrar( frameworkLangChain, framework_versionNone, platformlangchain, agent_idorders-assistant, agent_nameOrders Assistant, descriptionAnswers questions about orders., ) handler DataHubCallbackHandler(registrar, tools[get_order_stats]) # 将 handler 挂到 AgentExecutor 的 callbacks 上首次 LLM 调用时捕获模型 # Pattern 2 —— 一次性快照注册已构建好的 executor register_langchain_agent( agent_executor, agent_idorders-assistant, agent_nameOrders Assistant, descriptionAnswers questions about orders., )Google ADKfrom google.adk.agents import Agent from datahub_agent_context._registration_core import AgentRegistrar from datahub_agent_context.google_adk_registration import ( DataHubBeforeModelCallback, register_google_adk_agent, ) # Pattern 1 —— before-model 回调 registrar AgentRegistrar( frameworkGoogle ADK, framework_versionNone, platformgoogle-adk, agent_idorder-assistant, agent_nameOrder Assistant, descriptionAnswers questions about orders., ) callback DataHubBeforeModelCallback(registrar, tools[get_order_summary]) adk_agent Agent( modelgemini-2.0-flash, nameorder_assistant, tools[get_order_summary], before_model_callbackcallback, ) # Pattern 2 —— 急切注册已构建好的 Agent register_google_adk_agent( adk_agent, agent_idorder-assistant, agent_nameOrder Assistant, descriptionAnswers questions about orders., )kit 会根据模型标识符推断模型的mlModelURN 与供应商如gpt-*→ OpenAI、claude-*→ Anthropic、gemini-*→ Google。可端到端运行的完整示例位于仓库的datahub-agent-context/examples/langchain/autoregister_agent.py与datahub-agent-context/examples/google_adk/autoregister_google_adk.py——其中 LangChain 示例 展示了带datahub_tool注解与普通工具的对比注解过的工具get_order_stats会把数据集和技能链接进 DataHub 图未注解的工具则只捕获名称与描述。:::tip 反向使用把 DataHub 变成 Agent 的工具 同一个包也可以从DataHub 构建工具列表——build_langchain_tools(client)/build_google_adk_tools(client)传入include_mutationsTrue允许元数据编辑另有面向 Ask DataHub 的云版本变体。参见 DataHub MCP Server 指南 了解如何让 Agent 连接 DataHub 的工具。 :::版本化 Agent版本集合实战设置version可将 Agent 的连续发布归入版本集合version set——profile 上随即出现版本选择器最高版本被标记为 latest。每个版本都是独立的aiAgent实体使用不同的idAgent( idorders-assistant-v2, nameOrders Assistant, descriptionAdds refund lookups., version2.0, version_setorders-assistant, # 这些版本共享的家族 version_commentAdded refund-lookup tool., tools[tool_urn, refund_tool_urn], ).emit(graph)点分数字版本开箱即用地正确排序1.9 1.10 2.0——这得益于 SDK 从version自动派生的version_sort_id字典序排序键见 agent.py。常见问题FAQ这与 Agents 功能有何不同Agents 功能关注构建可自主运行任务的 AI 智能体Agent Registry 关注编目AI 智能体无论构建于 DataHub 内部还是外部为受治理的元数据——使其可被发现、有归属、带版本并与其触及的数据建立连接。Agent 的tool在元数据模型中映射到什么工具是一个API实体——与 Service Catalog 用于建模 REST 端点、gRPC 方法与 GraphQL 字段的实体相同。正因为如此哪些 Agent 调用了这个端点可以用普通的影响分析impact analysis回答API 是共享实体AgentUsesTool就是图中一条可遍历的边见 api.md 与 aiAgent.md 的关系定义。在 DataHub 之外构建的外部 Agent 能被编目吗可以。Agent 可以是 nativeDataHub 托管、system系统引导或external从其他平台编目——无论哪种profile、血缘、版本化与治理都以相同方式工作。source_type参数SDK 默认EXTERNAL正是这一点的直接体现。相关功能延伸阅读Service Catalog —— 服务、API、仓库与应用Agent Registry 复用其 Service 与 API 实体Agents —— 构建可自主执行任务的 AI 智能体Lineage —— 端到端依赖追踪与影响分析Glossary Term Propagation —— 跨血缘的自动化分级分类DataHub MCP Server —— 将 DataHub 自身的工具暴露给 AI Agent【免费下载链接】datahubThe Context Platform for your Data and AI Stack项目地址: https://gitcode.com/GitHub_Trending/da/datahub创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考