# 配置智能体输出语言

为工作区内可编辑的智能体设置固定回答语言，或清空该设置以跟随用户对话语言，并在保存后回读确认元数据更新结果。

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

```text
读取智能体当前配置与 metadata
            │
            ▼
设置或清空 metadata.output_language
            │
            ▼
提交增量更新并回读确认结果
```

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

1. 已完成 [使用 SDK](../../../quickstart/ai-studio/sdk.md) 中的服务地址、个人访问令牌与工作区配置。
2. 通过 [发现与选择智能体](发现与选择智能体.md#sdk-ai-studio-agents-s1)（或调用 `workspace.agents().list()`）获取当前工作区内有权编辑的智能体 ID（`AGENT_ID`）。
3. 确定目标语言代码（`OUTPUT_LANGUAGE`），例如 `zh-CN`、`zh-TW`、`en-US`、`ja-JP`。

```bash
export AGENT_ID='<editable-agent-id>'
export OUTPUT_LANGUAGE='zh-CN'
```

(sdk-ai-studio-agent-language-save)=
## 设置固定输出语言

先读取智能体当前完整对象并复制原有 `metadata`，写入 `output_language` 后调用 `resource_patch`（Go 为 `ResourcePatch`）提交更新，最后回读同一智能体核对已保存的值。

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

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

```python
import os

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"]
language = os.environ["OUTPUT_LANGUAGE"]

current = service.resource_get("agents", "/" + agent_id)
if current.get("id") != agent_id:
    raise RuntimeError("Agent identity does not match")

metadata = dict(current.get("metadata") or {})
metadata["output_language"] = language
service.resource_patch("agents", "/" + agent_id, {"metadata": metadata})

updated = service.resource_get("agents", "/" + agent_id)
actual = (updated.get("metadata") or {}).get("output_language")
if updated.get("id") != agent_id or actual != language:
    raise RuntimeError("Saved output language does not match")
print("agent id:", updated["id"])
print("output language:", actual)
```

::::

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

```go
package main

import (
	"context"
	"fmt"
	"log"
	"os"

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

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")
	language := os.Getenv("OUTPUT_LANGUAGE")
	if language == "" {
		log.Fatal("set OUTPUT_LANGUAGE to a non-empty language code")
	}

	current, err := service.ResourceGet(ctx, "agents", "/"+agentID)
	if err != nil {
		log.Fatal(err)
	}
	agent, ok := current.Value.(map[string]any)
	if !ok || agent["id"] != agentID {
		log.Fatal("agent identity does not match")
	}

	metadata, _ := agent["metadata"].(map[string]any)
	if metadata == nil {
		metadata = map[string]any{}
	}
	metadata["output_language"] = language
	if _, err := service.ResourcePatch(ctx, "agents", "/"+agentID, map[string]any{"metadata": metadata}); err != nil {
		log.Fatal(err)
	}

	result, err := service.ResourceGet(ctx, "agents", "/"+agentID)
	if err != nil {
		log.Fatal(err)
	}
	updated, ok := result.Value.(map[string]any)
	if !ok || updated["id"] != agentID {
		log.Fatal("agent identity does not match")
	}
	saved, _ := updated["metadata"].(map[string]any)
	if saved["output_language"] != language {
		log.Fatal("saved output language does not match")
	}
	fmt.Println("agent id:", agentID)
	fmt.Println("output language:", saved["output_language"])
}
```

::::

:::::

(sdk-ai-studio-agent-language-clear)=
## 恢复跟随对话语言

需要将智能体恢复为跟随每次对话的输入语言时，接续上例重新读取最新 `metadata`，将 `output_language` 设为空字符串 `""` 并提交更新：

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

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

```python
current = service.resource_get("agents", "/" + agent_id)
metadata = dict(current.get("metadata") or {})
metadata["output_language"] = ""
service.resource_patch("agents", "/" + agent_id, {"metadata": metadata})

updated = service.resource_get("agents", "/" + agent_id)
actual = (updated.get("metadata") or {}).get("output_language", "")
if actual != "":
    raise RuntimeError("Output language was not cleared")
print("output language: follow conversation")
```

::::

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

```go
current, err = service.ResourceGet(ctx, "agents", "/"+agentID)
if err != nil {
	log.Fatal(err)
}
agent, _ = current.Value.(map[string]any)
metadata, _ = agent["metadata"].(map[string]any)
if metadata == nil {
	metadata = map[string]any{}
}
metadata["output_language"] = ""
if _, err := service.ResourcePatch(ctx, "agents", "/"+agentID, map[string]any{"metadata": metadata}); err != nil {
	log.Fatal(err)
}

result, err = service.ResourceGet(ctx, "agents", "/"+agentID)
if err != nil {
	log.Fatal(err)
}
updated, _ = result.Value.(map[string]any)
saved, _ = updated["metadata"].(map[string]any)
if saved["output_language"] != "" && saved["output_language"] != nil {
	log.Fatal("output language was not cleared")
}
fmt.Println("output language: follow conversation")
```

::::

:::::

(sdk-ai-studio-agent-language-limit)=
## 限制和注意事项

- 输出语言保存在智能体的 `metadata.output_language` 字段中。`metadata` 按整体键值映射提交，更新前应先读取并保留其中的其他键；多人协作维护同一智能体时，提交前先刷新最新配置。
- 输出语言设置与个人账户界面语言相互独立，保存后在新对话中生效，已有会话中的历史回答保持不变。

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

- [调用智能体与跟踪任务](调用智能体并跟踪任务.md#sdk-ai-studio-agent-task-send)
- [管理智能体版本](查看和切换智能体版本.md#sdk-ai-studio-agent-version-list)
