在金融数据分析领域，数据源的多样性和数据格式的异构性一直是工程实践中的核心挑战。OpenBB 作为一款专注于金融数据分析的开源平台，通过其独特的 TET（Transform-Extract-Transform）数据管道架构，实现了对数十个第三方数据源的统一封装。更值得关注的是，OpenBB 还提供了完整的 AI 代理接入机制，允许开发者将自建的大语言模型代理无缝集成到其工作空间中。本文将从数据管道设计、AI 代理协议、SDK 工具三个维度，系统性地解析这一工程实践。
TET 数据管道：统一异构数据源的核心架构
OpenBB Platform 的核心设计理念是「一个接口，多个数据源」。平台通过嵌套的 FastAPI 风格路由，将诸如 equity/profile、equity/price/historical 等资源端点映射到具体的数据提供商。这种路由机制使得上层调用者无需关心底层数据来自哪里，只需按照统一的数据模式进行查询即可。
TET 管道是整个数据处理流程的灵魂所在，它包含三个关键阶段。第一阶段是请求转换（Transform），系统会验证输入参数的合法性，设置合理的默认值，并将用户友好的参数名称映射为特定数据提供商所需的参数格式。以查询苹果公司历史股价为例，用户可能传入「AAPL」或「Apple Inc.」，但不同的数据提供商（如 Yahoo Finance、Alpha Vantage）可能需要不同的股票代码格式，这一映射工作就在请求转换阶段完成。第二阶段是数据提取（Extract），系统根据转换后的参数调用外部 API 或本地数据源，获取原始数据 payload。这一阶段直接与第三方服务交互，可能是 REST API 调用、数据库查询或本地文件读取。第三阶段是响应转换（Transform），原始数据在此被强制转换为 OpenBB 定义的标准模型，标准化时间戳格式、删除敏感字段、按照统一 Schema 重命名字段，最终返回给调用者。
这种设计模式的精妙之处在于复用性。由于每个数据提供商都实现了相同的 TET 接口，上层业务逻辑无需为每个数据源编写专门的适配代码。平台目前支持数十个数据提供商，包括主流的金融数据 API、交易所接口以及本地文件源，但对外呈现的却是完全一致的数据 schema 和行为。
AI 代理接入协议：HTTP 与 SSE 的协同设计
OpenBB Workspace 是平台的可视化层，提供了 AI 驱动的金融研究和分析工作环境。在该环境中，用户可以通过对话方式与 AI 代理交互，获取即时的市场数据分析结果。为了支持自定义 AI 代理的接入，OpenBB 设计了一套简洁而强大的代理协议，核心依赖 HTTP 和 Server-Sent Events（SSE）两种技术。
外部 AI 代理需要暴露两个 HTTP 端点才能被 Workspace 发现和调用。第一个端点是 GET /agents.json，该端点返回代理的元数据信息，包括代理 ID、名称、描述、图标 URL、查询端点 URL，以及功能标志位（如是否支持流式输出、是否支持部件搜索等）。当用户在 Workspace 的 Copilot UI 中注册代理的基础 URL 后，Workspace 会自动调用此端点获取代理信息并在界面中展示。第二个端点是 POST /query，这是实际的对话入口，接收 QueryRequest 对象并通过 SSE 流式返回处理结果。
QueryRequest 的数据结构设计充分考虑了金融分析场景的复杂性。它包含对话历史（消息列表，每条消息有 human、ai 等角色标识）、当前选中的部件（Widget）信息、以及部件的具体参数。当用户发起一个分析请求时，代理可以决定是否需要先获取某些数据部件，然后在后续的回调中基于实际数据进行分析。
官方推荐的实现技术栈是 FastAPI 配合 sse_starlette 库中的 EventSourceResponse。当然，任何支持 POST 请求处理和 SSE 流式输出的服务器框架都可以实现这一协议，这为不同技术背景的开发者提供了极大的灵活性。
OpenBB AI SDK：类型安全与开发效率的双重保障
为了降低 AI 代理的开发门槛，OpenBB 提供了专门的 openbb-ai SDK。该 SDK 定义了一系列类型模型，涵盖代理开发所需的全部数据结构。核心类型包括 QueryRequest（查询请求）、MessageChunkSSE（流式消息块）、WidgetRequest（部件请求）、DataContent（数据内容）等。除此之外，SDK 还提供了丰富的辅助函数：message_chunk 用于构建文本消息、reasoning_step 用于输出推理步骤（可标记为 INFO/ERROR/SUCCESS 级别）、table 用于渲染表格视图、citations 用于生成数据引用来源。
SDK 还定义了丰富的数据格式类型，用于规范部件输出。PdfDataFormat、SpreadsheetDataFormat、ImageDataFormat、RawObjectDataFormat 分别对应 PDF 文件、表格文件、图片和原始对象。容器类型如 SingleDataContent 和 SingleFileReference 则提供了统一的数据包装方式，使得代理可以以一致的方式处理不同类型的返回结果。
两阶段数据流：代理与部件的协同机制
理解 OpenBB AI 代理的数据流，是掌握整个接入机制的关键。整个交互过程分为两个阶段，形成了代理与 Workspace 之间的回调闭环。
在第一阶段，用户发送初始问题后，代理分析是否需要获取数据部件。如果需要，代理会构建 WidgetRequest 列表，并通过 SSE 事件流中的 get_widget_data 事件告知 Workspace 需要哪些部件以及对应的参数。此时代理并不直接返回最终答案，而是暂时挂起等待数据。Workspace 收到请求后，会执行相应的部件查询（通常调用 OpenBB Platform 或其他数据源），将结果封装为 DataContent 或 DataFileReferences，然后以新的 QueryRequest 形式回调代理的 /query 端点，此时 last_message.data 字段中包含了完整的部件输出数据。
在第二阶段，代理接收到带有数据的回调请求后，开始真正的分析工作。代理遍历每个 DataContent 项，进行必要的解码操作（JSON 解析、Base64 解码等），将数据转换为内部结构（如 pandas DataFrame 或 JSON 字典），随后执行分析逻辑并生成回复。代理通过 SSE 事件流返回 reasoning_step（展示分析进度）、message_chunk（LLM 生成的文本）、table（可选的表格渲染）、citations（数据引用来源）等多种事件，Workspace 则将这些事件渲染为用户可见的界面元素。
这种两阶段设计确保了代理可以在需要时动态获取数据，同时保持了对话的上下文完整性。对于金融分析场景，这种设计尤为必要，因为市场数据的获取往往涉及多个 API 调用和复杂的数据处理逻辑。
工程实践建议
基于上述架构分析，以下是接入自定义 AI 代理的最小可行实现路径。首先，使用 FastAPI 创建服务，实现 GET /agents.json 端点返回代理元数据，其中必须包含 query 端点 URL 和 streaming 功能标志。其次，实现 POST /query 端点，接收 QueryRequest 并返回 EventSourceResponse。再次，在请求处理逻辑中实现两阶段模式：第一阶段检测部件需求并返回 get_widget_data 事件；第二阶段解析回调数据、执行分析、通过 SSE 返回结构化事件。最后，在 Workspace 的 Copilot UI 中注册代理的基础 URL，即可开始交互测试。
对于希望深度定制的开发者，还可以利用 OpenBB Platform 的 Python SDK 直接调用 TET 管道，自行构建数据获取逻辑而不依赖 Workspace 的部件系统。这种灵活的分层设计，使得 OpenBB 既可以作为一个开箱即用的金融数据分析工具，也可以作为自定义 AI 系统的数据基础设施。
资料来源：本文核心架构信息来源于 OpenBB 官方博客关于平台架构和数据管道的介绍，以及 OpenBB Workspace 官方文档中关于 AI 代理集成的技术说明。