Agent training · Data formats

Agent 轨迹如何变成 Foundation Model 训练数据From Agent Traces to Foundation Model Training Dataエージェントの軌跡を基盤モデルの学習データへ

Agent 读文件、调用工具、检查结果,再决定下一步。训练数据需要保留这条因果链,同时告诉模型:哪些内容用来理解上下文,哪些动作需要学会。An agent reads files, calls tools, inspects results, and chooses its next action. Training data must preserve that causal chain—and distinguish the context the model reads from the actions it should learn.エージェントはファイルを読み、ツールを呼び、結果を確認して次の行動を決める。学習データには、この因果関係と、読むための文脈・学習する行動の区別が必要になる。

2026 年 10 月 · 数据工程October 2026 · Data engineering2026年10月 · データエンジニアリング

这里沿着一次 CLI Agent 数据导出,拆开看这套面向基础模型的文本轨迹格式:一条完整会话放进一行 Parquet,消息变成有序片段,片段再标出是否参与训练损失。This walkthrough follows a CLI-agent data export for foundation-model training: one full conversation per Parquet row, messages serialized into ordered segments, and a loss flag on each segment.CLIエージェントのデータ出力を例に、Parquetのテキスト軌跡形式を見ていく。会話全体をParquetの1行に収め、メッセージを順序付きの断片に変換し、各断片に損失計算の対象かどうかを記録する。

静态图Static figure静止図从轨迹到训练文件
先固定轨迹,再转换协议与监督位置,最后检查文件与训练准入。Fix the source traces first, then serialize and mask them; check both file integrity and training admission.元の軌跡を確定し、形式と学習対象を変換してから、ファイルと学習への受け入れを確認する。

同一个 CaseThe same case同じCase

沿用库存搭建案例,看一轮工具调用如何从原始消息变成训练输入。Follow one tool-call turn from the inventory case into the two training formats.在庫構築Caseのツール呼び出し1ターンを、元のメッセージから二つの学習形式へ変換する。

渔具库存系统Fishing-tackle inventory釣具の在庫管理13 轮 · 32 条消息13 turns · 32 messages13ターン · 32メッセージ
用户需求:按渠道管理件数与箱数,记录出入库、操作人和时间。Task: track units and cartons by channel, with stock movements, operators, and timestamps.依頼:販路別の個数・箱数と、入出庫・操作者・日時を管理する。
T10 交付前,读回已写入的库存Before delivery, read back the stored inventory引き渡す前に、登録した在庫を読み戻す
assistant · Bash

读取产品库存Read product inventory商品在庫を読む

lark-cli base +record-list --base-token "<base>" --table-id "<products>" --as user
tool · 返回节选Result excerpt戻り値の抜粋

6 条产品记录6 product records商品レコード6件

米诺路亚假饵 110mmMinnow lure · 110 mmミノールアー 110 mm
1,260 件units個 / 42 箱cartons箱
count=6 · has_more=false
T11核对出入库记录Read stock movements入出庫履歴を確認
查看消息字段Message fieldsメッセージのフィールド
roleassistant
contentnull
tool_calls[0].idcall_10
function.nameBash
function.arguments{"command":"lark-cli base +record-list --base-token \"<base>\" --table-id \"<products>\" --as user","description":"Read product inventory"}JSON string
tool.tool_call_idcall_10
tool.content[0].textMarkdown 表格 + 分页信息Markdown table + paginationMarkdown表 + ページ情報string

资源 ID 用别名,description 已翻译;推理正文省略。Resource IDs are aliased and the description translated; reasoning text is omitted.リソースIDは別名、descriptionは翻訳表記。推論本文は省略。

第一步:先选轨迹,再按任务划分1. Select traces, then split by task1. 軌跡を選び、タスク単位で分割する

质量筛选发生在格式转换之前。同一条轨迹可能被多次评审、在多个批次出现,因此要先固定筛选条件,再去重并保留来源。训练集与测试集按 query 分组,同一个问题的多次尝试不跨集合。Quality selection comes before format conversion. A trajectory may be evaluated repeatedly or appear in several batches, so selection rules are fixed before deduplication, with provenance retained. Splits are grouped by query so repeated attempts at the same task stay together.品質による選別は形式変換より先に行う。同じ軌跡が複数回評価されたり、複数のバッチに現れたりするため、選別条件を固定したうえで重複を除き、出典を残す。データ分割はquery単位とし、同じ問題への再試行を別集合に分けない。

