Genkit JS Agent Artifacts 实战用artifacts()中间件让 Agent 产出与管理命名交付物Beta【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills导读ArtifactsBeta是 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/middlewareArtifact类型来自genkit/beta导入路径与签名未来可能变化。使用前请先阅读 agents.md 建立 Agent 基础认知。一行配置用artifacts()中间件给模型装配读写工具Artifacts 的核心接入方式不是手写工具而是通过genkit-ai/middleware包导出的artifacts()中间件工厂函数。将它放入 Agent 的use: [...]数组后中间件会自动完成两件事注入两个工具write_artifact按名称写入/覆盖一个 Artifact与read_artifact读取已创建的 Artifact模型在回合内可以自行调用无需任何自定义工具代码注入系统提示清单每个回合都会在系统提示中注入一个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()支持一个配置项选项类型默认值说明readonlybooleanfalse为true时只注入read_artifact模型只能读取、不能创建或更新 Artifactreadonly: true的典型场景是编排者orchestrator编排者应当审阅而非生产子 Agent 的产出因此只给它读取能力避免它越权改写子 Agent 的交付物。该用法与 agents-multi-agent.md 中的编排者配置完全对应详见下文跨 Agent 共享一节。Artifact数据结构name、parts 与 metadataArtifact类型从genkit/beta导入其结构非常轻量内容存放在parts数组中以 text part 形式承载metadata为可选字段。import type { Artifact } from genkit/beta; // 一个 Artifact 的内容存放在 partstext 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.currentSessionS()的约束完全一致工具内访问活动会话是读取并变更会话状态的统一入口getArtifacts()/addArtifacts()与getCustom()/updateCustom()并列共同构成工具侧操作会话数据的两种途径。从设计意图推断将 Artifacts 与自定义状态分开管理是为了把面向模型交付的结构化产物与面向业务逻辑的内部状态解耦。客户端读取remoteAgent上的chat.artifacts当 Agent 通过 HTTP 服务暴露时expressHandler参见 agents.md浏览器或 Node 客户端通过genkit/beta/client的remoteAgent消费 Agent。Artifacts 在客户端有两处呈现res.artifacts本回合产生的 Artifactschat.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配置策略行为inline默认Artifact 内容直接包含在委派工具结果中模型可直接看到同时合并进父会话sessionArtifact只合并进父会话委派工具结果只列出 Artifact 名称而非内容需配合artifacts()中间件让编排者按需read_artifact官方推荐的多 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 的使用有以下几点实践提醒Beta APIartifacts()与Artifact均属预览接口前者来自genkit-ai/middleware后者来自genkit/beta导入路径与签名可能随版本变化Agent 整体 API 要求genkit 1.39.0见 SKILL.md 与 agents.md。会话归属Artifacts 存在于会话中不配置store时由客户端remoteAgent持有并随每轮往返配置 会话存储InMemorySessionStore/FileSessionStore/FirestoreSessionStore时则由服务端持久化。currentSession()的调用时机仅在 Agent 回合内部工具执行、自定义 Agent 逻辑可安全调用否则抛异常。同名覆盖语义写入同名 Artifact 是替换而非合并设计会话内文件版本时需要自行把握如需历史版本可改用带版本号或时间戳的命名。只读编排者编排者如需审阅子 Agent 产物务必使用artifactStrategy: sessionartifacts({ 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创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考