Agno Studio 3.0 全生命周期实测：draft 发布阶梯、HITL 暂停流与 Registry/Components HTTP 契约

Agno Studio 3.0 全生命周期实测：draft 发布阶梯、HITL 暂停流与 Registry/Components HTTP 契约

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno

本篇技术指南以 Agno 仓库中cookbook/05_agent_os/22_studio/目录的TEST_LOG.md实况测试记录为核心骨架，逐条还原 Studio 3.0 重写版八个示例的 LIVE 验证过程与验证结果，并结合目录 README.md 与各示例源码，深入剖析「draft 默认创建 → 校验 → 预览 → 发布 → 编辑 → 再发布」的组件生命周期、控制台与 AgentOS 两种 HITL 暂停流、以及 Registry/Components 两套 HTTP 契约。读完本文，你将掌握 StudioTools 与 StudioRunnerTools 的完整调用链、StudioResult 结果封装的错误分支语义、所有权规则与并发写保护（compare-and-set），并能按测试日志中的命令逐例复现全部验证场景。

一、测试背景：Studio 3.0 重写版的验证环境与范围

TEST_LOG.md记录了 2026-08-18 对Studio 3.0 重写版的实况（LIVE）验证，覆盖三大新能力：draft-by-default 生命周期（创建默认落盘为草稿，发布后才对外服务）、StudioResult 结果封装（控制面工具统一返回{ok, status, data, error, warnings}JSON 信封）、以及archive/restore 归档与恢复。

验证环境信息（测试日志原文）：

• 代码工作树提交：9ea0b121a（分支feat/studio-3.0）；
• 加载方式：PYTHONPATH=<worktree>/libs/agno，使用.venvs/demo/bin/python解释器；
• 凭据来源：各 provider 的 API key 来自 shell 环境变量，测试日志未记录任何凭据值；
• 网络约定：服务端示例统一监听端口7777，每个 listener 在运行结束后被停止。

补充说明：registry_learning.py是 2026-08-21 追加的用例，用于验证learning-in-Studio变更，运行于分支feat/learning-in-studio，且因其机器上没有 demo venv，改用PYTHONPATH=<worktree>/libs/agno .venv/bin/python运行。

所有示例均使用同步SqliteDb数据库（位于22_studio/tmp/下）。这一点不是细节：StudioTools 持久化与/components路由要求同步BaseDb，若 AgentOS 收到异步数据库，则会暴露一个被禁用的/components表面；而GET /registry与组件持久化无关，只要求AgentOS(registry=...)。

二、standalone_studio_agent.py：完整生命周期阶梯与直接 Python 组合

2.1 测试方式与预期

该示例验证两条路径：一是由 Claude Agent 以 LLM 驱动方式走完完整生命周期阶梯；二是直接从 Python 调用工具组合工作流。运行命令：

.venvs/demo/bin/python cookbook/05_agent_os/22_studio/standalone_studio_agent.py

2.2 LLM 驱动的生命周期阶梯（PASS）

测试日志记录的操作序列为：

1. Agent 调用list_models与list_tools做发现，精确命中registry 中的模型名与工具名（说明测试提示词要求"只使用 discovery 返回的精确名称"，见 standalone_studio_agent.py 的 instructions）；
2. create_agent写入DRAFT version 1；
3. validate_component校验草稿配置；
4. run_agent(version=1)预览草稿（真实记录的一次 run，不是干跑）；
5. publish_component发布 v1；
6. edit_agent追加DRAFT version 2；
7. list_versions列出两个版本；
8. publish_component再次发布，得到 v2。

验证结果：组件studio-math-tutor-93854a91达到当前版本 2，版本阶段为['published', 'published']；预览 run 在发布前就正确回答了42（即 6×7）；源码侧的断言与此一一对应（standalone_studio_agent.py）：检查current_version == 2且两个 config 阶段均为published，否则抛错。

2.3 直接 Python 组合与 stale-guard 拒绝（PASS）

第二段不再经过模型，直接把StudioTools当作普通类调用（compose_workflow_directly）：

• create_agent(publish=True)立即发布一个 "Draft Checker" 组件；
• create_workflow组合一个复合loop步骤：{"type": "loop", "name": "re-check", "max_iterations": 2, "steps": [...]}，嵌套子步骤；
• validate_component对工作流做 dry-run 校验；
• edit_workflow(expected_version=1)以compare-and-set 守卫追加不可变 draft v2；
• 再次以expected_version=1提交时命中stale-guard：因为最新版本已不是 1。