另一次 207 条轨迹的批量导出,Parquet 得到 207 行,方舟逐目标导出得到 6,078 行。两者使用同一批任务与动作,差别在于样本的组织方式。A separate batch of 207 traces produced 207 Parquet rows and 6,078 target-wise Ark rows. Both exports use the same tasks and actions, organized into different sample units.別バッチの207本の軌跡から、Parquetは207行、対象別のArk出力は6,078行になった。タスクと行動は共通で、サンプルのまとめ方が異なる。

划分Split分割完整轨迹行Full-trajectory rows軌跡単位の行数assistant 学习目标Assistant targetsassistantの学習対象
训练集Train訓練1865,458
测试集Testテスト21620
合计Total合計2076,078

Parquet 一行里可以有多个学习目标。逐目标展开则为每个目标携带它之前的历史。这次两种导出对历史推理的处理也不同:Parquet 版本保留各轮原生推理,方舟版本未在历史 assistant 上重复携带 reasoning_content。因此不能把行数直接解释成数据量或训练成本的倍数。A Parquet row can contain many supervised targets. Target-wise expansion repeats the preceding history for each target. These exports also handle past reasoning differently: Parquet retains native reasoning across turns, while this Ark version does not carry historical assistant reasoning_content. The row ratio is therefore not a ratio of independent data or training cost.Parquetの1行には複数の学習対象が入る。対象ごとの展開では、それぞれに先行する履歴を付ける。この比較では過去の推論の扱いも異なり、Parquetは各ターンの推論を保持するが、Ark版は履歴中のassistantのreasoning_contentを含めない。行数比を独立なデータ量や学習コストの比とみなすことはできない。

为什么和方舟提训格式不同Why the Ark training format differsArkの学習形式と何が違うのか

这次使用的方舟 LLMSft 接口接收 JSONL,每行保留 messages 与 tools 等结构化字段。Parquet 导出则提前完成协议拼接,把带监督标记的输入片段写入 Parquet。区别在于,哪些转换由数据侧做,哪些交给训练平台做。The Ark LLMSft interface used here takes JSONL with structured fields such as messages and tools. The Parquet export prepares the protocol sequence in advance and stores loss-marked segments in Parquet. The key difference is where preparation happens: in the dataset exporter or in the training platform.今回使ったArk LLMSftは、messagesやtoolsなどの構造化フィールドをJSONLで受け取る。Parquet出力は、プロトコルに沿った系列を事前に作り、学習対象を指定した断片をParquetに保存する。違いは、どの変換をデータ側で行い、どこから学習基盤に任せるかにある。

比较项Aspect比較項目本次方舟 JSONLArk JSONL used here今回のArk JSONL本次 Parquet 导出Parquet export used here今回のParquet出力
文件与字段File and fieldsファイルとフィールド每行 JSON;messages / toolsOne JSON object per line; messages / tools1行1JSON。messages / tools四列;inputs 内是协议片段Four columns; inputs holds protocol segments4列。inputsにプロトコル断片
样本单位Sample unitサンプル単位历史前缀 + 一个 assistant 目标History prefix + one assistant target先行履歴 + assistantの1対象完整轨迹 + 多个 assistant 目标Full trace + multiple assistant targets全軌跡 + assistantの複数対象
工具动作Tool actionsツールの行動原生 tool_calls 与 tools schemaNative tool_calls and tools schemasネイティブなtool_callsとtoolsスキーマFunctionSP + XML65 调用文本FunctionSP + XML65 call textFunctionSP + XML65呼び出し本文
推理内容Reasoning推論内容当前目标用 reasoning_content;历史不重复携带reasoning_content on the current target, not past assistants現在の対象にreasoning_content。過去のassistantには含めない各轮原生推理序列化进正文Each turn’s native reasoning in the serialized body各ターンの推論を本文へ直列化
监督位置Supervision学習対象の指定历史 assistant 的 loss_weight=0,当前目标=1Past assistants: loss_weight=0; current target: 1過去のassistantはloss_weight=0、現在の対象は1按片段设置 has_loss;本批监督全部 assistant 正文与 EOSSegment-level has_loss; all assistant bodies and EOS in this batch断片ごとのhas_loss。本バッチは全assistant本文とEOSを対象とする
长度核算Length accounting長さの計測逐目标计算当行历史与目标长度Check each prefix-and-target row各行の履歴と対象を計測计算完整会话、协议头与各轮推理Check the full conversation, headers, and reasoning全会話、ヘッダー、各ターンの推論を計測

