← 全部文章
Agent 与 AI··约 6 分钟·

Agent 产物：怎样保存、交付和复用结果

Agent 为一次分析写出的脚本，下个月还能继续用吗？从这个需求出发，理解 Artifact 的定义、类型，以及保存、管理和复用的实际过程。

Agent 产物：怎样保存、交付和复用结果
文章目录
  1. 这次写好的脚本，下个月还能用吗
  2. Artifact 指的是哪一份东西
  3. 除了脚本，还会留下哪些产物
  4. 怎样把脚本保存好、管理起来
  5. 下一次任务，Agent 怎样取回并复用
  6. 参考资料

这次写好的脚本，下个月还能用吗

假设你有一份订单明细，记录了连续两个月的订单日期、地区和金额。你把它交给 Agent，想知道各地区的销售额，以及第二个月比第一个月增长了多少。

面对大量订单，Agent 选择用程序计算。它先查看字段和几条记录，确认日期格式、地区名称和金额单位，再编写一个分析脚本：读取订单，按月份和地区分组，汇总销售额，计算增长率。

随后，Agent 通过执行工具运行脚本，生成汇总表，再根据表中的数据给出分析结论。

这次任务解决了。但这样的分析每个月都要做，如果处理规则没有变化，下次换一份数据，我们希望 Agent 能继续使用这份脚本。

怎样把 Agent 生成的脚本留下来，让它在后续任务中能够被找到、再次使用？

这就引出了 Artifact（产物）及其管理机制。已有 Agent 框架提供了保存、读取和版本管理等能力，例如 Google ADK。要理解这些能力怎样支持复用，先从“产物”本身说起。

Artifact 指的是哪一份东西

Artifact 可以译为“产物”。在本文讨论的任务场景中，它指 Agent 生成的一份具体成果，可以被单独保存、交付，或供后续任务继续使用。

刚才的分析脚本是一份产物，脚本生成的汇总表也是。脚本留下了处理方法，汇总表留下了这次计算的结果。

用户可以下载汇总表，发给同事查看；Agent 下次也可以取回脚本，处理新的订单。产物的用途由任务决定，有的用来交付结果，有的值得长期保留、反复使用。

同一份分析脚本处理两次任务的数据，分别生成对应的汇总结果

以后再遇到“把产物沉淀成资产”这样的说法，可以先理解成一件具体的事：把有用的成果连同必要说明整理好，供后续任务使用。比如这份脚本经过验证、写清输入要求后，就可以成为每月分析时可用的资产。

不同框架使用 Artifact 这个词时，管理范围有所不同。本文先从生成的成果理解它；像 Google ADK，也会把用户上传的文件和任务中的中间文件纳入产物管理。

除了脚本，还会留下哪些产物

从内容形式看，常见产物可以这样理解：

产物 可以怎样使用
分析报告、调研文档 供用户阅读、修改，或交给同事继续处理
汇总表、清洗后的数据 核对计算结果，或作为下一步分析的输入
图表、图片 展示数据关系，或放进报告、演示文稿
音频、视频 作为配音、课程或其他内容的交付结果
脚本、查询语句 保存处理方法，在合适的数据上再次执行

这些产物不一定都直接交给用户。销售分析时，用户可能只要最终报告，但 Agent 在处理中还会生成清洗后的数据和汇总表；后续步骤需要它们，就有保留的理由。

也不必保存任务中产生的每一个临时文件。对于这个月度分析任务，我们先把最值得复用的脚本留下来，看看具体怎样做。

怎样把脚本保存好、管理起来

脚本最初可能只是执行目录里的一个文件。后续任务如果换了目录，或原目录被清理，就无法继续依赖这个位置。要长期使用，Agent 需要通过保存工具，把脚本内容交给会持续保留它的存储。

以 Google ADK 为例，框架把负责保存和取回内容的组件叫作 Artifact Service，即产物服务。开发者在搭建 Agent 时选择存储方式：本地运行可以使用指定目录，云端也可以使用 Google Cloud Storage。接好这个组件后，Agent 的工具执行程序就能调用保存、读取等接口。

