PreviewPipeline - 流水线预览-Agent 观测与优化 AgentLoop(AgentLoop)-阿里云帮助中心

预览流水线。在不创建流水线资源的前提下，基于给定的数据源、节点编排和时间范围试运行查询，返回少量样本数据，用于验证参数配置和预览处理效果。

接口说明

请求说明

agentSpace 必须是当前账户下已创建的 AgentSpace 实例。
source.type 当前仅支持 logstore 类型，且 logstore.project 和 logstore.logstore 需要在该 AgentSpace 内完成授权并处于同一区域。
pipeline.nodes 至少包含一个 Source 类型的节点，不允许为空。
fromTime 和 toTime 是 Unix 秒级时间戳，其中 fromTime 必须小于 toTime。
返回的数据最多为 5 条记录，并自动过滤掉数据源系统内部字段。

调试

您可以在OpenAPI Explorer中直接运行该接口，免去您计算签名的困扰。运行成功后，OpenAPI Explorer可以自动生成SDK代码示例。

调试

授权信息

下表是API对应的授权信息，可以在RAM权限策略语句的Action元素中使用，用来给RAM用户或RAM角色授予调用此API的权限。具体说明如下：

操作：是指具体的权限点。
访问级别：是指每个操作的访问级别，取值为写入（Write）、读取（Read）或列出（List）。
资源类型：是指操作中支持授权的资源类型。具体说明如下：
- 对于必选的资源类型，用前面加 * 表示。
- 对于不支持资源级授权的操作，用全部资源表示。
条件关键字：是指云产品自身定义的条件关键字。
关联操作：是指成功执行操作所需要的其他权限。操作者必须同时具备关联操作的权限，操作才能成功。

操作

访问级别

资源类型

条件关键字

关联操作

agentloop:PreviewPipeline

list

*Pipeline