下面把同一条两次动作的轨迹拆开。Q 是请求,A₁、A₂ 是两次 assistant 输出,Tool 是第一次动作的真实返回。方舟逐目标导出为两行;Parquet 版本把两个目标保留在同一行。The diagram follows a trace with two assistant actions. Q is the request, A₁ and A₂ are assistant outputs, and Tool is the actual result of the first action. The target-wise Ark export makes two rows; Parquet retains both targets in one row.次の図はassistantの行動が2回ある軌跡を示す。Qは依頼、A₁とA₂はassistant出力、Toolは最初の行動の実際の応答。対象ごとに展開するArk出力は2行、Parquetは両方の対象を1行に収める。

静态图Static figure静止図同一段轨迹,两种组织方式
示意:两条逐目标样本,对应一条包含两个目标的完整轨迹。系统前缀在图中省略。Schematic: two target-wise samples correspond to one full trace with two targets. System prefixes are omitted.模式図:対象別の2サンプルと、2対象を含む全軌跡の1サンプル。システム前置部は省略。

逐目标展开,是我们为当次方舟 reasoning_content 提训约定采用的导出方式;多轮上下文仍然存在。这里的片段格式可以直接标记一条长序列中的多个目标,于是这条导出路径选择保留完整轨迹。JSONL 和 Parquet 都只是容器,本身并不强制单目标或多目标。Target-wise expansion was our export choice for that Ark reasoning_content training contract; multi-turn context is still present. This segmented format can mark multiple targets within a long sequence, so this export keeps the full trace. JSONL and Parquet are containers: neither inherently requires single-target or multi-target training.対象ごとの展開は、当時のArkのreasoning_content学習仕様に合わせた出力方法であり、複数ターンの文脈は残っている。Parquetの断片形式は長い系列内の複数学習対象を直接指定できるため、この出力では全軌跡を保持した。JSONLとParquetは容器であり、単一対象か複数対象かを本質的に決めるものではない。

因此,迁移数据不能只把后缀从 jsonl 改成 parquet。需要重新对齐工具协议、推理区段、监督标记和长度检查;比较效果时,也要固定原始轨迹和划分,核对两边实际看见的历史是否相同。Migration therefore requires more than changing a file extension. Tool protocols, reasoning sections, supervision masks, and length checks must be aligned. A meaningful comparison fixes the source traces and splits, then checks whether both training paths actually receive the same history.移行は拡張子を変えるだけでは済まない。ツールの形式、推論区間、教師信号、長さの検証を合わせ直す必要がある。効果を比べる際は元の軌跡と分割を固定し、両方に渡る履歴が実際に同じかを確かめる。

第二步:把动作写成模型要读的协议2. Serialize actions into the model’s protocol2. 行動をモデルが読む形式に変換する

输入开头有三段系统消息:ThinkSP 约定推理与回答的表达方式,FunctionSP 描述工具及其参数,MainSP 保留任务本身的规则。旧记录只有 MainSP 时补齐协议头;已经有三段时校验并规范化,避免重复追加。Three system messages lead the input: ThinkSP defines the reasoning-and-answer convention, FunctionSP describes tools and their parameters, and MainSP retains the task instructions. Legacy records with only MainSP receive the protocol headers; existing three-part prefixes are checked and normalized instead of appended again.入力の先頭は3つのシステムメッセージで構成する。ThinkSPは推論と回答の表現、FunctionSPはツールと引数、MainSPはタスクの指示を担う。MainSPだけの旧記録にはプロトコルのヘッダーを補い、3段構成がある記録は確認して正規化し、重複追加を避ける。

assistant 原来分开的 reasoning_content、content 和 tool_calls,在目标训练序列中合成一段文本:推理区段、回答正文、XML65 工具调用。真实工具返回仍留在下一条 tool 消息中,不搬进模型的回答。The assistant’s separate reasoning_content, content, and tool_calls fields become one text payload in the target training sequence: a reasoning section, answer text, and XML65 tool calls. Actual tool results remain in the following tool messages, not in the assistant’s answer.assistantのreasoning_content、content、tool_callsは、Parquetの列では推論区間、回答本文、XML65のツール呼び出しを含む1つの本文になる。実際の実行結果は後続のtoolメッセージに残し、assistantの回答には移さない。

静态图Static figure静止図把原生 assistant 转成协议文本
三类原生字段合成 assistant 正文;工具返回保持为独立的 tool 消息。Three native fields form the assistant payload; the tool response remains a separate message.3種類の元フィールドをassistant本文にまとめ、ツール応答は別のメッセージに保つ。

