管理智能体版本

查询智能体已加载的版本清单、配置诊断与当前默认版本,将默认版本切换到可运行版本,并停用或删除不再使用的旧版本。

任务流程

查询版本清单与默认版本
        │
        ▼
检查目标版本状态(runnable)并切换默认版本
        │
        ▼
回读确认默认版本已生效
        │
        ▼
停用并删除不再使用的非默认旧版本

准备

  1. 已完成 使用 SDK 中的服务地址、个人访问令牌与工作区配置。

  2. 通过 发现与选择智能体 获取目标智能体 ID(AGENT_ID)。系统来源的智能体支持读取版本列表;切换默认版本、停用或删除版本需操作当前工作区内有权维护的智能体。

读取版本清单与默认版本

调用 resource_get(Go 为 ResourceGet)访问 /<agent_id>/versions,读取 lineage.default_version 及各版本的版本号、状态(如 runnable、disabled)和配置诊断信息。

import os
from urllib.parse import quote

import moi_product_sdk as sdk

client = sdk.new_with_personal_access_token(
    os.environ["PRODUCT_API_BASE_URL"],
    os.environ["PRODUCT_API_KEY"],
)
service = client.workspace(os.environ["WORKSPACE_ID"]).agents()
agent_id = os.environ["AGENT_ID"]
path = "/" + quote(agent_id, safe="") + "/versions"

listing = service.resource_get("agents", path)
print("Default version:", listing["lineage"]["default_version"])
for item in listing.get("items", []):
    print(item["version"], item["status"], item.get("diagnostics", []))
package main

import (
	"context"
	"fmt"
	"log"
	"net/url"
	"os"

	sdk "github.com/matrixorigin/matrixflow/sdk/go-sdk"
)

func mustObject(data *sdk.ProductData, err error) map[string]any {
	if err != nil {
		log.Fatal(err)
	}
	value, ok := data.Value.(map[string]any)
	if !ok {
		log.Fatal("expected an object response")
	}
	return value
}

func main() {
	ctx := context.Background()
	client, err := sdk.NewWithPersonalAccessToken(
		os.Getenv("PRODUCT_API_BASE_URL"),
		os.Getenv("PRODUCT_API_KEY"),
	)
	if err != nil {
		log.Fatal(err)
	}
	defer client.Close()

	workspace, err := client.Workspace(os.Getenv("WORKSPACE_ID"))
	if err != nil {
		log.Fatal(err)
	}
	service := workspace.Agents()
	agentID := os.Getenv("AGENT_ID")
	path := "/" + url.PathEscape(agentID) + "/versions"

	listing := mustObject(service.ResourceGet(ctx, "agents", path))
	lineage, _ := listing["lineage"].(map[string]any)
	fmt.Println("Default version:", lineage["default_version"])
	items, _ := listing["items"].([]any)
	for _, value := range items {
		item, _ := value.(map[string]any)
		fmt.Println(item["version"], item["status"], item["diagnostics"])
	}
}

diagnostics 字段列出当前版本缺失的配置或失效的关联资源,可在切换默认版本前据此排查异常。

切换默认版本并回读

从返回的版本清单中选择状态为 runnable 的目标版本(TARGET_AGENT_VERSION),接续上一步的 service、agent_id 与 path 提交默认版本切换请求,并重新读取版本清单确认 default_version 已更新。

target = os.environ["TARGET_AGENT_VERSION"]
selected = next((item for item in listing["items"] if item["version"] == target), None)
if selected is None or selected["status"] != "runnable":
    raise RuntimeError("Target version must exist in the list and have status 'runnable'")

service.resource_post(
    "agents",
    "/" + quote(agent_id, safe="") + "/versions/" + quote(target, safe="") + "/default",
    {},
)
listing = service.resource_get("agents", path)
if listing["lineage"]["default_version"] != target:
    raise RuntimeError("Default version readback does not match")
