Genkit Dart Agent Artifacts 实战指南会话级交付物的生产、流转与消费【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills导读在 Genkit Dart 的 Agent 体系中**Artifact产物**是 Agent 在一次会话期间产生的具名、带内容的交付物——例如生成的代码文件、报告、诗歌等它们存活于会话状态中随对话流转并流式同步到客户端。本文基于 skills/cloud/genkit-dart 技能库中的 agents-artifacts.md 参考文档系统讲解如何为模型提供write_artifact/read_artifact工具、Artifact 的底层流动机制与去重规则、服务端与客户端的读写 API以及多智能体编排下的产物合并策略。读完本文你将能够为 Dart / Flutter 中的 Genkit Agent 完整实现会话级产物能力并清楚区分它与filesystem()磁盘工作区的适用边界。阅读前置Artifact 是 Agent 会话状态的一部分建议先阅读 agents.md 了解 Agent 基础涉及Schema()等类型安全机制时可参考 schemantic.md。一、Artifact 是什么会话级交付物的定位按 agents-artifacts.md 的定义Artifacts是 Agent 在一次会话期间产生的具名、内容承载的交付物——文件、报告、代码等都属于此类。它们有两个关键特性存活于会话状态中Artifact 随会话状态SessionState一起被保存、流转并流式同步到客户端。从 agents-sessions.md 可以看到SessionState由messages、custom自定义状态和artifacts三部分组成Artifact 正是其中的第一等公民。按名称去重同一个会话中写入相同name的 Artifact 会被替换见下文流动机制因此一个 Artifact 名称在会话中唯一。在服务端Artifact 通过响应对象暴露res.artifactsListArtifact在客户端通过chat.artifacts追踪整个会话累积的所有 Artifact。API 分布如下Artifact类型与ai.currentSession()/session.addArtifacts()/session.getArtifacts()来自package:genkit/genkit.dart服务端浏览器 / HTTP 客户端能力来自package:genkit/client.dartremoteAgent。1.1 与 Agent 会话模型的关系从 agents.md 可知Agent 是在 prompt tools 之上构建的持久化多轮对话原语相比裸的ai.generate循环增加了Sessions以不可变快照snapshot形式记录的多轮历史State类型化的会话状态消息 自定义数据 产物Interrupts人在回路中的暂停/恢复Branching从任意快照分叉对话Detaching后台运行轮次并轮询结果。Artifact 正是 State 中产物维度的核心承载也是这些能力组合下最常用的数据形态之一。二、会话级 Artifact 与磁盘文件的取舍agents-artifacts.md 明确指出了两种互补的工作模式务必在动手前先做区分维度会话级 Artifactfilesystem()中间件数据位置会话状态内随对话流转、流式推送到客户端磁盘上的真实文件沙箱工作区生存周期会话生命周期内持久化落盘用途会话范围的交付物代码、报告、诗歌等持久的磁盘工作读写文件、搜索替换工具自定义write_artifact/read_artifact内置list_files/read_file/write_file/search_and_replacefilesystem()中间件来自package:genkit_middleware/filesystem.dart用法为filesystem(rootDirectory: ...)由FilesystemPlugin()提供运行时支撑。它会为模型注入一组根目录受限的文件工具——list_files、read_file、write_file、search_and_replace参见 genkit_middleware.md。两套能力是互补的会话级 Artifact适合对话范围内的交付物随聊天流式到达客户端例如 Flutter UI 实时渲染filesystem()适合需要持久落盘、跨会话保留的工作区操作。重要限制Dart 目前尚无artifacts()中间件SKILL.md 与 agents-artifacts.md 均明确说明。因此不能像其他语言一样一行挂载中间件而需要直接在会话 Artifact APIai.currentSession().addArtifacts()/getArtifacts()之上自行定义write_artifact/read_artifact工具。三、为模型提供 Artifact 工具完整实现本节给出 agents-artifacts.md 中的完整可运行示例并补充必要的实现细节说明。3.1 定义输入 Schemaschemantic由于工具入参需要类型安全的 JSON Schema必须使用schemantic库声明抽象 Schema 类$前缀 Schema()注解再通过代码生成得到带$schema的实体类。相关依赖安装与生成命令可参考 schemantic.mddart pub add schemantic dart pub add dev:schemantic_builder dart pub add dev:build_runner # 生成 .g.dart注意缺少 schemantic_builder 时会成功但输出 0 个文件 dart run build_runner buildimport package:genkit/genkit.dart; import package:schemantic/schemantic.dart; import genkit.dart; part workspace_agent.g.dart; Schema() abstract class $WriteArtifactInput { Field(description: The name (e.g. filename) of the artifact.) String get name; Field(description: The full content of the artifact.) String get content; } Schema() abstract class $ReadArtifactInput { Field(description: The name of the artifact to read.) String get name; }Field(description: ...)中的描述会被模型看到用于引导模型正确传参——例如write_artifact要求把文件名放进name、把完整内容放进content这一约定必须在工具描述里反复强调。3.2 定义write_artifact与read_artifact工具核心逻辑围绕ai.currentSession()展开写入用session.addArtifacts(...)读取用session.getArtifacts()final writeArtifact ai.defineTool( name: write_artifact, description: Create or overwrite a named artifact (e.g. a file). Pass the filename as name and the full content as content., inputSchema: WriteArtifactInput.$schema, outputSchema: SchemanticType.string(), fn: (input, _) async { final session ai.currentSession()!; session.addArtifacts([ Artifact(name: input.name, parts: [TextPart(text: input.content)]), ]); return Wrote artifact ${input.name}.; }, ); final readArtifact ai.defineTool( name: read_artifact, description: Read the content of a previously created artifact by name., inputSchema: ReadArtifactInput.$schema, outputSchema: SchemanticType.string(), fn: (input, _) async { final session ai.currentSession()!; final match session.getArtifacts().where((a) a.name input.name); if (match.isEmpty) return Artifact ${input.name} not found.; return match.first.parts.map((p) p.text ?? ).join(); }, );实现要点写工具session.addArtifacts([Artifact(name: ..., parts: [TextPart(text: ...)])])——Artifact 的内容放在parts中此处使用文本部件TextPart读工具按name在session.getArtifacts()中过滤未命中时返回明确的not found提示模型会据此决定是否重新生成命中时把parts中的文本拼回完整内容输出 Schema两个工具都返回SchemanticType.string()即纯字符串的工具结果便于模型理解。3.3 组装 Agentfinal 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., tools: [writeArtifact, readArtifact], use: [retry()], store: InMemorySessionStore(), );此处值得注意的点结合 agents.md 的defineAgent选项说明system提示词再次强化了工具使用约定是提升工具调用准确率的关键use: [retry()]挂载了核心包自带的retry()中间件用于模型瞬时错误的自动重试RetryPlugin需注册在Genkit实例上store: InMemorySessionStore()让服务端持有会话Artifact 随快照持久化若不设store则会话状态由客户端全权管理、每次轮次自动往返二者都支持 Artifact见 agents-sessions.md。四、Artifacts 的流动机制事件、流式块与按名称去重agents-artifacts.md 对底层机制做了精炼说明向会话添加 Artifact 会发出一个事件Agent 运行时将其转发给客户端表现为流中的artifactstream chunkArtifact按名称去重deduplicated by name——再次写入同名 Artifact 会直接替换旧值不会累积。这意味着客户端可以在轮次尚未结束时就实时收到产物例如边生成边渲染文件内容而最终响应中的res.artifacts是本次轮次产出的完整集合。服务端运行一次会话即可验证final chat workspaceAgent.chat(); final res await chat.send(text: Write poem.txt with a poem about Genkit); print(res.artifacts); // ListArtifact由于按名称去重若同一轮内模型先写了poem.txt再重写poem.txt最终res.artifacts中只有一份后者覆盖前者。这也解释了write_artifact描述中 Create oroverwrite 的语义来源。五、Artifact 的类型形状name partsArtifact 的内容承载在parts部件列表中name与metadata在类型上可选但实践上必须始终设置name去重与读取都依赖它// An artifacts content lives in parts (text parts). name and metadata // are optional on the type but you should always set name. final artifact Artifact( name: poem.txt, parts: [TextPart(text: Roses are red…)], );parts的设计为未来扩展非文本部件如图片、二进制块预留了空间当前文档中使用的TextPart通过text字段携带内容客户端可通过p.text读取。六、程序化访问在工具与自定义 Agent 内部读写 Artifact在工具函数或自定义 Agent 内部通过活动会话active session访问 Artifact。注意ai.currentSession()在没有活动会话时返回null因此只能在 Agent 轮次内调用即工具执行期间否则需要判空处理final session ai.currentSession()!; // Read all artifacts: final all session.getArtifacts(); // ListArtifact final found all.where((a) a.name poem.txt).firstOrNull; // Create / replace artifacts: session.addArtifacts([ Artifact(name: notes.md, parts: [TextPart(text: # Notes)]), ]);这两组 APIgetArtifacts()/addArtifacts()正是第三节中read_artifact/write_artifact两个工具的底层实现也是自定义 Agent如defineCustomAgent需要直接面对的原语。结合 agents-sessions.md 可以看到Artifact 随快照一起被SessionStore持久化内存 / 文件 / Firestore 三种实现因此换轮次后依然可读。七、客户端读取 Artifact流式与累积两种形态浏览器 / Dart 客户端含 Flutter通过package:genkit/client.dart的remoteAgent消费 Agent。Artifact 在客户端有三个暴露点chat.artifacts整个会话追踪到的全部 Artifact跨轮次累积res.artifacts本次轮次产出的 Artifactchunk.artifact流式块中实时到达的单条 Artifact。import package:genkit/client.dart; final agent remoteAgent(url: /api/workspaceAgent); final chat agent.chat(); final turn chat.sendStream(text: Create index.html and styles.css); await for (final chunk in turn.stream) { final artifact chunk.artifact; if (artifact ! null) { // artifact.name, artifact.parts — render/store it live. } } final res await turn.response; print(res.artifacts); // artifacts produced this turn print(chat.artifacts); // all artifacts tracked for the session在 Flutter 场景中参见 agents.md 的 Flutter 小节这一能力与流式文本一样可接入setState实时渲染Artifact、中断interrupts、自定义状态custom state在 Flutter 端与服务端行为完全一致。服务端可通过 agents-deployment.md 中介绍的genkit_shelf将workspaceAgent.action暴露为/api/workspaceAgent之类的 HTTP 端点。八、多智能体场景子 Agent 产物如何汇入父会话在 agents-multi-agent.md 描述的多智能体编排中agents()委派中间件支持把子 Agent 的 Artifact 合并进父会话由artifactStrategy选项控制策略行为inline默认产物内容直接包含在委派工具结果中模型可直接看到并且合并进父会话session仅合并进父会话工具结果只列出产物名称而非内容合并产物以调用 id 命名空间化键形如invocationId/nameinline适合父 Agent 需要阅读子 Agent 产物内容以便综合决策的场景内容可见但会占用上下文session适合只希望产物沉淀到会话、父 Agent 按需读取的场景。委派中间件的其他选项agents、toolPrefix、maxDelegations、historyLength详见 agents-multi-agent.md。九、最佳实践与注意事项综合 agents-artifacts.md 与整个 skills/cloud/genkit-dart 技能库落地 Artifact 能力时建议遵循以下实践先判场景再选机制会话内交付物代码、报告、诗歌等用 Artifact需要落盘、跨会话持久的工作区操作用filesystem(rootDirectory: ...)二者互补而非互斥。在工具描述与 system prompt 中双重强化参数约定write_artifact要求name传文件名、content传完整内容模型越明确越不容易误用。ai.currentSession()只能在 Agent 轮次内调用没有活动会话时返回null在工具外部使用必须判空。始终设置name虽然类型上可选但去重、读取、客户端追踪全部依赖它。利用按名称去重实现覆盖写模型对同一文件迭代修改时重复调用write_artifact同名即可无需先删除。配合会话持久化需要服务端持有 Artifact 历史时配置storeInMemorySessionStore/FileSessionStore/FirestoreSessionStore多智能体需要产物汇总时配置artifactStrategy。开发期用 Genkit CLI 校验通过genkit start -- dart run main.dart启动并捕获 trace再用genkit trace:get traceId查看工具调用与模型 I/O可直观验证write_artifact/read_artifact是否被正确调用参见 SKILL.md 的 Genkit CLI 章节。十、小结Artifact 是 Genkit Dart Agent 会话状态中的一等公民它以命名 内容的形式承载 Agent 交付物按名称去重随事件流式同步到客户端并可通过服务端会话 API 程序化读写。由于 Dart 暂无artifacts()中间件标准做法是在ai.currentSession().addArtifacts()/getArtifacts()之上自定义write_artifact/read_artifact工具——本文给出的完整示例可直接复制运行。结合filesystem()处理持久磁盘工作、agents()中间件的artifactStrategy处理多智能体产物汇总即可在 Dart / Flutter 应用中构建完整的生产 → 流转 → 消费产物链路。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
Genkit Dart Agent Artifacts 实战指南会话级交付物的生产、流转与消费【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills导读在 Genkit Dart 的 Agent 体系中**Artifact产物**是 Agent 在一次会话期间产生的具名、带内容的交付物——例如生成的代码文件、报告、诗歌等它们存活于会话状态中随对话流转并流式同步到客户端。本文基于 skills/cloud/genkit-dart 技能库中的 agents-artifacts.md 参考文档系统讲解如何为模型提供write_artifact/read_artifact工具、Artifact 的底层流动机制与去重规则、服务端与客户端的读写 API以及多智能体编排下的产物合并策略。读完本文你将能够为 Dart / Flutter 中的 Genkit Agent 完整实现会话级产物能力并清楚区分它与filesystem()磁盘工作区的适用边界。阅读前置Artifact 是 Agent 会话状态的一部分建议先阅读 agents.md 了解 Agent 基础涉及Schema()等类型安全机制时可参考 schemantic.md。一、Artifact 是什么会话级交付物的定位按 agents-artifacts.md 的定义Artifacts是 Agent 在一次会话期间产生的具名、内容承载的交付物——文件、报告、代码等都属于此类。它们有两个关键特性存活于会话状态中Artifact 随会话状态SessionState一起被保存、流转并流式同步到客户端。从 agents-sessions.md 可以看到SessionState由messages、custom自定义状态和artifacts三部分组成Artifact 正是其中的第一等公民。按名称去重同一个会话中写入相同name的 Artifact 会被替换见下文流动机制因此一个 Artifact 名称在会话中唯一。在服务端Artifact 通过响应对象暴露res.artifactsListArtifact在客户端通过chat.artifacts追踪整个会话累积的所有 Artifact。API 分布如下Artifact类型与ai.currentSession()/session.addArtifacts()/session.getArtifacts()来自package:genkit/genkit.dart服务端浏览器 / HTTP 客户端能力来自package:genkit/client.dartremoteAgent。1.1 与 Agent 会话模型的关系从 agents.md 可知Agent 是在 prompt tools 之上构建的持久化多轮对话原语相比裸的ai.generate循环增加了Sessions以不可变快照snapshot形式记录的多轮历史State类型化的会话状态消息 自定义数据 产物Interrupts人在回路中的暂停/恢复Branching从任意快照分叉对话Detaching后台运行轮次并轮询结果。Artifact 正是 State 中产物维度的核心承载也是这些能力组合下最常用的数据形态之一。二、会话级 Artifact 与磁盘文件的取舍agents-artifacts.md 明确指出了两种互补的工作模式务必在动手前先做区分维度会话级 Artifactfilesystem()中间件数据位置会话状态内随对话流转、流式推送到客户端磁盘上的真实文件沙箱工作区生存周期会话生命周期内持久化落盘用途会话范围的交付物代码、报告、诗歌等持久的磁盘工作读写文件、搜索替换工具自定义write_artifact/read_artifact内置list_files/read_file/write_file/search_and_replacefilesystem()中间件来自package:genkit_middleware/filesystem.dart用法为filesystem(rootDirectory: ...)由FilesystemPlugin()提供运行时支撑。它会为模型注入一组根目录受限的文件工具——list_files、read_file、write_file、search_and_replace参见 genkit_middleware.md。两套能力是互补的会话级 Artifact适合对话范围内的交付物随聊天流式到达客户端例如 Flutter UI 实时渲染filesystem()适合需要持久落盘、跨会话保留的工作区操作。重要限制Dart 目前尚无artifacts()中间件SKILL.md 与 agents-artifacts.md 均明确说明。因此不能像其他语言一样一行挂载中间件而需要直接在会话 Artifact APIai.currentSession().addArtifacts()/getArtifacts()之上自行定义write_artifact/read_artifact工具。三、为模型提供 Artifact 工具完整实现本节给出 agents-artifacts.md 中的完整可运行示例并补充必要的实现细节说明。3.1 定义输入 Schemaschemantic由于工具入参需要类型安全的 JSON Schema必须使用schemantic库声明抽象 Schema 类$前缀 Schema()注解再通过代码生成得到带$schema的实体类。相关依赖安装与生成命令可参考 schemantic.mddart pub add schemantic dart pub add dev:schemantic_builder dart pub add dev:build_runner # 生成 .g.dart注意缺少 schemantic_builder 时会成功但输出 0 个文件 dart run build_runner buildimport package:genkit/genkit.dart; import package:schemantic/schemantic.dart; import genkit.dart; part workspace_agent.g.dart; Schema() abstract class $WriteArtifactInput { Field(description: The name (e.g. filename) of the artifact.) String get name; Field(description: The full content of the artifact.) String get content; } Schema() abstract class $ReadArtifactInput { Field(description: The name of the artifact to read.) String get name; }Field(description: ...)中的描述会被模型看到用于引导模型正确传参——例如write_artifact要求把文件名放进name、把完整内容放进content这一约定必须在工具描述里反复强调。3.2 定义write_artifact与read_artifact工具核心逻辑围绕ai.currentSession()展开写入用session.addArtifacts(...)读取用session.getArtifacts()final writeArtifact ai.defineTool( name: write_artifact, description: Create or overwrite a named artifact (e.g. a file). Pass the filename as name and the full content as content., inputSchema: WriteArtifactInput.$schema, outputSchema: SchemanticType.string(), fn: (input, _) async { final session ai.currentSession()!; session.addArtifacts([ Artifact(name: input.name, parts: [TextPart(text: input.content)]), ]); return Wrote artifact ${input.name}.; }, ); final readArtifact ai.defineTool( name: read_artifact, description: Read the content of a previously created artifact by name., inputSchema: ReadArtifactInput.$schema, outputSchema: SchemanticType.string(), fn: (input, _) async { final session ai.currentSession()!; final match session.getArtifacts().where((a) a.name input.name); if (match.isEmpty) return Artifact ${input.name} not found.; return match.first.parts.map((p) p.text ?? ).join(); }, );实现要点写工具session.addArtifacts([Artifact(name: ..., parts: [TextPart(text: ...)])])——Artifact 的内容放在parts中此处使用文本部件TextPart读工具按name在session.getArtifacts()中过滤未命中时返回明确的not found提示模型会据此决定是否重新生成命中时把parts中的文本拼回完整内容输出 Schema两个工具都返回SchemanticType.string()即纯字符串的工具结果便于模型理解。3.3 组装 Agentfinal 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., tools: [writeArtifact, readArtifact], use: [retry()], store: InMemorySessionStore(), );此处值得注意的点结合 agents.md 的defineAgent选项说明system提示词再次强化了工具使用约定是提升工具调用准确率的关键use: [retry()]挂载了核心包自带的retry()中间件用于模型瞬时错误的自动重试RetryPlugin需注册在Genkit实例上store: InMemorySessionStore()让服务端持有会话Artifact 随快照持久化若不设store则会话状态由客户端全权管理、每次轮次自动往返二者都支持 Artifact见 agents-sessions.md。四、Artifacts 的流动机制事件、流式块与按名称去重agents-artifacts.md 对底层机制做了精炼说明向会话添加 Artifact 会发出一个事件Agent 运行时将其转发给客户端表现为流中的artifactstream chunkArtifact按名称去重deduplicated by name——再次写入同名 Artifact 会直接替换旧值不会累积。这意味着客户端可以在轮次尚未结束时就实时收到产物例如边生成边渲染文件内容而最终响应中的res.artifacts是本次轮次产出的完整集合。服务端运行一次会话即可验证final chat workspaceAgent.chat(); final res await chat.send(text: Write poem.txt with a poem about Genkit); print(res.artifacts); // ListArtifact由于按名称去重若同一轮内模型先写了poem.txt再重写poem.txt最终res.artifacts中只有一份后者覆盖前者。这也解释了write_artifact描述中 Create oroverwrite 的语义来源。五、Artifact 的类型形状name partsArtifact 的内容承载在parts部件列表中name与metadata在类型上可选但实践上必须始终设置name去重与读取都依赖它// An artifacts content lives in parts (text parts). name and metadata // are optional on the type but you should always set name. final artifact Artifact( name: poem.txt, parts: [TextPart(text: Roses are red…)], );parts的设计为未来扩展非文本部件如图片、二进制块预留了空间当前文档中使用的TextPart通过text字段携带内容客户端可通过p.text读取。六、程序化访问在工具与自定义 Agent 内部读写 Artifact在工具函数或自定义 Agent 内部通过活动会话active session访问 Artifact。注意ai.currentSession()在没有活动会话时返回null因此只能在 Agent 轮次内调用即工具执行期间否则需要判空处理final session ai.currentSession()!; // Read all artifacts: final all session.getArtifacts(); // ListArtifact final found all.where((a) a.name poem.txt).firstOrNull; // Create / replace artifacts: session.addArtifacts([ Artifact(name: notes.md, parts: [TextPart(text: # Notes)]), ]);这两组 APIgetArtifacts()/addArtifacts()正是第三节中read_artifact/write_artifact两个工具的底层实现也是自定义 Agent如defineCustomAgent需要直接面对的原语。结合 agents-sessions.md 可以看到Artifact 随快照一起被SessionStore持久化内存 / 文件 / Firestore 三种实现因此换轮次后依然可读。七、客户端读取 Artifact流式与累积两种形态浏览器 / Dart 客户端含 Flutter通过package:genkit/client.dart的remoteAgent消费 Agent。Artifact 在客户端有三个暴露点chat.artifacts整个会话追踪到的全部 Artifact跨轮次累积res.artifacts本次轮次产出的 Artifactchunk.artifact流式块中实时到达的单条 Artifact。import package:genkit/client.dart; final agent remoteAgent(url: /api/workspaceAgent); final chat agent.chat(); final turn chat.sendStream(text: Create index.html and styles.css); await for (final chunk in turn.stream) { final artifact chunk.artifact; if (artifact ! null) { // artifact.name, artifact.parts — render/store it live. } } final res await turn.response; print(res.artifacts); // artifacts produced this turn print(chat.artifacts); // all artifacts tracked for the session在 Flutter 场景中参见 agents.md 的 Flutter 小节这一能力与流式文本一样可接入setState实时渲染Artifact、中断interrupts、自定义状态custom state在 Flutter 端与服务端行为完全一致。服务端可通过 agents-deployment.md 中介绍的genkit_shelf将workspaceAgent.action暴露为/api/workspaceAgent之类的 HTTP 端点。八、多智能体场景子 Agent 产物如何汇入父会话在 agents-multi-agent.md 描述的多智能体编排中agents()委派中间件支持把子 Agent 的 Artifact 合并进父会话由artifactStrategy选项控制策略行为inline默认产物内容直接包含在委派工具结果中模型可直接看到并且合并进父会话session仅合并进父会话工具结果只列出产物名称而非内容合并产物以调用 id 命名空间化键形如invocationId/nameinline适合父 Agent 需要阅读子 Agent 产物内容以便综合决策的场景内容可见但会占用上下文session适合只希望产物沉淀到会话、父 Agent 按需读取的场景。委派中间件的其他选项agents、toolPrefix、maxDelegations、historyLength详见 agents-multi-agent.md。九、最佳实践与注意事项综合 agents-artifacts.md 与整个 skills/cloud/genkit-dart 技能库落地 Artifact 能力时建议遵循以下实践先判场景再选机制会话内交付物代码、报告、诗歌等用 Artifact需要落盘、跨会话持久的工作区操作用filesystem(rootDirectory: ...)二者互补而非互斥。在工具描述与 system prompt 中双重强化参数约定write_artifact要求name传文件名、content传完整内容模型越明确越不容易误用。ai.currentSession()只能在 Agent 轮次内调用没有活动会话时返回null在工具外部使用必须判空。始终设置name虽然类型上可选但去重、读取、客户端追踪全部依赖它。利用按名称去重实现覆盖写模型对同一文件迭代修改时重复调用write_artifact同名即可无需先删除。配合会话持久化需要服务端持有 Artifact 历史时配置storeInMemorySessionStore/FileSessionStore/FirestoreSessionStore多智能体需要产物汇总时配置artifactStrategy。开发期用 Genkit CLI 校验通过genkit start -- dart run main.dart启动并捕获 trace再用genkit trace:get traceId查看工具调用与模型 I/O可直观验证write_artifact/read_artifact是否被正确调用参见 SKILL.md 的 Genkit CLI 章节。十、小结Artifact 是 Genkit Dart Agent 会话状态中的一等公民它以命名 内容的形式承载 Agent 交付物按名称去重随事件流式同步到客户端并可通过服务端会话 API 程序化读写。由于 Dart 暂无artifacts()中间件标准做法是在ai.currentSession().addArtifacts()/getArtifacts()之上自定义write_artifact/read_artifact工具——本文给出的完整示例可直接复制运行。结合filesystem()处理持久磁盘工作、agents()中间件的artifactStrategy处理多智能体产物汇总即可在 Dart / Flutter 应用中构建完整的生产 → 流转 → 消费产物链路。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考