库存案例中的 Read 动作,转换后仍是读取同一个文件,只是调用写法变为 XML65。下面省略实际路径;推理区段也要使用目标协议的标签。The inventory case’s Read action still reads the same file after conversion; its call is now written in XML65. The actual path is omitted below. The reasoning section must also use the target protocol’s tags.在庫CaseのReadは変換後も同じファイルを読む。変わるのはXML65での呼び出し表現だ。以下では実際のパスを省略した。推論区間にも対象プロトコルのタグを使う。

<seed:tool_call><function name="Read">
  <parameter name="file_path" string="true">[original path omitted]</parameter>
</function></seed:tool_call>

字符串参数带 string="true";数字、布尔值和对象等用 JSON 表达,并标记 string="false"。这属于模型的序列化协议,不是普通网页 XML:命令和文件内容不能被额外 HTML 转义,也不能被一个通用格式化器悄悄改写。String arguments use string="true". Numbers, booleans, and objects use JSON representations with string="false". This is a model serialization protocol, not ordinary web XML: commands and file contents must not be additionally HTML-escaped or silently rewritten by a generic formatter.文字列引数にはstring="true"を付ける。数値・真偽値・オブジェクトなどはJSONで表し、string="false"とする。これはモデル向けの直列化プロトコルであり、通常のWeb用XMLではない。コマンドやファイル内容を追加でHTMLエスケープしたり、汎用フォーマッターで書き換えたりしない。

第三步:上下文都能读,只有部分要学3. Read the context; learn the selected outputs3. 文脈を読み、指定された出力を学習する

每条消息被拆成四段:起始标记、角色、正文、结束标记。每段都有 type、text 和 has_loss。type 告诉加载器如何处理这一段;has_loss 决定它是否成为需要预测的训练目标。Each message becomes four segments: a start marker, role, body, and end marker. Every segment carries type, text, and has_loss. The type guides the loader; has_loss determines whether the segment contributes supervised prediction targets.各メッセージは開始マーカー、役割、本文、終了マーカーの4断片になる。それぞれにtype、text、has_lossを持たせる。typeはローダーでの扱いを、has_lossは予測の学習対象に含めるかどうかを指定する。

这批导出把 assistant 正文和结束标记设为 1;system、user、tool 以及消息起始和角色标记设为 0。也就是说,模型学习怎么思考、回答和调用工具,但不用学习扮演环境、伪造工具返回。In this export, assistant bodies and end markers are marked 1. System, user, and tool content, plus message-start and role markers, are marked 0. The model is trained on its reasoning, answers, and tool calls—not on impersonating the environment’s responses.この出力ではassistantの本文と終了マーカーを1にし、system・user・toolの内容、開始マーカー、役割マーカーを0にする。モデルが学ぶのは推論、回答、ツール呼び出しであり、環境の応答を生成することではない。

静态图Static figure静止図一条序列中的上下文与学习目标
上方显示各消息正文的监督标记;下方展开一条 assistant 消息。Top: supervision of message bodies. Below: the segments of one assistant message.上段は各メッセージ本文の学習対象の指定、下段はassistantメッセージの断片構成。

has_loss=0 不会把内容从输入中删掉。工具返回不计损失,后面的 assistant 仍然能读到它。若轨迹中保留了教师纠正提示,即使提示本身不计损失,也仍会影响后续输出;是否保留它,要在数据策略里另行决定。has_loss=0 does not remove content from the input. A tool result can carry no loss and still inform the next assistant action. The same applies to a retained teacher correction: masking its loss does not remove its influence. Whether to keep that guidance is a separate dataset decision.has_loss=0にしても入力から内容は消えない。ツール応答を損失対象外にしても、後続のassistantはそれを読める。教師の訂正指示も同様で、損失を除外しても影響は残る。指示を残すかどうかはデータ方針として別に決める。

一行包含未来的工具返回,也不代表前面的动作可以提前看见它。因果注意力只允许读取当前位置之前的内容;loss mask 则决定哪些位置计算损失。可见范围与监督范围是两件事。Storing later tool results in the same row does not let an earlier action see them. Causal attention restricts each position to its preceding context; the loss mask selects which positions contribute to the objective. Visibility and supervision are separate controls.同じ行に後のツール応答があっても、前の行動が先読みできるわけではない。因果的注意は先行する内容だけを参照可能にし、loss maskは損失を計算する位置を選ぶ。参照範囲と教師信号の範囲は別の制御である。

第四步:用四列封装,读回后再检查4. Package four columns, then read them back4. 4列にまとめ、読み戻して確認する

