Genkit Python Agent ArtifactsBeta实战指南让 Agent 在会话中产出报告、文件与代码【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills导读本篇指南围绕 Genkit Python 的 Agent ArtifactsBeta功能展开讲解如何让 Agent 在一次多轮会话session中产出带名字的交付物——报告、文件、代码片段并通过chat.artifacts与res.artifacts随时读取。你将掌握三种核心用法通过Artifacts()中间件给模型挂上write_artifact/read_artifact工具、在自定义 Agent 中直接调用sess.add_artifacts注入交付物以及从TextPart中正确提取文本内容。本文以 agents-artifacts.md 为主干并结合本仓库中 agents.md、agents-sessions.md、agents-custom.md、agents-state.md 等姊妹文档做纵深解读。Artifacts 是什么会话上的命名交付物在 Genkit Python 的 Agent 模型中一次会话session携带三层数据消息历史messages、自定义状态custom state对应state_schema、以及 Artifacts详见 agents-state.md 开篇。Artifacts 是挂载在会话上的带名字的交付物——一份报告、一个文件、一段代码都可以成为 artifact。它可以从两个位置读取chat.artifacts当前会话累积的所有 artifactsres.artifacts某次发送chat.send返回的响应中携带的 artifacts。其典型语义是Agent 在回答问题的同时把可复用的产出例如生成的poem.txt、report.md、补丁代码以独立命名的实体沉淀下来供后续轮次或宿主程序使用而不是混在纯文本回复里。方式一通过Artifacts()中间件启用工具Genkit 的中间件机制Middleware允许你为 Agent 组合文件系统、工具审批、技能加载、重试等能力参考 agents.md 的 Middleware 一节。其中Artifacts()中间件会为模型提供两个工具write_artifact写入一个 artifactread_artifact读取已存在的 artifact。一个关键语义是写入同名 artifact 会覆盖旧版本。这意味着 artifact 的命名空间是以名字为准的非常适合迭代式生成先写草稿再覆盖为最终版。官方示例来自 agents-artifacts.mdfrom genkit_google_genai import GoogleAI from genkit_middleware import Artifacts, Middleware from genkit import Genkit from genkit.agent import InMemorySessionStore ai Genkit(plugins[GoogleAI(), Middleware()]) agent ai.define_agent( nameworkspaceAgent, modelgoogleai/gemini-flash-latest, systemUse write_artifact for files. Use read_artifact to review them., use[Artifacts()], storeInMemorySessionStore(), ) chat agent.chat() await chat.send(Write poem.txt with a short poem about Python agents.) print([a.name for a in chat.artifacts])拆解这段代码的要点插件组合Genkit(plugins[GoogleAI(), Middleware()])—— 先注册Middleware()插件一次性注册再在use[...]中传入Artifacts()实例参考 agents.md 中RegisterMiddleware()once, then pass instances inuse[...]的约定。系统提示引导system明确指示模型用write_artifact写文件、用read_artifact复查让模型在工具选择时优先使用 artifact 工具。会话存储传入InMemorySessionStore()让服务端拥有历史记录该 Store 重启即失效生产场景可换用 FileSessionStore。读取结果chat.send(...)之后chat.artifacts即为模型本轮以及此前各轮写出的 artifact 列表[a.name for a in chat.artifacts]即可列出所有交付物的名字。重要限制使用 Store 的 Agentstore-backed不能在创建会话时用chat(artifacts...)预置 artifacts。官方文档给出的替代方案是二选一让模型在第一轮对话中主动写出 artifact或者在自定义 Agent 中调用add_artifacts见下文方式二。方式二在自定义 Agent 中直接注入 Artifacts如果不想依赖模型自主调用工具你可以通过自定义 Agentdefine_custom_agent手动管理 artifacts。Genkit 的SessionRunner暴露了get_artifacts/add_artifacts两个方法见 agents-custom.md 的 Fromsess 一节其中add_artifacts接收的是一个列表。官方示例from genkit import Part, TextPart from genkit.agent import Artifact await sess.add_artifacts( [Artifact(namereport.md, parts[Part(TextPart(textbody))])] )关键对象说明Artifact一个命名的交付物核心字段是name名字与parts内容分片列表Partartifact 内容的载体TextPart承载纯文本的分片类型textbody传入实际文本内容。这种方式适合在自定义编排逻辑中例如在handle_turn里完成多步骤处理后把计算结果固化为 artifact 持久化到会话。注意add_artifacts与add_messages一样都要求传入list即使只有一个 artifact 也要包一层列表。方式三无 Store 模式下的 Artifacts 往返传递当你的应用自己管理历史省略store参数时chat的 ids 保持为None需要手动把 messages、state、artifacts 传给下一次chat(...)完成上下文衔接。这在 agents.md 的 Without a store 一节中有明确示范chat agent.chat() await chat.send(My name is Ada. Remember it.) resumed agent.chat( messageschat.messages, statechat.state, artifactschat.artifacts ) await resumed.send(What is my name? One word.)在这种模式下artifacts 与 messages、state 处于同一往返协议上一轮产生的chat.artifacts必须显式回传给新的chat(...)下一轮才能看到。这与 Store-backed 模式服务端持有历史、按snapshot_id恢复形成鲜明对比——后者不需要手动往返这也是 agents-sessions.md 中With a store, the server owns history所强调的职责划分。读取 Artifact 中的文本内容Artifact 的parts使用 Pydantic 的RootModel结构Part的根对象.root才是真正的分片内容。因此读取文本时必须判断根对象是否为TextPart再从.root.text取值。官方给出的辅助函数from genkit import TextPart def artifact_text(artifact) - str: return .join( p.root.text for p in (artifact.parts or []) if isinstance(p.root, TextPart) )要点artifact.parts or []对可能为空的parts做了兜底避免None遍历报错isinstance(p.root, TextPart)仅收集文本分片跳过其他类型的分片p.root.textRootModel 包装下真正的文本位于.root.text这也是该 API 在 Beta 阶段与普通 Pydantic 模型最大的使用差异。与工具审批ToolApproval的联动在启用ToolApproval中间件的场景中参见 agents-human-in-the-loop.mdallowed_tools之外的工具会触发人机确认中断。当同时挂载Filesystem或Artifacts中间件时需要特别注意若write_artifact/read_artifact不在allowed_tools白名单中模型的每次 artifact 写入都会暂停等待审批官方建议只自动放行读取类工具如read_file、read_artifact对写入类工具write_file、edit_file、write_artifact要么显式加入白名单要么有意让它们触发人工确认。这与 agents.md 中 coding-agent 示例的配置哲学一致ToolApproval(allowed_tools[list_files, read_file, use_skill])—— 默认只信任读取与技能加载。组合场景从生成交付物到人工审批再到分叉迭代结合本仓库的 agents 文档体系Artifacts 可以与其他能力无缝组合生成Artifacts()中间件 系统提示引导模型调用write_artifact生成报告/文件审批若write_artifact未列入ToolApproval.allowed_tools写入前会触发INTERRUPTED宿主可用resume(restart[...])或resume(respond[...])决定放行或拒绝迭代/分叉Store-backed 模式下每个快照snapshot_id不可变可以从同一检查点 fork 出多条分支见 agents-branching.md每条分支独立产出不同版本的 artifact 交付物后台化需要长时间产出报告时可用chat.detach(...)把任务交给服务端拿到snapshot_id后随时回来取结果见 agents-background.md。常见坑位小结场景正确做法易错点Store-backed Agent 预置 artifacts让模型第一轮写出或自定义 Agent 里add_artifactschat(artifacts...)不生效自定义 Agent 注入 artifactssess.add_artifacts([...])传list传单个Artifact而非列表读取文本分片判断isinstance(p.root, TextPart)后取p.root.text直接从p.text取值拿不到内容无 Store 模式跨轮传递agent.chat(messages..., state..., artifacts...)显式回传忘记回传导致上下文丢失工具审批与 artifact 写入将write_artifact显式加入allowed_tools或有意中断默认全部工具都需要人工确认结语Artifacts 是 Genkit Python Agent 中会话交付物的第一等公民它让模型的产出不再是易失的纯文本而是可命名、可覆盖、可跨轮引用的实体。无论是借助Artifacts()中间件让模型自主管理文件还是在自定义 Agent 中程序化注入交付物抑或在无 Store 场景下手动往返本文给出的三种模式与代码均可直接复制运行运行前提Python 3.10、uv、GEMINI_API_KEY环境变量参见 SKILL.md 的前置条件。需要更完整的 Agent 能力图谱时可继续阅读 agents.md 及其链接的 sessions、HITL、branching、background、state、custom、HTTP 系列文档。【免费下载链接】skillsAgent Skills for Google products and technologies项目地址: https://gitcode.com/GitHub_Trending/skills29/skills创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考