企业官网建设流程全解析

Genkit JS Agent Artifacts 实战：用artifacts()中间件让 Agent 产出与管理命名交付物（Beta）

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills

导读：Artifacts（Beta）是 Genkit JS 智能体会话中的一项交付物机制，让 Agent 在会话过程中以命名文件的形式产出代码、报告、文档等内容，并支持按名称去重、会话内追溯读取以及跨子 Agent 共享。读完本文，你将掌握如何用artifacts()中间件一行代码为 Agent 注入write_artifact/read_artifact工具、理解Artifact数据结构与ai.currentSession()的程序化访问方式，并能结合agents()中间件把子 Agent 的产出聚合到编排者会话中。本文内容以仓库中 agents-artifacts.md 为骨架，并辅以 Genkit JS 技能包内其余 Agent 参考文档进行源码级印证。

Artifacts 是什么：Agent 会话中的命名交付物

在 Genkit 的 Agent 模型中，一次会话（session）不只包含消息历史与自定义状态，还可以持有Artifacts——Agent 在会话过程中产生的、携带内容的命名交付物，典型形态包括文件、报告、代码片段等。它把"模型产出了什么"从回复文本中剥离出来，变成会话内结构化的、可追溯、可按名读取的对象集合。

从 agents.md 对会话状态的描述可以看出，Artifacts 与消息、自定义数据并列，是会话状态的三个组成部分之一（messages+ custom data + artifacts），因此它天然具备以下特性：

• 归属会话：Artifacts 存活于会话（session）生命周期内，随会话快照传递；
• 按名称去重：同一会话中再次写入同名 Artifact 会替换旧内容（dedup by name）；
• 随响应返回：Agent 端在res.artifacts中返回，客户端则在chat.artifacts上持续跟踪。

import type { Artifact } from 'genkit/beta'; // 一次生成后，Agent 的产出可从响应中直接取到 const res = await chat.send('Write poem.txt with a poem about Genkit'); console.log(res.artifacts); // Artifact[]

需要说明的是，该 API 目前处于Beta / preview阶段：artifacts()中间件来自@genkit-ai/middleware，Artifact类型来自genkit/beta，导入路径与签名未来可能变化。使用前请先阅读 agents.md 建立 Agent 基础认知。

一行配置：用artifacts()中间件给模型装配读写工具

Artifacts 的核心接入方式不是手写工具，而是通过@genkit-ai/middleware包导出的artifacts()中间件工厂函数。将它放入 Agent 的use: [...]数组后，中间件会自动完成两件事：

1. 注入两个工具：write_artifact（按名称写入/覆盖一个 Artifact）与read_artifact（读取已创建的 Artifact），模型在回合内可以自行调用，无需任何自定义工具代码；
2. 注入系统提示清单：每个回合都会在系统提示中注入一个<artifacts>列表，包含当前会话内 Artifact 的名称与大小（而非完整内容），让模型知道当前已有哪些交付物。

import { artifacts } from '@genkit-ai/middleware'; import { ai } from './genkit.js'; export const workspaceAgent = ai.defineAgent({ name: 'workspaceAgent', system: `You are a code generation assistant. Use write_artifact to create files (pass the filename as "name" and the full content as "content"). Use read_artifact to review or modify a previously created file.`, use: [artifacts()], });

运行后，模型会通过工具调用产出 Artifact，并在响应中一并返回：

const chat = workspaceAgent.chat(); const res = await chat.send('Write poem.txt with a poem about Genkit'); console.log(res.artifacts); // Artifact[]

从中间件机制看，这正是@genkit-ai/middleware包"以中间件提供横切能力"设计哲学的体现：如 middleware.md 所述，artifacts()属于该包导出的七个现成中间件工厂之一，其底层实现方式对应 middleware-custom.md 中描述的tools: ToolAction[]静态工具注入钩子——即"当中间件激活时，把工具静态注入到生成请求中"，这正是artifacts()/filesystem()添加工具的实现机制。

readonly选项：只读模式

artifacts()支持一个配置项：

readonly: true的典型场景是编排者（orchestrator）：编排者应当审阅而非生产子 Agent 的产出，因此只给它读取能力，避免它越权改写子 Agent 的交付物。该用法与 agents-multi-agent.md 中的编排者配置完全对应（详见下文"跨 Agent 共享"一节）。

Artifact数据结构：name、parts 与 metadata

Artifact类型从genkit/beta导入，其结构非常轻量：内容存放在parts数组中（以 text part 形式承载），metadata为可选字段。

import type { Artifact } from 'genkit/beta'; // 一个 Artifact 的内容存放在 parts（text parts）中，metadata 可选 const artifact: Artifact = { name: 'poem.txt', parts: [{ text: 'Roses are red…' }], metadata: { source: 'workspaceAgent' }, // optional };

需要牢记的两个语义：

• 内容在parts中：Artifact 采用与 Genkit 消息一致的多模态 part 结构，text part 承载文本内容，这也为未来承载多模态内容保留了空间；
• 同名即替换：向会话中再次写入相同name的 Artifact，会替换旧版本（按名称去重），而不是追加或报错。

程序化访问：在工具与自定义 Agent 内部读写 Artifacts

除了让模型通过write_artifact/read_artifact工具操作外，开发者还可以在自定义工具或自定义 Agent 的回合内，通过活动会话（active session）以编程方式访问 Artifacts。核心入口是ai.currentSession()：

const session = ai.currentSession(); // 读取全部 Artifacts： const all = session.getArtifacts(); // Artifact[] const found = all.find((a) => a.name === 'poem.txt'); // 创建 / 替换 Artifacts： session.addArtifacts([{ name: 'notes.md', parts: [{ text: '# Notes' }] }]);