验证结果：claim-review-8da0941f校验通过；守卫编辑追加出 v2；陈旧守卫返回version_conflict，且retryable: true（可重试标志）。源码断言stale["error"]["code"] == "version_conflict"（L193），印证了"分支判断 error.code 而非 message 文本"的契约。

2.4 关键机制：StudioResult 信封与运行工具扁平负载

测试日志反复强调两种返回形状的区别，这是 3.0 最核心的契约变化：

控制面工具（create/validate/publish/edit/archive/list 等）统一返回一个StudioResultJSON 信封：

{ "ok": true, "status": "success", "data": { "...": "..." }, "error": { "code": "", "message": "", "details": {}, "retryable": false }, "warnings": [] }

调用方必须按error.code分支（机器可读、稳定），绝不依赖 message 文本。测试中出现的稳定错误码包括：version_conflict、learning_not_found、tool_not_allowed、component_not_found、ambiguous_reference等。

运行工具是刻意的例外：run_agent/run_team/run_workflow返回的是 runner 的扁平负载{agent_id|team_id|workflow_id, run_id, session_id, status, content}，因为"run 的结果是组件的输出，而非控制面响应"。status取值为COMPLETED、ERROR或PAUSED；暂停时附带requirements，产生媒体产物时附带media计数。解析不到 id 时返回扁平{"error": "<message>"}——注意这里的error是字符串而非对象，因此没有 code。驱动器应在存在ok键时读信封、否则回退读扁平status与error字符串。run_*(version=N)两种形状都支持：预览门禁在信封中拒绝（component_not_found、version_not_found、validation_failed），放行的预览则正常运行并返回扁平负载。

此外，schedules=True时从SchedulerTools挂载的调度工具（list_schedules、get_schedule、get_schedule_runs、trigger_schedule、enable_schedule、disable_schedule、delete_schedule）同样返回调度器的扁平负载；而 Studio 自身的create_schedule/update_schedule属于控制面工具，返回信封。

2.x 扁平 API 的迁移要点（测试日志随附的变更说明）：

• delete_agent/team/workflow→archive_component+restore_component（要求精确 id）；
• get_agent/team/workflow、list_agents/teams/workflows→ 合并为get_component+list_components；
• get_version→get_component(version=N)；
• list_dbs已移除——构造时绑定一个 catalog 数据库，不再有按调用传db_id的机制。

三、studio_tools_agent.py：AgentOS 服务下的 HTTP 发布与所有权

3.1 测试方式与预期

该示例把 Studio Agent 作为 AgentOS 的代码定义 Agent 之一对外服务，然后由--demoHTTP 客户端发起一次带user_id的创建：

# 终端一：启动服务（默认端口 7777） .venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_tools_agent.py # 终端二：运行可重复执行的 HTTP 客户端 .venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_tools_agent.py --demo

StudioTools构造时传入了include_agents=[greeter, reporter]（studio_tools_agent.py），使这两个代码定义 Agent 可作为 Team 成员与 Workflow 步骤参与组合，并自动启用其操作；而 Studio 创建的组件只持久化在数据库中，不会追加进代码定义 Agent 列表。

3.2 验证结果

demo 客户端以user_id="studio-demo-user"POST 到POST /agents/studio-agent/runs，消息要求先list_models/list_tools发现，再create_agent且publish=true立即上线（源码 run_demo 同时校验GET /registry中必须含calculator与gpt-5.5）。

验证结果：run3a330d26状态COMPLETED；组件api-math-guide-8ce75a74v1 已发布；ComponentResponse.user_id报告属主为studio-demo-user——证明RunContext 被框架注入到每次 StudioTools 调用，运行期间创建的组件归该 user 所有。

3.3 所有权规则（identity and ownership）

测试日志与 README 同步确认了 3.0 的所有权语义：

• 在user_id下创建的组件（与 schedule）归该用户所有；
• 组件仅 draft 时，其他 scoped 用户访问得到component_not_found；
• 发布后组件上平台，所有用户可读可运行；
• 编辑、归档、版本写入始终归 owner 作用域（其他用户得到not_owner）；
• schedule 发布后永不共享；
• 无 run context 的直接 Python 调用/测试写入无主、共享的行。

四、HITL 暂停流：控制台与 AgentOS 两种形态

两个 HITL 示例刻意只给 Studio Agent 一个组件名，要求它依次完成三步：① 用结构化多选工具提问（ask_user）；② 请求自由文本指令（get_user_input）；③ 在确切的create_agent调用上暂停等待确认。暂停/恢复机制（RunRequirement、continue_run、/continue路由）由cookbook/05_agent_os/22_studio/../05_human_in_the_loop/目录讲解，本目录只演示其在 Studio 组合中的应用。

