Manage Agent Versions¶
Query loaded versions, configuration diagnostics, and the active default version for an agent, switch the default version to a runnable version, and disable or delete retired versions.
Task flow¶
List agent versions and default version
│
▼
Verify runnable status and switch default
│
▼
Read back to confirm the active default
│
▼
Disable and delete retired non-default versions
Prerequisites¶
Complete the endpoint, personal access token, and workspace setup in Use the SDK.
Obtain the target agent ID (
AGENT_ID) via Discover and Select Agents. System-provided agents support listing versions; switching the default version, disabling, or deleting versions requires a maintainable agent in the current workspace.
List versions and the default version¶
Call resource_get (ResourceGet in Go) on /<agent_id>/versions to read lineage.default_version along with each version’s identifier, status (runnable, disabled, and others), and configuration diagnostics.
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"])
}
}
The diagnostics list reports missing configuration fields or invalid linked resources so you can resolve issues before promoting a version.
Switch the default version and read back¶
Select a version with status runnable from the returned list (TARGET_AGENT_VERSION), continue with service, agent_id, and path from the previous step to update the default version, and read back the version list to verify 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)
Disable and delete an old version¶
Before retiring an older version (OLD_AGENT_VERSION), confirm that it is not the active default version, call /disable to set its status to disabled, and read back the list to verify:
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)
Once the version is disabled and no longer needed, delete it and read back the version list to confirm removal:
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)
Limitations and notes¶
Switching the default version applies only to subsequent invocations; tasks already in progress continue under their original version and task ID.
The active default version cannot be disabled or deleted directly. Switch the default version to another
runnableversion first, disable the old version, and then delete it.The version list reflects generated historical versions and their diagnostics; changing agent configurations requires generating and validating a new version through the authoring workflow.