docs(examples): move agentstudio to the 2.0 tiers, add agentic RL quickref

AgentStudio and agentic RL are shared by the 1.x/2.0 generations, so
they do not belong under legacy_1x. agentstudio examples now use the
client.agentstudio entry; reinforcement_learning.py covers client.rl.

Author: zhansheng.lzs

examples/01_atomic_capabilities/fine_tuning/reinforcement_learning.py

@@ -0,0 +1,83 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) Alibaba, Inc. and its affiliates.
+"""dashscope 2.0 agentic RL example: list jobs, and (optionally) the
+full register-functions -> upload-data -> create -> wait lifecycle.
+
+The read-only list/get sections run as-is. The training workflow is
+commented out: it registers real rollout/reward function instances,
+uploads datasets and submits a real training job (which trains and
+bills). Uncomment it once your function classes, data files and
+training config are ready.
+"""
+
+import dashscope
+
+# Authentication: the client reads the API key from the
+# DASHSCOPE_API_KEY environment variable by default; you can also
+# pass it explicitly via dashscope.Client(api_key="sk-xxx").
+
+if __name__ == "__main__":
+    client = dashscope.Client()
+
+    # List RL jobs (paged; RL jobs share the fine-tune wire contract)
+    print("----- list RL jobs -----")
+    page = client.rl.jobs.list(page_no=1, page_size=10)
+    print(f"total: {page.total_count}")
+    for job in page.jobs:
+        print(
+            f"job_id={job.job_id}, status={job.status}, "
+            f"model={job.finetuned_model}",
+        )
+
+    # Get one job by ID (uses the first job of the list above)
+    if page.jobs:
+        print("----- get RL job -----")
+        job = client.rl.jobs.fetch(page.jobs[0].job_id)
+        print(
+            f"job_id={job.job_id}, status={job.status}, "
+            f"finished={job.finished}",
+        )
+
+    # Full lifecycle: register functions -> upload data -> create ->
+    # wait -> delete. Uncomment once you have rollout/reward function
+    # classes, training data files and a training config file.
+    #
+    # print("----- register functions -----")
+    # registered = client.rl.register_functions(
+    #     rollout_classpaths=["my_rl.rollout.MyRollout"],
+    #     reward_classpaths=["my_rl.reward.MyReward"],
+    #     workspace_dir="./",
+    # )
+    # print(f"registered: {registered}")
+    #
+    # print("----- upload data -----")
+    # data = client.rl.upload_data(
+    #     training_files=["train.jsonl"],
+    #     validation_files=["val.jsonl"],
+    # )
+    # print(f"training_file_ids={data.training_file_ids}")
+    #
+    # print("----- create RL job -----")
+    # job = client.rl.jobs.create(
+    #     config_path="rl_config.yaml",
+    #     job_name="my-rl-job",
+    # )
+    # print(f"created job_id={job.job_id}")
+    #
+    # print("----- wait RL job -----")
+    # final = client.rl.jobs.wait(job)
+    # print(f"status={final.status}, succeeded={final.succeeded}")
+    #
+    # print("----- delete RL job -----")
+    # client.rl.jobs.delete(job.job_id)
+
+
+# --- Production springboard (Best Practices & Patterns) -------
+# Minimal runnable atomic call above; to productionize it, see:
+#   Offline mock debugging: 02_advanced_engineering/local_mock_debugging.py
+#   Backoff + breaker DR: 02_advanced_engineering/circuit_breaker_retry.py
+#   This capability is a long-running jobs flow; reuse the
+#   generic patterns above for poll timeouts and retries.
+#   client.rl wraps the async workflow with asyncio.run -- under a
+#   running event loop (Jupyter, FastAPI) use dashscope.AsyncClient.rl.
+# -------------------------------------------------------------

examples/legacy_1x/agentstudio.py examples/03_agent_recipes/agentstudio.pyexamples/legacy_1x/agentstudio.py renamed to examples/03_agent_recipes/agentstudio.py

@@ -1,35 +1,44 @@
 # -*- coding: utf-8 -*-
 # Copyright (c) Alibaba, Inc. and its affiliates.