acs:agentloop:{#regionId}:{#accountId}:agentspace/{#AgentSpaceName}/pipeline/*

无

请求语法

POST /agentspace/{agentSpace}/pipeline/preview HTTP/1.1

路径参数

名称	类型	必填	描述	示例值
agentSpace	string	否	AgentSpace 名称，定位流水线所在的 AgentSpace	my-agent-space

请求参数

名称	类型	必填	描述	示例值
body	object	否	请求体
fromTime	integer	否	预览数据窗口起始时间，Unix 秒	1735660800
pipeline	object	否	Pipeline 配置（节点编排）	{"nodes":[{"id":"select-fields","type":"project","parameters":{"question":"user_query"}}]}
nodes	array<object>	否	节点列表	[{"id":"select-fields","type":"project","parameters":{}}]
	array<object>	否	单个节点配置
id	string	否	节点 Id	node-1
parameters	object	否	节点参数，键值结构，随节点类型而定
	any	否	节点参数值	value
type	string	否	节点类型	transform
source	object	否	Pipeline 数据源	{"type":"logstore","logstore":{"project":"my-sls-project","logstore":"agent-logs"},"inputFields":[{"name":"question","type":"text"}]}
dataset	object	否	当前 AgentSpace 下的 Dataset 数据源配置	{"dataset":"my-dataset","filter":"status = 'pending'"}
dataset	string	否	源 Dataset 名称	my-dataset
filter	string	否	Dataset 数据过滤条件	status = 'pending'
inputFields	array<object>	否	输入字段及字段类型，适用于所有数据源类型	[{"name":"question","type":"text"}]
	object	否	输入字段
name	string	否	字段名称	question
type	string	否	字段类型，支持 text、long、double、json	text
logstore	object	否	SLS Logstore 数据源配置	{"project":"my-sls-project","logstore":"agent-logs"}
logstore	string	否	SLS Logstore 名称	my-sls-logstore
project	string	否	SLS Project 名称	my-sls-project
query	string	否	数据筛选查询语句（SLS 查询/分析语法）	* \| SELECT *
trajectory	object	否	轨迹数据配置（可选，type 为 trace 时生效）：从轨迹清洗服务获取 ATIF 标准轨迹数据，按功能扩展	{"enrich":{"enabled":true,"columns":["input","output"]}}
enrich	object	否	轨迹富化：按 trace_id 将轨迹数据挂载进清洗结果；写入数据集时以固定列 agent_trajectory 承载（列值为轨迹 JSON 内容）	{"enabled":true,"columns":["input","output"]}
columns	array	否	富化列清单（兼容保留）：当前实现固定输出单列 agent_trajectory，本参数不再影响输出	["input","output","session_id"]
	string	否	轨迹列名	input
enabled	boolean	否	是否开启轨迹富化	false
type	string	否	数据源类型，当前支持 SLS	SLS
toTime	integer	否	预览数据窗口结束时间，Unix 秒	1735747200

The path parameter agentSpace must match an existing AgentSpace instance owned by the current account; otherwise an AgentSpaceNotFound error is returned.
source.type currently only supports SLS. The logstore.project and logstore.logstore must have completed STS authorization within the AgentSpace, and must be in the same region.
source.logstore.query follows standard SLS query syntax (including SPL stage | SELECT ...). Verify your query in the SLS console first.
pipeline.nodes must contain at least one Source node (type=Source); an empty array triggers InvalidParameter.Pipeline.
Other supported node types include Filter, Extract, Transform, SampleData, etc. (see the Pipeline developer documentation for the complete list).
pipeline.nodes[].parameters is map, interpreted according to node.type; unexpected keys will be rejected.
fromTime / toTime are unix seconds; fromTime must be strictly less than toTime. Keep the window under 15 minutes to control SLS scan volume within the 3-second timeout.

返回参数

名称	类型	描述	示例值
	object	响应数据
data	array<object>	`data` 为样本行集合（数组内 map），仅包含前 N 行（默认最多 5 行），不反映完整写入计划。	[{"status":"200","method":"POST"}]
	object	字段值	200
	string	返回数据	[{'type': 'saturation', 'value': 0}, {'type': 'load', 'value': 0}, {'type': 'latency', 'value': 1}, {'type': 'error', 'value': 0}]
meta	object	查询元信息
aggQuery	string	聚合分析 SPL 语句	* \| SELECT status, count(*) AS cnt GROUP BY status
columnTypes	array	`meta.columnTypes` 提供列名到数据类型的映射（string / long / double / json）。	["long","string"]
	string	`meta.columnTypes` 提供列名到数据类型的映射（string / long / double / json）。	string
count	integer	匹配的日志条数	100
cpuCores	integer	消耗的 CPU 核数	2
cpuSec	number	消耗的 CPU 时间，秒	0.5
elapsedMillisecond	integer	查询耗时，毫秒	1200
hasSQL	boolean	是否 sql 查询	true
isAccurate	boolean	是否开启纳秒级有序	true
keys	array	结果列名列表	["status","method","path"]
	string	结果列名列表	[]
limited	integer	返回结果行数上限	5
mode	integer	查询模式标识	1
processedBytes	integer	处理的数据字节数	524288
processedRows	integer	处理的日志行数	10000
progress	string	SLS 查询进度，Complete 表示已完成	Complete
scanBytes	integer	扫描的原始数据字节数	1048576
schema	object	Pipeline 最终输出的 Dataset Schema。键为字段名称，值中的 type 支持 text、long、double、json；字段顺序以 keys 为准	{"status":{"type":"long"}}
	object	schema 说明对象
type	string	Dataset 字段类型，支持 text、long、double、json	text
terms	array<object>	列的类型与聚合信息	[{"column":"status","type":"long"}]
	object	列的类型与聚合信息
whereQuery	string	过滤条件 SPL 语句	status: 200
requestId	string	请求 Id，用于排查问题时定位本次请求	9ACFB10A-1B2C-3D4E-5F6G-7H8I9J0K1L2M

data 为样本行集合（数组内 map），仅包含前 N 行（默认最多 5 行），不反映完整写入计划。
meta.limited 表示是否命中行数限制，为 true 时当前数据为截断子集。
meta.mode 描述执行模式（spl / sql / hybrid），可用于理解查询降级行为。
meta.columnTypes 提供列名到数据类型的映射（string / long / double / json）。
meta.processedRows / processedBytes / scanBytes / cpuSec / cpuCores 反映资源消耗，可用于创建流水线前的容量估算。
若预览未命中数据，data 为空数组，meta.count=0，requestId 仍返回以便日志定位。

示例

正常返回示例

JSON格式

{
  "data": [
    {
      "key": "[{'type': 'saturation', 'value': 0}, {'type': 'load', 'value': 0}, {'type': 'latency', 'value': 1}, {'type': 'error', 'value': 0}]"
    }
  ],
  "meta": {
    "aggQuery": "* | SELECT status, count(*) AS cnt GROUP BY status",
    "columnTypes": [
      "string"
    ],
    "count": 100,
    "cpuCores": 2,
    "cpuSec": 0.5,
    "elapsedMillisecond": 1200,
    "hasSQL": true,
    "isAccurate": true,
    "keys": [
      "[]"
    ],
    "limited": 5,
    "mode": 1,
    "processedBytes": 524288,
    "processedRows": 10000,
    "progress": "Complete",
    "scanBytes": 1048576,
    "schema": {
      "key": {
        "type": "text"
      }
    },
    "terms": [
      {
        "test": "test",
        "test2": 1
      }
    ],
    "whereQuery": "status: 200"
  },
  "requestId": "9ACFB10A-1B2C-3D4E-5F6G-7H8I9J0K1L2M"
}

错误码

访问错误中心查看更多错误码。

变更历史

更多信息，参考变更详情。