通过控制台,按 4 步完成智能体创建、环境配置、会话发起与调用。
前置准备
- 已开通阿里云百炼。
- 当前账号在目标工作空间内具备 Managed Agents 操作权限。
下方首次对话不需要上传文件或安装 SDK。文件分析和程序调用示例放在完整控制台流程之后的可选 API 扩展中。
步骤 1:配置智能体
进入百炼控制台 > Managed Agents > 快速开始,填写智能体的基本信息、模型与工具。页面已预填模板值,按需修改即可。
| 字段 | 说明 |
|---|---|
| 名称 | 默认 Agent_v1,可自定义 |
| 模型 | 必选。从下拉列表选择,如 qwen3.7-plus |
| 系统提示词 | 定义智能体的角色与行为。已预填通用模板,可根据场景修改 |
| 工具 | 内置工具默认全选:bash、write、read、edit、glob、grep、web_search、web_fetch、todo_write、mark_artifacts。按需取消勾选 |
| Skill / MCP | 可选。快速开始阶段可跳过,后续在智能体详情页追加 |
填写完成后点击完成并下一步,系统创建并保存智能体,随后进入环境配置。
步骤 2:配置运行环境
环境定义工具调用的执行沙箱,与智能体独立管理。
| 字段 | 说明 |
|---|---|
| 名称 | 默认 Agent_v1_Env,可自定义 |
| 托管类型 | 默认云端托管(阿里云百炼托管的沙箱容器) |
点击完成并下一步,系统创建并保存环境,随后进入会话配置。
步骤 3:确认会话配置
页面展示已创建的智能体与环境摘要,并基于两者自动发起会话。
- 确认智能体卡片中的名称、模型信息。
- 确认环境卡片中的名称、托管类型。
- 如需在沙箱中使用本地文件,点击上传文件挂载;否则直接跳过。步骤 4 的首次对话不需要文件。
点击完成并下一步,系统绑定智能体与环境、创建并保存会话,随后进入调用页面。
步骤 4:开始调用
配置完成。页面提供两个标签页:
- 可调用 API:展示创建事件的 curl 命令,可直接复制到终端执行。
- 预览调试:在页面内直接与智能体对话,实时查看事件与工具调用过程。左上角下拉框可按事件类型筛选(User、Agent、Tool、Tool_output、Error、Model、System)。
打开预览调试,输入 请简要介绍你能做什么。 并发送,查看智能体回答和执行事件。通过程序调用时先建立 SSE 订阅再发送消息,具体顺序见下方可选扩展。
说明看到回答且本轮正常结束(idle 且 stop_reason.type=end_turn)即完成首次对话。requires_action 表示等待工具审批,不是成功;retries_exhausted 表示本轮失败。新建会话的 idle 且停止原因为空,不代表某轮任务完成;terminated 会话不能继续。
调试完成后,点击返回智能体列表进入管理页面。前三步创建的智能体、环境、会话均已保存,可随时在对应菜单中查看和编辑。后续多轮交互可复用同一 Session,idle 不代表删除。
可选:API 扩展
以下保留数据分析配置,作为控制台流程之外的可选路径。选择 curl、Python 或 Java,在同一工作空间内分三个阶段执行第 1–4 节,不混用不同版本示例的 ID。如需调用控制台已创建的资源,直接使用其实际 ID,无需重复创建。
初始化上下文
先按 API 快速开始 获取 API Key、工作空间 ID,设置 DASHSCOPE_API_KEY 和 AGENTSTUDIO_URL。原始 Endpoint 形式为 https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio,将 {workspace_id} 替换为实际工作空间 ID。curl 需要 jq;示例使用 Python SDK 1.27.7 或 Java SDK 2.23.2(Map.of 需要 JDK 9+),安装方法见 API 快速开始。
按以下阶段组合对应语言的片段,不把第 1–4 节一次性放入同一个程序:
- 资源准备:执行共享初始化与第 1–2 节,保存打印的实际
AGENT_ID、ENV_ID,等待环境预热完成。 - 创建会话:重新执行共享导入与客户端初始化,仅运行第 3 节,从环境变量
AGENT_ID、ENV_ID绑定已有资源,保存打印的实际SESSION_ID。 - 文件与调用:先按第 4 节将
sales.csv上传并挂载到这个SESSION_ID;再重新执行共享初始化,仅运行第 4 节的订阅与发送片段,从环境变量读取同一个SESSION_ID。无需重新创建资源。
Python:每阶段仅用对应片段替换下方 pass,每行增加四个空格。官方 Client 上下文退出时关闭 HTTP 客户端;新进程不会保留前一阶段的 agent、env 或 session 对象。Java:将 API 示例 的 ManagedAgentQuickstart.java 与下方 ManagedAgentConsoleQuickstart.java 放在一起,每阶段仅将对应 Java 片段插入 main 的注释位置,只运行控制台扩展类,不运行 API 类的资源创建入口。第 3 阶段复用公共 runTurn:响应头确认后发送,接收 SSE、输出文本、判断停止原因并关闭订阅;保留 120000 毫秒的业务事件等待检查,心跳不重置,同时限制 socket 无数据等待。阻塞行读取不保证精确的 120 秒墙钟截止,完整心跳行上的检查会在到期后停止,详见该 API 示例。
set -euo pipefail
# 在此终端中使用 API 快速开始的环境变量。
# Endpoint 模板:替换 workspace_id,并复用实际返回的 Session ID。
# POST https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/agents
# POST https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/environments
# POST https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/sessions
# GET https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/sessions/sesn_xxx/events/stream
# POST https://{workspace_id}.cn-beijing.maas.aliyuncs.com/api/v1/agentstudio/sessions/sesn_xxx/events
import os
from dashscope.agentstudio import Client
from dashscope.agentstudio.types import user_message
with Client(
api_key=os.environ["DASHSCOPE_API_KEY"],
base_url=os.environ["AGENTSTUDIO_URL"],
workspace="ws_xxxxxxxxxxxx",
region="cn-beijing",
) as client:
# 仅用当前阶段的片段替换 pass,并缩进到此上下文内。
pass
import com.alibaba.dashscope.agentstudio.AgentStudioClient;
import com.alibaba.dashscope.agentstudio.model.Agent;
import com.alibaba.dashscope.agentstudio.model.Configs;
import com.alibaba.dashscope.agentstudio.model.Environment;
import com.alibaba.dashscope.agentstudio.model.Session;
import com.alibaba.dashscope.agentstudio.param.AgentCreateParam;
import com.alibaba.dashscope.agentstudio.param.EnvironmentCreateParam;
import com.alibaba.dashscope.agentstudio.param.SessionCreateParam;
import com.google.gson.Gson;
import java.util.Arrays;
import java.util.Collections;
import java.util.Map;
public class ManagedAgentConsoleQuickstart {
public static void main(String[] args) throws Exception {
AgentStudioClient client = AgentStudioClient.builder()
.apiKey(System.getenv("DASHSCOPE_API_KEY"))
.baseUrl(System.getenv("AGENTSTUDIO_URL"))
.workspace("ws_xxxxxxxxxxxx").region("cn-beijing").build();
// 在此仅插入当前阶段的 Java 片段。
}
}
1. 通过 API 配置智能体
指定名称、模型和工具(详见创建 Agent API)。此数据分析示例使用 data-analyst 和 qwen3.8-max,与控制台模板值不同。
AGENT_ID=$(curl -fsS -X POST "$AGENTSTUDIO_URL/agents" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "data-analyst",
"model": {"id": "qwen3.8-max"},
"system": "你是数据分析专家,使用 pandas 处理 CSV 文件。",
"tools": [
{
"type": "builtin_toolkit",
"default_config": {"enabled": true},
"configs": [
{"name": "bash", "enabled": true},
{"name": "read", "enabled": true},
{"name": "write", "enabled": true}
]
}
]
}' | jq -er '.id')
printf 'Agent: %s\n' "$AGENT_ID"
agent = client.agents.create(
name="data-analyst",
model="qwen3.8-max",
system_prompt="你是数据分析专家,使用 pandas 处理 CSV 文件。",
tools=[
{"type": "builtin_toolkit",
"default_config": {"enabled": True},
"configs": [
{"name": "bash", "enabled": True},
{"name": "read", "enabled": True},
{"name": "write", "enabled": True},
]}
],
)
print(agent.id) # "agent_xxx"
print(agent.version) # 1
Configs.ToolConfig toolkit = new Gson().fromJson(
"{\"type\":\"builtin_toolkit\",\"default_config\":{\"enabled\":true},"
+ "\"configs\":[{\"name\":\"bash\",\"enabled\":true},"
+ "{\"name\":\"read\",\"enabled\":true},{\"name\":\"write\",\"enabled\":true}]}",
Configs.ToolConfig.class);
Agent agent = client.agents().create(AgentCreateParam.builder()
.name("data-analyst")
.model("qwen3.8-max")
.systemPrompt("你是数据分析专家,使用 pandas 处理 CSV 文件。")
.tools(Collections.singletonList(toolkit))
.build());
System.out.println(agent.getId()); // "agent_xxx"
System.out.println(agent.getVersion()); // 1
2. 通过 API 配置运行环境
指定沙箱类型与预装包(详见创建 Environment API)。本例安装 apt: ffmpeg、pip: pandas, numpy, matplotlib,并设置 networking.type=unrestricted。
ENV_ID=$(curl -fsS -X POST "$AGENTSTUDIO_URL/environments" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"name": "data-sandbox",
"description": "数据分析沙箱",
"config": {
"type": "cloud",
"packages": {
"apt": ["ffmpeg"],
"pip": ["pandas", "numpy", "matplotlib"]
},
"networking": {"type": "unrestricted"}
}
}' | jq -er '.id')
printf 'Environment: %s\n' "$ENV_ID"
env = client.environments.create(
name="data-sandbox",
config={
"type": "cloud",
"networking": {"type": "unrestricted"},
"packages": {
"apt": ["ffmpeg"],
"pip": ["pandas", "numpy", "matplotlib"],
},
},
description="数据分析沙箱",
)
print(env.id)
Map<String, Object> config = Map.of(
"type", "cloud",
"networking", Map.of("type", "unrestricted"),
"packages", Map.of(
"apt", Arrays.asList("ffmpeg"),
"pip", Arrays.asList("pandas", "numpy", "matplotlib")));
Environment env = client.environments().create(EnvironmentCreateParam.builder()
.name("data-sandbox")
.description("数据分析沙箱")
.config(config)
.build());
System.out.println(env.getId());
说明API 示例配置了预装包:环境创建后可能需要数分钟或更长的预热时间。预热完成前第 3 节的会话创建会被拒绝,返回 invalid_parameter:The environment is still being prepared. Please wait until it is ready and try again. 等待准备完成后再继续,详见环境预热。
片段不会自动等待。第 1 阶段(第 1–2 节)保存打印的 Agent、Environment ID;预热完成后,仅执行第 2 阶段(第 3 节)创建 Session,保存 Session ID;上传并挂载文件后,再执行第 3 阶段(第 4 节)调用。Session 创建被拒绝时,准备完成后只重试会话创建,不重复创建 Agent 或 Environment。
3. 通过 API 确认会话配置
绑定前两节返回的智能体与环境 ID(详见创建 Session API)。agent_xxx、env_xxx、sesn_xxx 表示实际返回的 ID,不是可互换的固定值。
Python、Java 的第 2 阶段启动前,在启动进程的终端导出保存的 ID,将下方占位值替换为第 1 阶段打印的实际值,并重新执行共享导入与客户端初始化。新终端还需设置相同的 API Key 和 Endpoint。curl 在原终端继续时保留已有 AGENT_ID、ENV_ID,不要用占位值覆盖它们。
# 替换为第 1 阶段打印的实际 ID 后再执行。
export AGENT_ID="agent_xxx"
export ENV_ID="env_xxx"
SESSION_ID=$(curl -fsS -X POST "$AGENTSTUDIO_URL/sessions" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d "{\"agent\": {\"type\": \"agent\", \"id\": \"$AGENT_ID\"}, \"environment_id\": \"$ENV_ID\", \"title\": \"Q3 销售数据分析\"}" | jq -er '.id')
export SESSION_ID
printf 'Session: %s\n' "$SESSION_ID"
session = client.sessions.create(
agent={"type": "agent", "id": os.environ["AGENT_ID"]},
environment_id=os.environ["ENV_ID"],
title="Q3 销售数据分析",
)
print(session.id, session.status)
Session session = client.sessions().create(SessionCreateParam.builder()
.agent(Map.of("type", "agent", "id", System.getenv("AGENT_ID")))
.environmentId(System.getenv("ENV_ID"))
.title("Q3 销售数据分析")
.build());
System.out.println(session.getId() + " " + session.getStatus());
4. 通过 API 开始调用:可选文件分析
Python、Java 第 3 阶段启动前,在启动进程的终端导出第 2 阶段打印的实际 Session ID(不包含后面的状态),然后重新执行共享导入与客户端初始化;保持 API Key 和 Endpoint 不变。curl 在原终端保留第 3 节已导出的变量。
# 将占位值替换为第 2 阶段打印的实际 Session ID。
export SESSION_ID="sesn_xxx"
发送分析任务前,先上传 sales.csv,待审核状态为 available 后挂载到此 Session。挂载路径填写 /sales.csv,服务端自动加上 /mnt/session/uploads 前缀,智能体实际访问 /mnt/session/uploads/sales.csv。可使用控制台上传文件,或按文件上传与挂载操作。上方创建 Session 的代码不会上传或挂载本地文件,添加文件时保持同一 Session ID。
先订阅 SSE 事件流,再发送 Event。SSE 不回放历史,断线恢复见客户端流式接收与恢复。
curl:在终端 A 执行以下订阅。在此新终端中设置相同的 API Key、Endpoint,并复制第 3 节打印的实际 SESSION_ID。保持连接运行,确认 2xx 响应与 Content-Type: text/event-stream 后,再在终端 B 提交任务,不使用固定延时判断连接就绪。
export SESSION_ID="sesn_xxx"
curl -N -i "$AGENTSTUDIO_URL/sessions/$SESSION_ID/events/stream" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Accept: text/event-stream"
终端 B 保持相同的 SESSION_ID。下方 Python、Java 片段在第 3 阶段重新运行的初始化上下文中组合订阅与发送,仅引用环境变量中的 Session ID,不依赖第 2 阶段的 session 对象。Python 1.27.7 在 stream() 返回前打开 HTTP 连接;Java 的 runTurn 检查 HTTP 状态、内容类型并打开输入流后再通过 SDK 发送,仅调用 SDK 的 stream() 不保证连接就绪。
curl -fsS -X POST "$AGENTSTUDIO_URL/sessions/$SESSION_ID/events" \
-H "Authorization: Bearer $DASHSCOPE_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"input": [
{
"role": "user",
"type": "message",
"content": [
{"type": "text", "text": "分析 /mnt/session/uploads/sales.csv 中 Q3 的销售趋势"}
]
}
]
}'
session_id = os.environ["SESSION_ID"]
with client.sessions.events.stream(session_id, timeout=120.0) as stream:
client.sessions.events.send(
session_id,
events=[user_message("分析 /mnt/session/uploads/sales.csv 中 Q3 的销售趋势")],
)
for event in stream:
if event.type == "message":
for block in (event.content or []):
if getattr(block, "type", None) == "text":
print(block.text, end="", flush=True)
elif event.type == "session_status":
state = event.session_status
reason = (event.stop_reason or {}).get("type")
if state == "terminated":
print("会话已终止,不能继续。")
break
if state == "idle" and reason in (
"end_turn", "requires_action", "retries_exhausted"
):
print({
"end_turn": "本轮正常完成。",
"requires_action": "等待工具审批,请处理审批或中断本轮。",
"retries_exhausted": "本轮失败,请查看错误事件。",
}[reason])
break
else:
print(event, flush=True)
ManagedAgentQuickstart.runTurn(client, System.getenv("SESSION_ID"),
"分析 /mnt/session/uploads/sales.csv 中 Q3 的销售趋势");
说明预期收到 Q3 销售分析并以 end_turn 正常结束。POST 成功仅表示任务入队,running 时继续接收,新建会话 idle 且停止原因为空时不退出;按步骤 4 区分正常完成、等待审批、重试耗尽与终止。断线或超时时任务结果为 UNKNOWN,不是成功信号;应查询 Session 状态(Java client.sessions().retrieve(System.getenv("SESSION_ID")))与历史,不自动重发任务。关闭订阅不会终止会话。
资源与会话管理
保存返回的 ID,本轮正常完成后可复用 Session 继续交互。输入文件见文件上传与挂载,输出产物取回见数据分析:取回产物;审批、中断和终止见会话操作。归档 Session 会终止会话并保留历史,删除 Session 会不可逆地删除元数据和历史;Environment 的归档、删除独立管理。仅 running 时计收运行时长费用,idle 不计该运行时长费用,详见计费说明。