-"""AgentStudio sync API example: end-to-end quickstart.
+"""dashscope 2.0 agent recipe: AgentStudio end-to-end quickstart.
 
 Flow: create environment -> create agent -> create session ->
 send message -> stream events -> archive session.
 
+AgentStudio is shared by the 1.x and 2.0 SDK generations: the 2.0
+client mounts it as ``client.agentstudio`` (workspace and region
+forward from the client config) and translates its errors into the
+``dashscope.v2`` exception family, so one ``client`` covers both the
+2.0 resources and AgentStudio.
+
 `memory_stores_demo` covers the memory store flow (create store ->
 write memory -> list -> update -> list versions -> delete). It creates
 and deletes a real store, so it is opt-in: uncomment its call below.
+
+Requires DASHSCOPE_API_KEY; DASHSCOPE_WORKSPACE selects the
+AgentStudio workspace (defaults to trial).
 """
 
 import os
 
-from dashscope.agentstudio import Client, user_message
+import dashscope
+from dashscope.agentstudio import user_message
 
 
-def make_client() -> Client:
-    # Authentication: set your Model Studio API key via the
-    # DASHSCOPE_API_KEY environment variable, and the workspace via
-    # DASHSCOPE_WORKSPACE (defaults to trial)
-    return Client(
-        api_key=os.environ["DASHSCOPE_API_KEY"],
+def make_client():
+    # Authentication: the client reads the API key from the
+    # DASHSCOPE_API_KEY environment variable by default.
+    return dashscope.Client(
         workspace=os.environ.get("DASHSCOPE_WORKSPACE", "trial"),
     )
 
 
 def main() -> None:
     client = make_client()
+    studio = client.agentstudio
 
     print("==> creating environment")
-    env = client.environments.create(
+    env = studio.environments.create(
         name="quickstart-env",
         config={
             "type": "cloud",
@@ -39,7 +48,7 @@ def main() -> None:
     print(f"   environment_id={env.id}")
 
     print("==> creating agent")
-    agent = client.agents.create(
+    agent = studio.agents.create(
         name="quickstart-agent",
         system_prompt="You are a friendly demo agent. Reply briefly.",
         model="qwen3.8-max",
@@ -54,59 +63,59 @@ def main() -> None:
     print(f"   agent_id={agent.id}")
 
     print("==> creating session")
-    session = client.sessions.create(
+    session = studio.sessions.create(
         agent=agent.id,
         environment_id=env.id,
         title="quickstart",
     )
     print(f"   session_id={session.id}")
 
     print("==> sending user message")
-    client.sessions.events.send(
+    studio.sessions.events.send(
         session.id,
         [user_message("Hello! Tell me one fun fact about Hangzhou.")],
     )
 
     print("==> streaming events")
-    with client.sessions.events.stream(session.id) as stream:
+    with studio.sessions.events.stream(session.id) as stream:
         for text in stream.text_stream:
             print(text, end="", flush=True)
         print()  # newline after streaming
 
     print("==> archiving session")
-    client.sessions.archive(session.id)
+    studio.sessions.archive(session.id)
     print("done.")
 
 
 def memory_stores_demo() -> None:
     """Memory store flow: create store -> seed memory -> read back
     -> audit versions -> cleanup."""
-    client = make_client()
+    studio = make_client().agentstudio
 
     print("==> creating memory store")
-    store = client.memory_stores.create(
+    store = studio.memory_stores.create(
         name="demo-preferences",
         description="Per-user preferences and project context.",
     )
     print(f"   memory_store_id={store.id}")
 
     print("==> seeding a memory")
-    mem = client.memory_stores.memories.create(
+    mem = studio.memory_stores.memories.create(
         store.id,
         path="/formatting_standards.md",
         content="All reports use GAAP formatting.",
     )
     print(f"   memory_id={mem.id} size={mem.content_size_bytes}")
 
     print("==> listing memories")
-    page = client.memory_stores.memories.list(store.id, view="full")
+    page = studio.memory_stores.memories.list(store.id, view="full")
     for item in page:
         print(f"   {item.path} -> {item.content}")
     # Directory nodes ride the page's prefixes field (per page):
     print(f"   prefixes={page.prefixes}")
 
     print("==> updating with optimistic lock")
-    updated = client.memory_stores.memories.update(
+    updated = studio.memory_stores.memories.update(
         store.id,
         mem.id,
         content="All reports use GAAP formatting. ISO-8601 dates.",
@@ -115,11 +124,11 @@ def memory_stores_demo() -> None:
     print(f"   new sha={updated.content_sha256[:12]}...")
 
     print("==> listing versions")
-    for v in client.memory_stores.memory_versions.list(store.id):
+    for v in studio.memory_stores.memory_versions.list(store.id):
         print(f"   {v.id}: {v.operation}")
 
     print("==> deleting memory store")
-    client.memory_stores.delete(store.id)
+    studio.memory_stores.delete(store.id)
     print("done.")
 
 

…les/legacy_1x/agentstudio_deployments.py …agent_recipes/agentstudio_deployments.pyexamples/legacy_1x/agentstudio_deployments.py renamed to examples/03_agent_recipes/agentstudio_deployments.py examples/legacy_1x/agentstudio_deployments.py renamed to examples/03_agent_recipes/agentstudio_deployments.py

@@ -1,15 +1,21 @@
 # -*- coding: utf-8 -*-
-"""Create and run a Managed Agent deployment.
+# Copyright (c) Alibaba, Inc. and its affiliates.
+"""dashscope 2.0 agent recipe: create and run a Managed Agent deployment.
 
-Set DASHSCOPE_API_KEY and DASHSCOPE_WORKSPACE before running this sample.
+Requires DASHSCOPE_API_KEY; DASHSCOPE_WORKSPACE selects the
+AgentStudio workspace (defaults to trial).
 """
 