两者的关键配置一致：requires_confirmation_tools=["create_agent"]。注意该参数默认只暂停删除类操作（archive_component、delete_version、delete_schedule），传入自定义列表会整体替换默认值——此处把创建本身纳入审批，归档反而不再暂停；传[]则完全关闭确认。

4.1 studio_hitl_agent.py：控制台 LIVE（--auto）

运行方式：

.venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_hitl_agent.py .venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_hitl_agent.py --auto

--auto使用测试日志所用的确定性答案。流程（源码 run_console_demo）：studio_agent.run(..., user_id="console-hitl-user")返回暂停的 run，循环读取run.active_requirements，对每个 requirement 按needs_user_feedback/needs_user_input/needs_confirmation分别调用provide_user_feedback、provide_user_input、confirm()/reject()，再Agent.continue_run(run_id=..., requirements=run.requirements, user_id=...)继续，直至非暂停。

验证结果：暂停序列['user_feedback', 'user_input', 'confirmation']；最终 runCOMPLETED；组件console-research-buddy-b1d193fb以draft 创建（stages['draft']、无 current version），属主console-hitl-user。测试确认即使 create 被确认批准，写入的仍是 DRAFT，直到publish_component提升 v1 才对外服务。

4.2 studio_hitl_agent_os.py：AgentOS REST API 版（LIVE，server +--demo）

# 终端一 .venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_hitl_agent_os.py # 终端二 .venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_hitl_agent_os.py --demo

AgentOS 版把暂停的执行序列化进 run 的tools数组。客户端逐轮读取run["tools"]，为反馈问题填充selected_options、为输入字段填value、设置answered、最后对确认工具设confirmed=true，再将更新后的 tools POST 到POST /agents/{agent_id}/runs/{run_id}/continue（源码 resolve_paused_tools 与 run_demo）。

验证结果：暂停序列同样为['user_feedback', 'user_input', 'confirmation']；rund8363eadCOMPLETED；组件os-research-buddy-6974b5d3以未发布 draft创建，属主agentos-hitl-user。

两种形态共享同一业务事实：确认后的 create 只写草稿，且 draft-only 组件在POST /agents/{id}/runs上返回 404，直到发布。

五、registry_and_components.py：Registry/Components HTTP 契约端到端

5.1 两个表面的职责分工

表面	职责	说明
GET /registry	描述实时、代码定义的资源：tools、models、dbs、schemas、functions、learning machines、可复用组件	只读；支持resource_type、部分name、page、limit过滤
/components	管理持久化的组件元数据与版本化配置	承担完整生命周期写操作

5.2 测试方式与预期

# 终端一：启动 catalog 服务 .venvs/demo/bin/python cookbook/05_agent_os/22_studio/registry_and_components.py # 终端二：运行 live 生命周期客户端 .venvs/demo/bin/python cookbook/05_agent_os/22_studio/registry_and_components.py --demo

5.3 验证结果：完整 3.0 REST 生命周期（PASS）

组件registry-lifecycle-agent-386f6b59按序完成全部步骤（源码 run_demo）：

1. POST /components创建DRAFT v1——响应 201 且current_version为 null（draft 无当前版本，可读可编辑、不可派发）；
2. POST /agents/{id}/runs对 draft-only 组件返回404（无显式version字段时不可运行）；
3. 带守卫的POST /components/{id}/configs（guard: {"latest_version": 1}）追加出v2；
4. 重复相同守卫（最新已变 2）命中409；
5. PATCH /components/{id}/configs/2以stage: "published"发布 v2，GET /components/{id}/configs/current确认当前为 v2/published；
6. PATCH /components/{id}改名（id 不变）；
7. DELETE /components/{id}归档——响应 204，随后 GET 返回 404（id 保留、历史留存、依赖方拒绝）；
8. POST /components/{id}/restore恢复——组件回到归档时的 v2。

Registry 侧报告共 5 个资源（toolcalculator、模型gpt-5.5/claude-sonnet-4-6、db 等）。测试日志总结为：draft 派发 404 → guarded append 出 v2、stale guard 409 → archive 后 restore 回到 v2。

5.4 HTTP 契约要点

• 每个变更型/components请求体都接受可选guard: {latest_version, current_version}：携带则 compare-and-set（冲突 409），缺失则 last-writer-wins；
• 已发布配置不可变；draft 配置可编辑或删除；只有已发布版本能成为 current；
• run 路由接受可选version表单字段以预览精确版本（含 draft），但仅限组件属主或管理员——这正是测试日志中"显式 version 预览会真实调用模型，故 demo 不使用"的原因。

六、runner 半区：direct 调用与 dispatcher 分发