print("Updated default version:", target)
target := os.Getenv("TARGET_AGENT_VERSION")
runnable := false
for _, value := range items {
	item, _ := value.(map[string]any)
	if item["version"] == target && item["status"] == "runnable" {
		runnable = true
	}
}
if !runnable {
	log.Fatal("target version must exist in the list and have status 'runnable'")
}

mustObject(service.ResourcePost(
	ctx,
	"agents",
	"/"+url.PathEscape(agentID)+"/versions/"+url.PathEscape(target)+"/default",
	map[string]any{},
))
listing = mustObject(service.ResourceGet(ctx, "agents", path))
lineage, _ = listing["lineage"].(map[string]any)
if lineage["default_version"] != target {
	log.Fatal("default version readback does not match")
}
fmt.Println("Updated default version:", target)

停用与删除旧版本

清理不再使用的历史版本(OLD_AGENT_VERSION)时,先确认该版本为非默认版本,调用 /disable 将其状态置为 disabled 并回读确认:

old_version = os.environ["OLD_AGENT_VERSION"]
latest = service.resource_get("agents", path)
old = next((item for item in latest["items"] if item["version"] == old_version), None)
if old is None or latest["lineage"]["default_version"] == old_version:
    raise RuntimeError("Select an existing non-default version")

if old["status"] != "disabled":
    service.resource_post(
        "agents",
        "/" + quote(agent_id, safe="") + "/versions/" + quote(old_version, safe="") + "/disable",
        {},
    )
latest = service.resource_get("agents", path)
old = next(item for item in latest["items"] if item["version"] == old_version)
if old["status"] != "disabled":
    raise RuntimeError("Old version was not disabled")
print("Disabled version:", old_version)
oldVersion := os.Getenv("OLD_AGENT_VERSION")
latest := mustObject(service.ResourceGet(ctx, "agents", path))
oldLineage, _ := latest["lineage"].(map[string]any)
if oldLineage["default_version"] == oldVersion {
	log.Fatal("select an existing non-default version")
}
var old map[string]any
for _, value := range latest["items"].([]any) {
	item, _ := value.(map[string]any)
	if item["version"] == oldVersion {
		old = item
	}
}
if old == nil {
	log.Fatal("select an existing non-default version")
}
if old["status"] != "disabled" {
	mustObject(service.ResourcePost(
		ctx,
		"agents",
		"/"+url.PathEscape(agentID)+"/versions/"+url.PathEscape(oldVersion)+"/disable",
		map[string]any{},
	))
}
latest = mustObject(service.ResourceGet(ctx, "agents", path))
for _, value := range latest["items"].([]any) {
	item, _ := value.(map[string]any)
	if item["version"] == oldVersion {
		old = item
	}
}
if old["status"] != "disabled" {
	log.Fatal("old version was not disabled")
}
fmt.Println("Disabled version:", oldVersion)

确认旧版本已处于 disabled 状态且无需保留后,调用删除接口并回读清单确认该版本已移除:

service.resource_delete(
    "agents",
    "/" + quote(agent_id, safe="") + "/versions/" + quote(old_version, safe=""),
)
latest = service.resource_get("agents", path)
if any(item["version"] == old_version for item in latest["items"]):
    raise RuntimeError("Deleted version is still listed")
print("Deleted version:", old_version)
mustObject(service.ResourceDelete(
	ctx,
	"agents",
	"/"+url.PathEscape(agentID)+"/versions/"+url.PathEscape(oldVersion),
))
latest = mustObject(service.ResourceGet(ctx, "agents", path))
for _, value := range latest["items"].([]any) {
	item, _ := value.(map[string]any)
	if item["version"] == oldVersion {
		log.Fatal("deleted version is still listed")
	}
}
fmt.Println("Deleted version:", oldVersion)

限制和注意事项

  • 切换默认版本仅作用于后续新发起的调用;已在执行中的任务继续沿用原版本并按原任务 ID 查询状态。

  • 当前默认版本不支持直接停用或删除;下线前需先将默认版本切换到另一个 runnable 版本,完成停用后再执行删除。

  • 版本清单展示已生成的历史版本状态与诊断;调整智能体配置需进入构建流程生成并校验新版本。

下一步

最后更新于