重要边界：ai.currentSession()在不存在活动会话时会抛出异常——例如在未被 Agent 回合驱动的工具调用中调用它。因此该 API 只能在 Agent 回合内部使用。这与 agents-state.md 中对ai.currentSession<S>()的约束完全一致：工具内访问活动会话是"读取并变更会话状态"的统一入口，getArtifacts()/addArtifacts()与getCustom()/updateCustom()并列，共同构成工具侧操作会话数据的两种途径。从设计意图推断，将 Artifacts 与自定义状态分开管理，是为了把"面向模型交付的结构化产物"与"面向业务逻辑的内部状态"解耦。

客户端读取：remoteAgent上的chat.artifacts

当 Agent 通过 HTTP 服务暴露时（expressHandler，参见 agents.md），浏览器或 Node 客户端通过genkit/beta/client的remoteAgent消费 Agent。Artifacts 在客户端有两处呈现：

• res.artifacts：本回合产生的 Artifacts；
• chat.artifacts：会话累计跟踪的全部Artifacts（含历史回合）。

import { remoteAgent } from 'genkit/beta/client'; const agent = remoteAgent({ url: '/api/workspaceAgent' }); const chat = agent.chat(); const res = await chat.send('Create index.html and styles.css'); console.log(res.artifacts); // Artifact[] produced this turn console.log(chat.artifacts); // all artifacts tracked for the session

这里的"客户端跟踪"与 agents.md 中"客户端管理状态（client-managed state）"模型一脉相承：当 Agent 未配置store时，服务端无状态，会话状态块（消息 + 自定义数据 + artifacts）由调用方持有，remoteAgent客户端在每轮自动携带并在本地维护chat.artifacts。因此客户端侧读取 Artifacts 不需要额外的服务端存储设施。

跨 Agent 共享：artifactStrategy: 'session'与只读编排者

在多 Agent 编排场景（agents-multi-agent.md）中，子 Agent 会产出各自的 Artifacts，如何让编排者拿到这些产出是关键问题。agents()中间件提供artifactStrategy配置：

官方推荐的多 Agent 共享模式是：子 Agent 各自携带artifacts()产出交付物，编排者设置artifactStrategy: 'session'并把产出归并进父会话，同时给编排者加artifacts({ readonly: true })使其只能读取、不能改写：

use: [ agents({ agents: ['researcher', 'coder'], artifactStrategy: 'session' }), artifacts({ readonly: true }), ];

具体到完整编排者定义（取自 agents-multi-agent.md 的示例模式）：

import { agents, artifacts, retry } from '@genkit-ai/middleware'; import { ai } from './genkit.js'; export const orchestratorAgent = ai.defineAgent({ name: 'orchestratorAgent', system: `You are a helpful project assistant. Analyze the request and delegate to the appropriate sub-agent. If it needs research AND code, call them sequentially, then synthesize a final answer.`, use: [ agents({ agents: [ 'researcher', // description 自动发现 { name: 'coder', description: 'Writes, debugs, and explains code.' }, ], maxDelegations: 5, artifactStrategy: 'session', // 子 Agent 产出合并进父会话 }), artifacts({ readonly: true }), // 编排者通过 read_artifact 读取 retry(), ], });

与之配套，子 Agent 侧通过artifacts()生产交付物（如researcher用write_artifact保存调研结果、coder用write_artifact保存代码）。需要留意两点细节：

• 命名空间化：'session'策略下合并进父会话的 Artifacts 会按调用 ID 命名空间化，即<agentName>_<rand>/<name>，避免不同子 Agent 的同名产物冲突；
• 读取链路：由于工具结果只返回名称，编排者必须拥有read_artifact（这正是artifacts({ readonly: true })的注入效果）才能按需拉取内容，两者是配套使用的。

从架构上看，这种"子 Agent 生产、编排者按需读取"的设计，将大体积内容（如完整代码文件）从每次委派的工具结果中剥离，避免在模型上下文与工具往返中反复搬运全部内容，属于典型的按需加载（lazy fetch）模式。

注意事项与边界

围绕 Artifacts 的使用，有以下几点实践提醒：

1. Beta API：artifacts()与Artifact均属预览接口（前者来自@genkit-ai/middleware，后者来自genkit/beta），导入路径与签名可能随版本变化；Agent 整体 API 要求genkit >= 1.39.0（见 SKILL.md 与 agents.md）。
2. 会话归属：Artifacts 存在于会话中，不配置store时由客户端（remoteAgent）持有并随每轮往返；配置 会话存储（InMemorySessionStore/FileSessionStore/FirestoreSessionStore）时则由服务端持久化。
3. currentSession()的调用时机：仅在 Agent 回合内部（工具执行、自定义 Agent 逻辑）可安全调用，否则抛异常。
4. 同名覆盖语义：写入同名 Artifact 是替换而非合并，设计会话内文件版本时需要自行把握（如需历史版本，可改用带版本号或时间戳的命名）。
5. 只读编排者：编排者如需审阅子 Agent 产物，务必使用artifactStrategy: 'session'+artifacts({ readonly: true })组合，而非让编排者直接改写子 Agent 的交付物。

小结

Artifacts 是 Genkit JS Agent 会话模型的重要组成：它以@genkit-ai/middleware的artifacts()中间件为入口，无需手写工具即可赋予模型write_artifact/read_artifact能力；以genkit/beta的Artifact类型（name + parts + metadata）为统一数据结构，按名称去重、随响应返回；在多 Agent 场景下配合agents()的artifactStrategy: 'session'与只读artifacts()，实现子 Agent 产出的聚合与按需审阅。建议结合 agents.md、agents-state.md 与 agents-multi-agent.md 阅读，以在真实编码助手、报告生成器或多 Agent 工作流中组合运用 Artifacts、会话状态与中间件体系。

【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills