Alation AI Agent SDK

Alation AI Agent SDK

Alation AI Agent SDK 可让 AI Agent 访问并利用 Alation Data Catalog 中的元数据。

概览

此 SDK 使 AI Agent 能够：

• 轻松集成 Alation Data Catalog
• 支持资产整理、搜索与发现、基于角色的 Agent 以及数据分析师 Agent 等使用场景
• 使用自然语言搜索相关元数据
• 与 MCP 等 AI 框架无缝集成

组件

此项目由多个组件构成：

• 核心 SDK - 提供 API 客户端和上下文工具的基础组件
• MCP 集成 - Model Context Protocol 的服务实现
• LangChain 集成 - 面向 LangChain 框架的适配器

核心 SDK (alation-ai-agent-sdk)

核心 SDK 为与 Alation API 交互提供基础功能，负责处理身份验证、请求格式化和响应解析。

详细了解核心 SDK

LangChain 集成 (alation-ai-agent-langchain)

此组件将 SDK 与 LangChain 框架集成，使你能够创建复杂的 AI Agent，对数据目录进行推理。

详细了解 LangChain 集成

MCP 集成 (alation-ai-agent-mcp)

MCP 集成提供兼容 MCP 的服务，可向任何 MCP 客户端开放 Alation 的上下文功能。支持用于直接连接 MCP 客户端的传统 STDIO 模式，也支持适用于 Web 应用和 API 集成的 HTTP 模式。

详细了解 MCP 集成

入门

前提条件

• Python 3.10 或更高版本
• 可访问 Alation Data Catalog 实例
• 有效的刷新令牌，或 client_id 和 secret。更多详情请参阅身份验证指南。

安装

pip install uv

# Install the core SDK
uv pip install alation-ai-agent-sdk==1.0.0

# Install LangChain integration
uv pip install alation-ai-agent-langchain==1.0.0

# Install the MCP integration
uv pip install alation-ai-agent-mcp==1.0.0

用法

此库需要使用 Alation 实例凭据进行配置。你应使用 ServiceAccountAuthParams。

服务账户身份验证（推荐）

from alation_ai_agent_sdk import AlationAPI, ServiceAccountAuthParams

# Initialize the SDK with Service Account Authentication
auth_params = ServiceAccountAuthParams(
    client_id="your_client_id",
    client_secret="your_client_secret"
)
alation_api = AlationAPI(
    base_url="https://your-alation-instance.com",
    auth_method="service_account",
    auth_params=auth_params
)

如果无法获取服务账户凭据（仅限管理员），请参阅用户账户身份验证指南了解操作说明。

新版主版本 1.x.x

2026 年 10 月 23 日更新

1.0.0 是 Alation AI Agent SDK 的首个稳定版本。

• 现在，请求会发送 Ai-Surface 标头（默认为 sdk）；设置 AgentSDKOptions(surface=...) 可标识你的集成
• MCP 服务要求 certifi>=2026.10.19，其 Docker 镜像会刷新 OS CA 存储，移除对已遭入侵的 eMudhra 中间 CA 的信任
• 身份验证参数对象会在其 repr() 中隐藏机密
• 流式和非流式响应对格式错误或为空的有效负载处理得更加稳健

2026 年 1 月 2 日更新

重大变更：

• 已移除的工具：update_catalog_asset_metadata 和 check_job_status 已从 SDK 中移除

如需此功能，请直接使用 Alation REST API。底层 API 端点（/integration/v2/custom_field_value/async/ 和 /api/v1/bulk_metadata/job/）仍然可用。详情请参阅 Alation Developer Portal。

2025 年 12 月 10 日更新

Alation AI Agent SDK 的 1.0.0rc2 版本现已推出。

此版本弃用 Context Tool，改用功能更强大的 Catalog Context Search Agent。在实际使用中，Catalog Context Search Agent 沿用相同的契约，因此迁移应该很简单。

我们承诺在接下来的 三个月过渡期内，继续将现已弃用的 Context Tool 保留在 SDK 中。这意味着预计它将在 2026 年 2 月移除。

