<span id="管理智能体版本"></span>

# 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.

(sdk-ai-studio-agent-version-flow)=
<span id="任务流程"></span>

## Task flow

```text
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
```

(sdk-ai-studio-agent-version-prepare)=
<span id="准备"></span>

## Prerequisites

1. Complete the endpoint, personal access token, and workspace setup in [Use the SDK](../../../quickstart/ai-studio/sdk.md).
2. Obtain the target agent ID (`AGENT_ID`) via [Discover and Select Agents](发现与选择智能体.md#sdk-ai-studio-agents-s1). System-provided agents support listing versions; switching the default version, disabling, or deleting versions requires a maintainable agent in the current workspace.

(sdk-ai-studio-agent-version-list)=
<span id="读取版本清单与默认版本"></span>

## 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.

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
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", []))
```

::::

::::{tab-item} Go
:sync: go

```go
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.

(sdk-ai-studio-agent-version-default)=
<span id="切换默认版本并回读"></span>

## 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`.

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
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)
```

::::

::::{tab-item} Go
:sync: go

```go
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)
```

::::

:::::

(sdk-ai-studio-agent-version-retire)=
<span id="停用与删除旧版本"></span>

## 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:

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
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)
```

::::

::::{tab-item} Go
:sync: go

```go
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:

:::::{tab-set}
:sync-group: sdk-language

::::{tab-item} Python
:sync: python

```python
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)
```

::::

::::{tab-item} Go
:sync: go

```go
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)
```

::::

:::::

(sdk-ai-studio-agent-version-limit)=
<span id="限制和注意事项"></span>

## 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 `runnable` version 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.

(sdk-ai-studio-agent-version-next)=
<span id="下一步"></span>

## Next steps

- [Invoke Agents and Track Tasks](调用智能体并跟踪任务.md#sdk-ai-studio-agent-task-send)
- [Configure Agent Output Language](配置智能体输出语言.md#sdk-ai-studio-agent-language-save)
