# 管理智能体版本

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

(sdk-ai-studio-agent-version-flow)=
## 任务流程

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

(sdk-ai-studio-agent-version-prepare)=
## 准备

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。
2. 通过 [发现与选择智能体](发现与选择智能体.md#sdk-ai-studio-agents-s1) 获取目标智能体 ID（`AGENT_ID`）。系统来源的智能体支持读取版本列表；切换默认版本、停用或删除版本需操作当前工作区内有权维护的智能体。

(sdk-ai-studio-agent-version-list)=
## 读取版本清单与默认版本

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

:::::{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"])
	}
}
```

::::

:::::

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

(sdk-ai-studio-agent-version-default)=
## 切换默认版本并回读

从返回的版本清单中选择状态为 `runnable` 的目标版本（`TARGET_AGENT_VERSION`），接续上一步的 `service`、`agent_id` 与 `path` 提交默认版本切换请求，并重新读取版本清单确认 `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)=
## 停用与删除旧版本

清理不再使用的历史版本（`OLD_AGENT_VERSION`）时，先确认该版本为非默认版本，调用 `/disable` 将其状态置为 `disabled` 并回读确认：

:::::{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)
```

::::

:::::

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

:::::{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)=
## 限制和注意事项

- 切换默认版本仅作用于后续新发起的调用；已在执行中的任务继续沿用原版本并按原任务 ID 查询状态。
- 当前默认版本不支持直接停用或删除；下线前需先将默认版本切换到另一个 `runnable` 版本，完成停用后再执行删除。
- 版本清单展示已生成的历史版本状态与诊断；调整智能体配置需进入构建流程生成并校验新版本。

(sdk-ai-studio-agent-version-next)=
## 下一步

- [调用智能体与跟踪任务](调用智能体并跟踪任务.md#sdk-ai-studio-agent-task-send)
- [配置智能体输出语言](配置智能体输出语言.md#sdk-ai-studio-agent-language-save)