-from dashscope.agentstudio import Client, user_message
+import os
+
+import dashscope
+from dashscope.agentstudio import user_message
 
 
 def main() -> None:
-    with Client() as client:
-        deployment = client.deployments.create(
+    workspace = os.environ.get("DASHSCOPE_WORKSPACE", "trial")
+    with dashscope.Client(workspace=workspace) as client:
+        deployment = client.agentstudio.deployments.create(
             name="daily-summary",
             description="Generate a daily summary",
             agent={"id": "agent_xxx"},
@@ -23,10 +29,13 @@ def main() -> None:
         )
         print("deployment:", deployment.id, deployment.status)
 
-        run = client.deployments.run(deployment.id)
+        run = client.agentstudio.deployments.run(deployment.id)
         print("run:", run.id, run.status)
 
-        for item in client.deployments.list_runs(deployment.id, limit=20):
+        for item in client.agentstudio.deployments.list_runs(
+            deployment.id,
+            limit=20,
+        ):
             print(item.id, item.trigger_source, item.status)
 
 

examples/README.md

@@ -104,6 +104,7 @@ Uniform style: `client = dashscope.Client()` (reads the key from the `DASHSCOPE_
 | `files/files.py` | File management: upload / list / get / delete |
 | `applications/apps.py` | Model Studio application invocation (non-streaming + streaming) |
 | `fine_tuning/fine_tunes.py` | Fine-tune jobs: list / get, create / wait / delete (uncomment to run) |
+| `fine_tuning/reinforcement_learning.py` | Agentic RL: list / get jobs; register functions -> upload data -> create / wait / delete (uncomment to run) |
 | `models/models.py` | Model list and get |
 
 ## 02_advanced_engineering — Advanced engineering
@@ -121,6 +122,8 @@ Uniform style: `client = dashscope.Client()` (reads the key from the `DASHSCOPE_
 | `tool_call_loop.py` | Managed multi-turn tool-call state machine: declare `tools` schemas, execute locally when the model requests a call, feed the `role="tool"` result back, and loop until a final answer (with a `MAX_TURNS` backstop) | Yes |
 | `rag_expert_system.py` | Standard RAG: corpus embedding -> cosine top-k recall -> `client.rerank` refinement -> an "answer only from the sources" chat prompt -> an answer with citations | Yes |
 | `mcp_server_demo/` | Dependency-free MCP (Model Context Protocol) stdio server + client demo: `server.py` speaks JSON-RPC 2.0; `client_demo.py` spawns the subprocess and runs initialize -> tools/list -> tools/call. See its `README.md` | No |
+| `agentstudio.py` | AgentStudio end-to-end quickstart via `client.agentstudio`: environment -> agent -> session -> streamed reply (plus an opt-in memory-store demo); AgentStudio is shared by the 1.x/2.0 generations and mounts on the 2.0 client | Yes |
+| `agentstudio_deployments.py` | Managed Agent deployments: create a cron-scheduled deployment, trigger a run, list runs | Yes |
 
 ## 04_real_world_scenarios — Real-world scenarios
 
@@ -146,7 +149,6 @@ The following use the old 1.x style (`dashscope.Generation`, `dashscope.MultiMod
 | `multimodal_conversation/` | MultiModalConversation multimodal chat: image, video, tool calls, OCR, ASR, deep thinking |
 | `aio_multimodal_conversation/` | Async versions of the above |
 | `application.py` | Model Studio application (Application) invocation |
-| `agentstudio.py` / `agentstudio_deployments.py` | AgentStudio sessions and managed deployments |
 | `assistant_api*.py` | Assistant agents: create / update, file attachment, end-to-end dialogue |
 | `image_generation.py` / `image_synthesis.py` / `aio_image_synthesis.py` | Image generation (wanx / wan2.x) |
 | `video_synthesis.py` / `aio_video_synthesis.py` | Video generation (wan series) |

examples/README_zh.md

@@ -104,6 +104,7 @@ examples/
 | `files/files.py` | 文件管理：上传 / 列表 / 查询 / 删除 |
 | `applications/apps.py` | 百炼应用调用（非流式 + 流式） |
 | `fine_tuning/fine_tunes.py` | 微调任务：list / get、create / wait / delete（取消注释即可运行） |
+| `fine_tuning/reinforcement_learning.py` | 智能体 RL：任务 list / get；注册函数 -> 上传数据 -> create / wait / delete（取消注释即可运行） |
 | `models/models.py` | 模型列表与详情 |
 
 ## 02_advanced_engineering —— 进阶工程
@@ -121,6 +122,8 @@ examples/
 | `tool_call_loop.py` | 受管多轮工具调用状态机：声明 `tools` schema，模型请求调用时本地执行，把 `role="tool"` 结果喂回，循环直到最终答案（带 `MAX_TURNS` 兜底） | 是 |
 | `rag_expert_system.py` | 标准 RAG：语料向量 -> 余弦 top-k 召回 -> `client.rerank` 精排 -> "仅依据资料作答"的聊天 prompt -> 带引用的答案 | 是 |
 | `mcp_server_demo/` | 零依赖 MCP（Model Context Protocol）stdio server + client 演示：`server.py` 讲 JSON-RPC 2.0；`client_demo.py` 拉起子进程并跑 initialize -> tools/list -> tools/call。见其 `README.md` | 否 |
+| `agentstudio.py` | AgentStudio 端到端 quickstart（经 `client.agentstudio`）：环境 -> 智能体 -> 会话 -> 流式回复（另附可选的 memory store 演示）；AgentStudio 为 1.x/2.0 两代共用模块，挂载在 2.0 客户端上 | 是 |
+| `agentstudio_deployments.py` | 托管智能体部署：创建 cron 定时部署、触发运行、列出运行记录 | 是 |
 
 ## 04_real_world_scenarios —— 真实场景
 
@@ -146,7 +149,6 @@ examples/
 | `multimodal_conversation/` | MultiModalConversation 多模态对话：图像、视频、工具调用、OCR、ASR、深度思考 |
 | `aio_multimodal_conversation/` | 上述的异步版本 |
 | `application.py` | 百炼应用（Application）调用 |
-| `agentstudio.py` / `agentstudio_deployments.py` | AgentStudio 会话与托管部署 |
 | `assistant_api*.py` | Assistant 智能体：创建 / 更新、文件挂载、端到端对话 |
 | `image_generation.py` / `image_synthesis.py` / `aio_image_synthesis.py` | 图像生成（wanx / wan2.x） |
 | `video_synthesis.py` / `aio_video_synthesis.py` | 视频生成（wan 系列） |