Parquet 是存储容器,聊天协议和监督位置由里面的 inputs 决定。本次文本格式固定四列;inputs 与 metadata 都是 JSON 编码后的字符串,不是 Parquet 的嵌套数组列。Parquet is the storage container. The inputs field determines the conversation protocol and supervised positions. This text-only export has four columns; inputs and metadata are JSON-encoded strings, not nested Parquet array columns.Parquetは保存用の容器であり、会話形式と学習対象の位置はinputsが定める。このテキスト形式は4列で、inputsとmetadataはJSON文字列として保存する。Parquetのネストした配列列ではない。

列名Column列名物理类型Physical type物理型内容Contents内容
imagesbinary空字节;本篇只讨论文本轨迹Empty bytes; this article covers text-only traces空のバイト列。本稿はテキスト軌跡を対象とする
inputsstring有序的 type / text / has_loss 片段数组Ordered type / text / has_loss segmentstype / text / has_lossの順序付き断片
uidstring稳定的轨迹标识Stable trajectory identifier安定した軌跡識別子
metadatastring来源、划分与校验信息;不作为模型正文Provenance, split, and checks; not model text出典・分割・検証情報。モデル本文には入れない

读取 inputs 时做一次 JSON 解析,就得到片段数组。下面以一个示意性的 assistant 文本展示消息边界;完整文件会按时间顺序接上所有消息。Parsing inputs once yields the segment array. The example below uses an illustrative assistant text to show message boundaries; a full row concatenates all messages in chronological order.inputsを一度JSON解析すると断片配列が得られる。以下はassistantの例文でメッセージ境界を示したもの。実際の1行には、全メッセージを時系列でつなげる。

[
  {"type":"special_token", "text":"[CLS]",       "has_loss":0},
  {"type":"special_token", "text":"assistant\n", "has_loss":0},
  {"type":"text",          "text":"[reasoning + text + XML65 call]", "has_loss":1},
  {"type":"special_token", "text":"[EOS]",       "has_loss":1}
]

有两类检查不能省略:格式检查确认列类型、协议、工具配对、loss 标记与读回一致性;训练准入检查使用目标 tokenizer 和加载器,确认整条序列是否满足模型窗口及其他要求。Two checks are essential. Format validation checks column types, protocol, tool pairing, loss flags, and readback equality. Training admission uses the target tokenizer and loader to check the complete sequence against the model’s window and other requirements.省略できない確認は2種類ある。形式検証では列型、プロトコル、ツールの対応、lossの指定、読み戻した内容の一致を調べる。学習への受け入れ確認では対象のtokenizerとローダーを使い、全系列がモデルの文脈長などの要件に収まるかを見る。

完整轨迹往往比“只取最后一轮回答”长得多。前面那批 207 条轨迹中,有 4 条的离线文本 token 估算超过 131,072;它们被完整保留并单列,没有截断。该导出未运行目标训练接口的官方 compute_tokens Checker,所以格式验证通过,不等于这些长样本已通过训练准入。Full trajectories can be much longer than a final-answer-only sample. In the matched batch of 207 traces, offline text-token estimates exceeded 131,072 for four rows. They were retained intact and listed separately, not truncated. That export did not run the target training platform’s official compute_tokens Checker, so a format-valid row is not automatically training-admitted.完全な軌跡は、最終回答だけのサンプルより大幅に長くなりうる。先ほどの207本では、4行のオフライン推定値が131,072トークンを超えた。これらは切り詰めずに保持し、別途一覧化した。この出力では対象の学習基盤が提供する公式のcompute_tokens Checkerを実行していないため、形式の妥当性と学習への受け入れを区別する。

最后,检查模型实际在学什么Check what the model is actually learning最後に、何を学習するのかを確かめる

看一条训练样本,最好能回答三个问题:模型当时看到了什么,下一步要学会输出什么,输出之后环境实际返回了什么。原始轨迹、序列化协议和监督标记对齐之后,Parquet 才成为一份能解释、能复查的训练数据。A training sample should make three things clear: what the model could see, what it was supposed to produce next, and what the environment actually returned. Aligning the original trace, serialization protocol, and supervision flags makes the resulting Parquet inspectable and meaningful.学習サンプルから、モデルが何を見られたか、次に何を出力すべきだったか、その後に環境が何を返したかを確認できるようにする。元の軌跡、直列化プロトコル、教師信号の指定が一致してこそ、Parquetを理解し、検証できる学習データになる。

完整轨迹的生成与修复见For trajectory generation and repair, see軌跡の生成と修復については

Coding Agent 的生成与修复 →Generating and Repairing Coding-Agent Trajectories →Coding Agentの軌跡の生成と修復 →

图源与代码Figures and code図とコード
放大的流程图