StudioRunnerTools是 Studio 的派发半边：只列出平台数据库中的组件并按 id 运行，没有 create/edit/archive 表面。Runs 以当前用户身份执行、每组件每会话保持一个 session、固定stream=False、中继PAUSED结果及其requirements。派发只解析当前已发布版本——draft-only 组件在发布前一律 not-found。

挂载注意：StudioRunnerTools应替代StudioTools而非并列挂载。两者共享运行工具名（run_agent，启用 teams/workflows 后还有run_team/run_workflow），且工具命名空间是扁平的——先列出的 toolkit 赢得这些名字，后者被跳过并告警。

6.1 studio_runner_direct.py：直接方法调用与 registry 守卫（PASS）

该示例用StudioTools直接创建两个已发布组件（Greeter 无工具、Calculator Agent 引用calculator工具），然后以普通方法调用StudioRunnerTools.list_agents()、run_agent("greeter", ...)（源码 main）。

验证结果：live runCOMPLETED。核心是registry-guard 拒绝：用StudioRunnerTools(db=db)构造（不带 registry）去运行引用 registry 资源的组件，会被拒绝，且错误信息精确点名缺失的工具函数（add...square_root），并说明"reads 与 edits 仍能加载该组件"——因为重建会静默丢掉 calculator，导致降级运行。

6.2 studio_runner_dispatcher.py：runner-only Agent 分发（PASS）

.venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_runner_dispatcher.py

dispatcher Agent 只挂载StudioRunnerTools（studio_runner_dispatcher.py），收到"写一首关于数据库的俳句"请求后自行发现组件列表并派发已发布的haiku-writer。

验证结果：run_agent(agent_id=haiku-writer, ...)COMPLETED并返回俳句；发现列表只暴露派发允许的内容。源码注释提醒：可以"让 dispatcher 两次运行同一组件并比较 session id"以观察每组件每会话保持一个 session 的行为。

七、registry_learning.py：Registry 学习机与组件接线

7.1 学习是 Studio 组件的唯一记忆面

测试日志（2026-08-21 追加）验证learning-in-Studio：部署者决定平台上存在哪些学习能力——LearningMachine按名称声明在 Registry 上（Registry(learning=[...])或registry.add_learning(...)），构建方用list_learning发现，并在create_agent/edit_agent/create_team/edit_team上用learning_name接线（""解除）。存储的配置只携带{"name": ...}引用，绝不携带机器配置，因此组件无法授权部署者未声明的学习；未声明的名字返回learning_not_found。

7.2 测试步骤与验证结果（PASS）

示例在 Registry 上声明了两个机器（源码 registry_learning.py）：

• shared-brain：namespaceshared，模型gpt-5.5，user_memory为 AGENTIC 模式 +entity_memory=True；
• research-brain：namespaceresearch，配置同上。

完整验证序列与结果：