移除 Context Tool 的主要原因是，它与另一个工具的功能非常相似。当两者都提供给大模型时，模型经常会选择功能较弱的那个，导致效果变差。通过减少概念上重叠的工具数量，我们可以避免选错工具。

Catalog Context Search Agent 不仅能完成 Context Tool 的所有工作，还能动态构建 signature 参数。这是使用 Context Tool 时的一大瓶颈。

出于同样的原因，我们也调整了本地 MCP 服务，默认不再包含 Context Tool、Analyze Catalog Question、Signature Create 或 Bulk Retrieval。Catalog Context Search Agent 会根据需要在内部调用这些工具，无需将它们加入可用范围。

如果你的提示词依赖上述任何特定工具，就需要告知 MCP 服务要启用哪些工具（覆盖默认设置）。你可以通过命令行参数或环境变量进行设置。

提醒：如果你的用例范围较窄，请仅启用该用例所需的工具。

# As command line arguments to the MCP server command
--enabled-tools=alation_context,analyze_catalog_question,bulk_retrieval,generate_data_product,get_custom_fields_definitions,get_data_dictionary_instructions,data_product,get_signature_creation_instructions,catalog_context_search_agent,query_flow_agent,sql_query_agent

# Or as an environment variable
export ALATION_ENABLED_TOOLS='alation_context,analyze_catalog_question,bulk_retrieval,generate_data_product,get_custom_fields_definitions,get_data_dictionary_instructions,data_product,get_signature_creation_instructions,catalog_context_search_agent,query_flow_agent,sql_query_agent'

2025 年 11 月 4 日更新

我们很高兴地宣布，Alation AI Agent SDK 的 1.0.0rc1 版本现已推出。

重要：作为一项重大变更，user_account 不再受支持作为授权模式。我们建议你迁移到 service_account 或 bearer_token 模式。

这个新的主要版本带来了多项值得关注的变更，让迁移更有价值。

• Alation Agent Studio 集成
• 远程 MCP 服务
• Catalog Search Context Agent
• 流式传输和 Chat ID 支持

Alation Agent Studio 集成

Alation Agent Studio 为创建和使用业务所需的 Agent 提供一流支持。无论你是在改进目录整理，还是在构建以数据为中心的查询 Agent，Agent Studio 都能让你轻松创建、完善 Agent，并将其部署到整个企业。它包含多种专家工具，可直接使用，也可组合起来作为构建块，以应对更复杂的场景。你构建的任何精准 Agent 都可在 SDK 或 MCP 服务中作为工具使用（参见 custom_agent）。

远程 MCP 服务

我们了解到，许多客户希望灵活使用 MCP 服务，但不想承担安装或升级 SDK 的责任。使用我们的远程 MCP 服务，你无需处理这些事务。只需完成一次面向 MCP 的授权设置，就可以轻松地将远程 MCP 服务添加到你喜欢的 MCP 客户端中，例如：https://<your_instance>/ai/mcp

注意：MCP 客户端和平台正在快速发展。它们支持授权流程、路径参数等的方式并不完全相同。如果你遇到阻碍，请提交 Issue，以便我们调查并制定计划。我们不支持动态客户端注册，因此请使用允许你传入 client_id 和 client_secret 的 MCP 客户端。

从这里开始

远程 MCP 服务要解决的一个问题是动态列出工具。这种动态能力为我们承担了许多工作。例如，它可以筛除当前用户无法使用的工具，也可以列出 SDK 尚不知晓的全新工具。

由于工具是按需解析而非静态解析，这些工具的 API 契约也可以动态变化。这样可以避免客户端与服务端版本不匹配的问题，否则这可能会导致静态集成失效。

我们会继续支持 SDK，并定期发布新版本；但如果你希望采用不那么脆弱、更稳健的集成方式，可以考虑从直接集成远程 MCP 服务入手。

Catalog Search Context Agent