这里有两份信息需要一起留下：一份是脚本内容，另一份是以后使用它需要知道的说明。

例如，这份脚本的说明可以写成：按月份和地区汇总销售额；输入是包含日期、地区、金额三列的 CSV；金额单位为元；使用 Python 运行；输出各地区销售额和增长率。文件名能帮助定位，说明能帮助判断这份脚本是否适合当前任务。

ADK 允许保存时附带这种描述信息，称为 metadata，也就是描述产物的数据。框架会保存开发者传入的说明；“用途”“输入要求”等内容，需要保存工具准备好。

保存工具把脚本内容、用途与输入要求交给产物存储，后续任务再取回脚本使用

下面用 ADK Python 2.8.0 的接口看一次保存。script_bytes 是工具从脚本文件里读出的内容，usage_info 是刚才那份使用说明。

version = await tool_context.save_artifact(
    filename="user:sales-analysis.py",
    artifact=types.Part.from_bytes(
        data=script_bytes,
        mime_type="text/x-python",
    ),
    custom_metadata=usage_info,
)

tool_context 是 ADK 在执行工具时提供的对象，它带着当前用户、本次对话和产物服务等信息。调用它的保存方法，就会把文件交给已经配置好的产物服务。Part.from_bytes 负责把文件内容包装成接口接收的形式，text/x-python 说明内容是 Python 脚本。

文件名前的 user: 是 ADK 的一项约定：把这份产物放在当前用户的范围内，方便同一用户在后续对话中取回。因为我们想下个月继续用，这里选择用户范围；只供本次对话使用的文件，可以采用会话范围，也就是限定在这次对话里。

保存成功后，接口返回版本号。假如第一份脚本是版本 0，后来增加了数据检查，再以同名保存，就会得到新版本。下次读取时，可以明确指定要用哪一版；保存过新版本，也仍然能够取回旧版。

这样，脚本有了保存位置、名称、使用说明和版本。Agent 下次就有办法找到它，而用户要下载脚本时，也可以通过读取接口取回文件内容。

下一次任务，Agent 怎样取回并复用

下个月，你交来新数据，并要求“沿用上次的分析方法”。要做到这一点，Agent 需要能通过工具查到已有产物。

ADK 提供了列举文件、读取版本信息和加载内容的接口。开发者可以把这些接口接进工具：先列出当前用户可用的产物，再取出名称、版本和使用说明，返回给模型。模型看到“按月份和地区汇总销售额”这条说明，才有依据判断它是否适合这次请求。

选定脚本后，工具执行程序按名称和版本读取内容：

part = await tool_context.load_artifact(
    "user:sales-analysis.py",
    version=0,
)

读取成功后，工具把返回的脚本内容写入这次任务的执行目录。随后，Agent 检查新数据是否符合输入要求，再通过执行工具运行脚本，生成新的汇总表。

例如，新表仍有日期、地区和金额三列，但金额单位改成了万元，就需要先统一单位。直接把原数值交给按“元”计算的脚本，会让销售额结论出错。所以，Agent 取回脚本后，要先根据使用说明检查新数据的字段和单位，必要时做相应转换，再运行脚本。

为了验证脚本能否在后续任务中复用，我们用两批模拟订单做了一个本地实验：先保存脚本，再换一个执行目录，取回脚本处理新数据。实验由测试程序依次完成这些操作，模拟 Agent 复用脚本的过程。

第一次处理五月、六月的订单，保存脚本后删除原执行目录。随后启动新的 Python 进程，换到另一段对话，从产物服务取回版本 0，处理六月、七月的数据。取回后的脚本内容与最初保存的文件完全一致。

本地实际运行结果：更换执行目录和对话后取回同一脚本，处理新订单并通过结果检查；数据为模拟订单

下个月，Agent 就可以从已有脚本继续完成分析：确认新数据适用，取回并运行脚本，再把这次计算出的汇总表交给用户。处理方法被保留下来，分析结果则随新数据重新生成。

参考资料