1. list_learning打印两台机器，带每 store 的模式与 namespace——测试确认输出按 namespace 排列（机器级与每 store 级）；
2. create_agent(learning_name="shared-brain", publish=True)创建已发布的profile-coach——存储配置携带{'name': 'shared-brain'}（引用而非机器）；get_component视图显示learning_name: shared-brain；
3. 请求未声明的my-own-brain被拒：错误码learning_not_found；
4. 通过get_agent_by_id("profile-coach", ...)按 AgentOS 的方式重新水合（rehydrate）——agent.learning is shared_brain: True，机器上注入了SqliteDb，模型为机器声明的gpt-5.5；
5. 以用户ash运行时工具列表含update_user_memory加实体工具；无 user 时只剩实体工具；
6. live run 调用update_user_memory(task=User's name is Ash.)并回答 "Got it, Ash."；
7. edit_agent(learning_name="", publish=True)解除——写入的版本不再含learning键。

同日补记（Addendum）：enable_learning=True段落在此次 live 通过后追加，并在无需 provider key的复跑中验证（该段无需 provider）：note-taker存储learning: True，经get_agent_by_id重新水合后initialize_agent产生默认机器（user_profile+user_memory，模型gpt-5.5）；其余输出与 live 通过时一致。

7.3 学习配置的优先级与语义

• 零配置路径：未声明机器时enable_learning=True让配置携带learning: True，框架在 init 时构建默认机器（组件自身 db 与模型上的 user profile + user memory）；
• 已接线的组件：再加enable_learning=True会保留原机器并在warnings中说明；同一次调用里learning_name=""会先解除引用，因此两者同传会切到默认机器；enable_learning=False无论何种形态都关闭学习；同时给出时，非空learning_name优先；
• 共享实例语义：registry 机器是一个共享实例——框架只在机器没有 db/model 时才注入组件的 db 和 model，因此第一个运行的组件会永久绑定它们（对所有共享者生效）。若应由部署者而非第一个组件决定，请在机器上显式声明db与model；create_*/edit_*在接线机器未声明 db/model 或与组件 db 不同时，会在成功信封的warnings中提示；
• namespace 是字面字符串，没有按组件模板化；
• 两个同名机器在接线时被拒：ambiguous_reference；
• 代码定义 Agent/Team 上的命名机器会像 knowledge 一样折叠进 Registry，存储引用可解析、list_learning可见，GET /registry以type: learning列出；
• 旧字段迁移：memory_manager_id/enable_agentic_memory组合已从 Studio 表单移除；向携带它们的组件接learning_name会清除两者，但get_component仍显示残留的enable_agentic_memory，真实状态保持可见；
• 升级注意事项（3.0.0a3）：learned_knowledge（由 bool 或绑定 knowledge 启用）现在跟随机器 namespace，与entity_memory一致。2.8.4 至 3.0.0a2 期间在LearningMachine(namespace="team_west", knowledge=kb)下保存的学习内容落在global下；召回按精确 namespace 过滤，这些行需要把 namespace 更新为team_west（或让机器留在默认 namespace）才会被返回。

八、调色板策略（Palette Policy）与运行复现指引

8.1 可构建与可解析的边界

构建调色板是强制而非提示的：

• Registry 上声明的工具可构建（buildable）；
• 经 AgentOS fold 到达的（每个注册 agent 自身的 wiring）工具，对重建可解析但不可构建，除非以allowed_tools=[...]放行；
• denied_tools永远优先；
• 组合一个自身携带StudioTools的组件同样被拒；
• list_tools每行报告buildable与source（declared或folded）；接线不可构建的名字返回tool_not_allowed（与tool_not_found区分）。

8.2 汇总复现命令

以下命令均来自 README 与测试日志，均在仓库根目录下、使用.venvs/demo/bin/python执行（先完成./scripts/demo_setup.sh并导出OPENAI_API_KEY/ANTHROPIC_API_KEY）：

# 完整生命周期阶梯 + 直接 Python 组合 .venvs/demo/bin/python cookbook/05_agent_os/22_studio/standalone_studio_agent.py # AgentOS Studio Agent（服务 + HTTP 客户端各一终端；PORT / AGENT_OS_BASE_URL 可改） .venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_tools_agent.py .venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_tools_agent.py --demo # 控制台 HITL（--auto 使用测试日志的确定性答案） .venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_hitl_agent.py --auto # AgentOS HITL（服务 + 客户端） .venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_hitl_agent_os.py .venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_hitl_agent_os.py --demo # Registry/Components HTTP 生命周期（服务 + 客户端） .venvs/demo/bin/python cookbook/05_agent_os/22_studio/registry_and_components.py .venvs/demo/bin/python cookbook/05_agent_os/22_studio/registry_and_components.py --demo # runner 派发与直接调用 .venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_runner_dispatcher.py .venvs/demo/bin/python cookbook/05_agent_os/22_studio/studio_runner_direct.py # 学习机接线（构建与重新水合无需 key；最终 run 需要 OPENAI_API_KEY） .venvs/demo/bin/python cookbook/05_agent_os/22_studio/registry_learning.py

九、结语：测试日志背后的三条主线

复盘TEST_LOG.md的八个 LIVE 用例，可以提炼出 Studio 3.0 重写的三条主线：

1. draft 默认生命周期是安全阀：创建默认写草稿、预览用run_agent(version=N)、发布用publish_component、归档/恢复用archive_component/restore_component——草稿不可派发（run 路由 404），从机制上杜绝了"未验证配置直接上线"；
2. 信封与扁平负载的二分法：控制面统一返回StudioResult信封、按稳定error.code分支，运行面返回扁平负载，调度工具因同因返回扁平负载——理解这一二分是正确驱动 3.0 的前提；
3. 平台级治理内建于工具层：RunContext 注入实现按用户所有权、guard实现并发写保护、registry 守卫杜绝静默降级重建、palette policy 区分可解析与可构建、学习只能接线部署者声明的机器——这些约束把"组件平台"的合规问题前置到了每次工具调用。

如需继续深入，可对照阅读 AgentOS 的 HITL 基础（cookbook/05_agent_os/05_human_in_the_loop/）以及各示例源码注释中给出的扩展实验（如set_current_version回滚、registry=registry后守卫消除、两次派发比较 session id）。

【免费下载链接】agnoBuild, run, and manage agent platforms.项目地址: https://gitcode.com/GitHub_Trending/ag/agno