Agent SDK 刚推出时，我们只有一个工具：Alation Context。它提供了一种强大的方式，可以动态选择合适的对象及其属性，以最佳方式回答特定问题。它强大的 signature 参数也让它适用于没有用户问题的场景（批量检索）。与此同时，我们发现，大模型生成的 signature 参数相当容易无效或完全错误。令人意外的是，许多使用场景根本没有提供 signature，这往往会导致结果不佳。

为了解决这些问题，我们将一组工具（alation_context、bulk_retrieval）整合为一个 Agent。它会执行一系列检查和启发式步骤，在需要时动态创建 signature，以便利用你的自定义字段。这就是我们的新工具 catalog_search_context_agent。

这样一来，你需要编写的指令会更少，就能让这些工具协同工作；同时还可以提高调用的准确性。

流式传输和 Chat ID 支持

流式传输

现在，所有工具都支持流式传输选项。这主要有益于处于 http 模式下的本地 MCP 服务。如果你的 MCP 客户端支持流式传输，现在应该可以看到工具和 Agent 的部分内部处理过程，从而更清楚地了解其底层运行情况。

SDK 默认禁用流式传输，但如果你有相关使用场景，可以启用此功能。若要启用，请向 AlationAIAgentSDK 构造函数传入 sdk_options=AgentSDKOptions(enable_streaming=True) 参数。使用流式传输时，你需要遍历结果或从中 yield，才能正确处理底层生成器。

Chat ID

大多数工具和 Agent 在调用时都接受 chat_id 参数。包含此参数后，该工具调用会与引用相同 chat_id 的其他先前调用相关联。任何兼容 chat_id 的工具都会在响应中包含 chat_id。

支持的工具

• alation_context
• bulk_retrieval
• data_quality_tool
• get_custom_fields_definitions
• get_data_products
• get_data_sources_tool
• get_signature_creation_instructions
• lineage

支持的 Agent

• catalog_context_search_agent
• custom_agent
• query_flow_agent
• sql_query_agent

指南和示例 Agent

通用

• 身份验证 - 如何获取访问权限。
• 工具管理 - 启用或禁用特定工具的控制选项。

聚合上下文 / 批量检索工具

• 规划集成 - 了解如何充分利用 Agent 和 Alation Data Catalog 的实用注意事项。
• 使用签名 - 通过具体示例了解如何自定义 Agent。
• 支持的对象类型和默认对象字段 - 查看支持的对象。
• 支持的对象字段 - 各个支持对象的完整参考资料。

其他工具

• 数据质量：检查 SQL 查询 - 识别 SQL 查询中的数据质量问题。
• 血缘关系 - 获取上游和下游关系图。

核心 SDK

Alation AI Agent SDK 的直接使用示例：

• 基本用法示例 - 展示 SDK 初始化和上下文查询的简单示例。
• 问答聊天机器人示例 - 演示对话上下文和签名用法的交互式聊天机器人。

模型上下文协议（MCP）

借助 Alation Data Catalog 打造 Agent 式体验。

• MCP 集成 - 启动并运行 Alation MCP 服务。
• 与代码编辑器集成 - 在代码编辑器中直接使用工具。
• 使用 MCP Inspector 进行测试 - 调试和验证步骤。
• Claude Desktop 集成 - 在 Claude Desktop 中使用 Alation MCP 服务。
• LibreChat 集成 - 创建助手和 Agent。

LangChain

使用 SDK 构建复杂的 Agent 和工作流。

• LangChain 集成 - 了解如何将 SDK 集成到 LangChain Agent 中。
• 基本用法示例 - 一个简单示例。
• 多 Agent 示例 - 展示多个 SDK 集成点的多 Agent 工作流。

与其他工具包集成

已发布的 Agent 框架和工具包似乎每天都在增加。如果这里没有列出您正在使用的框架或工具包，仍然可以根据您的需求调整 alation-ai-agent-sdk。可能只需编写一个应用装饰器的包装函数即可。

我们希望服务尽可能多的开发者，并尽可能提供便利，但我们预计工具包的分布会呈长尾形态，因此无法为所有情况编写适配器。如果您希望支持特定工具包，请创建问题进行讨论。