Merge branch 'main' into deploy-oauth

Author: zhxie

.gitignore

@@ -196,4 +196,7 @@ cython_debug/
 
 **/.nuxt
 **/.data
-**./output
+**./output
+
+*.mp3
+*.pcm

config.yaml.full

@@ -46,6 +46,11 @@ tool:
   web_scraper: 
     endpoint: 
     api_key:    # `token`
+  # [optional] https://console.volcengine.com/speech/new/experience/tts
+  text_to_speech:
+    app_id:     # `app_id`
+    api_key:    # `app_secret`
+    speaker:    # `speaker`
   # [optional] https://open.larkoffice.com/app
   lark: 
     endpoint:   # `app_id`

docs/content/5.tools/3.sandbox-tools.md

@@ -5,8 +5,73 @@ navigation:
   icon: i-lucide-codesandbox
 ---
 
-提供多种沙箱工具：
+## 概述
 
+VeADK 提供多种沙箱工具，为 Agent 的执行与操作提供安全、隔离的运行环境。目前支持以下几种类型：
+- Code sandbox
 - Computer sandbox (TBD)
 - Browser sandbox (TBD)
-- Code sandbox (TBD)
+
+当前，VeADK 支持两种方式调用 Code Sandbox：
+- （推荐）内建工具 [`run_code`](https://www.volcengine.com/docs/86681/1847934)：该方式通过 AgentKit tools 调用，配置过程可自定义代码生成模型。通过设置环境变量 `AGENTKIT_TOOL_ID` 或者在 config.yaml 中添加配置即可开始使用：
+  ```yaml
+  agentkit:
+    tool:
+      id: <your_id>
+  ```
+- MCP 工具 [`code_sandbox`](https://www.volcengine.com/mcp-marketplace/detail?name=Code-Sandbox%20MCP)：该方式通过 MCP（Model Context Protocol） 调用 Code Sandbox 工具，具体步骤为：
+  - 在 VeFaaS 一键部署 [Code Sandbox Agent 应用](https://www.volcengine.com/docs/6662/1538139)，配置过程中可自定义代码生成模型；
+  - 部署成功后，在部署的 Code sanbox 的应用详情标签页获取**访问地址**，地址形式是：{YOUR_URL}/?token={YOUR_TOKEN}；
+  - 为 Code sandbox [创建 MCP Server](https://www.volcengine.com/mcp-marketplace/detail?name=Code-Sandbox%20MCP) 并配置环境变量：
+    ```bash
+    SANDBOX_API={YOUR_URL}
+    AUTH_TOKEN={YOUR_TOKEN}
+    ```
+  - 最后，将上述 Code sanbox 访问地址设置环境变量 `TOOL_CODE_SANDBOX_URL` 或者在 config.yaml 中添加配置即可开始使用：
+    ```yaml
+    tool:
+      code_sandbox:
+        url: <your_url>
+    ```
+
+
+## 使用
+以下示例展示了在 VeADK 中如何通过两种方式调用沙箱工具来执行代码。
+
+示例一：使用内建工具 `run_code`：
+
+```python [agent.py]
+import asyncio 
+from veadk import Agent, Runner
+from veadk.tools.builtin_tools.run_code import run_code
+
+agent = Agent(
+    instruction="你是一名资深的代码专家。请通过调用 run_code 工具执行代码、调试、并展示运行结果。",
+    tools=[run_code]
+) 
+
+runner = Runner(agent=agent)
+
+response = asyncio.run(runner.run(messages="请用Python写一个函数，计算斐波那契数列的前10项，并打印出来。"))
+
+print(response)
+```
+
+示例二：使用 MCP 工具 `code_sandbox`
+
+```python [agent.py]
+import asyncio 
+from veadk import Agent, Runner
+from veadk.tools.sandbox.code_sandbox import code_sandbox
+
+agent = Agent(
+    instruction="你是一名资深的代码专家。请通过调用 code_sandbox 工具执行代码、调试、并展示运行结果。",
+    tools=[code_sandbox]
+) 
+
+runner = Runner(agent=agent)
+
+response = asyncio.run(runner.run(messages="请用Python写一个函数，计算斐波那契数列的前10项，并打印出来。"))
+
+print(response)
+```

pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "veadk-python"
-version = "0.2.21"
+version = "0.2.22"
 description = "Volcengine agent development kit, integrations with Volcengine cloud services."
 readme = "README.md"
 requires-python = ">=3.10"
@@ -54,6 +54,7 @@ database = [
     "tos>=2.8.4",                   # For TOS storage and Viking DB
     "mem0ai==0.1.118",              # For mem0
 ]
+speech = []
 eval = [
     "prometheus-client>=0.22.1",    # For exporting data to Prometheus pushgateway
     "deepeval>=3.2.6",              # For DeepEval-based evaluation

tests/auth/veauth/test_speech_veauth.py

@@ -0,0 +1,113 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import pytest
+from unittest.mock import patch, MagicMock
+from veadk.auth.veauth.speech_veauth import get_speech_token
+
+
+# Test cases
+
+
+def test_get_speech_token_with_env_vars(monkeypatch):
+    """Test when credentials are available in environment variables"""
+    # Setup
+    monkeypatch.setenv("VOLCENGINE_ACCESS_KEY", "test_access_key")
+    monkeypatch.setenv("VOLCENGINE_SECRET_KEY", "test_secret_key")
+
+    mock_response = {"Result": {"APIKeys": [{"APIKey": "test_api_key"}]}}
+
+    with patch("veadk.auth.veauth.speech_veauth.ve_request") as mock_ve_request:
+        mock_ve_request.return_value = mock_response
+
+        # Execute
+        result = get_speech_token()
+
+        # Verify
+        assert result == "test_api_key"
+        mock_ve_request.assert_called_once_with(
+            request_body={
+                "ProjectName": "default",
+                "OnlyAvailable": True,
+            },
+            header={"X-Security-Token": ""},
+            action="ListAPIKeys",
+            ak="test_access_key",
+            sk="test_secret_key",
+            service="speech_saas_prod",
+            version="2025-05-20",
+            region="cn-beijing",
+            host="open.volcengineapi.com",
+        )
+
+
+def test_get_speech_token_with_vefaas_iam(monkeypatch):
+    """Test when credentials are obtained from vefaas iam"""
+    # Setup
+    monkeypatch.delenv("VOLCENGINE_ACCESS_KEY", raising=False)
+    monkeypatch.delenv("VOLCENGINE_SECRET_KEY", raising=False)
+
+    mock_cred = MagicMock()
+    mock_cred.access_key_id = "vefaas_access_key"
+    mock_cred.secret_access_key = "vefaas_secret_key"
+    mock_cred.session_token = "vefaas_session_token"
+
+    mock_response = {"Result": {"APIKeys": [{"APIKey": "vefaas_api_key"}]}}
+
+    with (
+        patch(
+            "veadk.auth.veauth.speech_veauth.get_credential_from_vefaas_iam"
+        ) as mock_get_cred,
+        patch("veadk.auth.veauth.speech_veauth.ve_request") as mock_ve_request,
+    ):
+        mock_get_cred.return_value = mock_cred
+        mock_ve_request.return_value = mock_response
+
+        # Execute
+        result = get_speech_token(region="cn-shanghai")
+
+        # Verify
+        assert result == "vefaas_api_key"
+        mock_get_cred.assert_called_once()
+        mock_ve_request.assert_called_once_with(
+            request_body={
+                "ProjectName": "default",
+                "OnlyAvailable": True,
+            },
+            header={"X-Security-Token": "vefaas_session_token"},
+            action="ListAPIKeys",
+            ak="vefaas_access_key",
+            sk="vefaas_secret_key",
+            service="speech_saas_prod",
+            version="2025-05-20",
+            region="cn-shanghai",
+            host="open.volcengineapi.com",
+        )
+
+
+def test_get_speech_token_invalid_response():
+    """Test when API response is invalid"""
+    # Setup
+    monkeypatch = pytest.MonkeyPatch()
+    monkeypatch.setenv("VOLCENGINE_ACCESS_KEY", "test_access_key")
+    monkeypatch.setenv("VOLCENGINE_SECRET_KEY", "test_secret_key")
+
+    mock_response = {"Error": {"Message": "Invalid request"}}
+
+    with patch("veadk.auth.veauth.speech_veauth.ve_request") as mock_ve_request:
+        mock_ve_request.return_value = mock_response
+
+        # Execute & Verify
+        with pytest.raises(ValueError, match="Failed to get speech api key list"):
+            get_speech_token()

tests/test_misc.py

@@ -0,0 +1,65 @@
+# Copyright (c) 2025 Beijing Volcano Engine Technology Co., Ltd. and/or its affiliates.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+import os
+import sys
+import types
+
+from veadk.utils.misc import get_agents_dir, get_agent_dir
+
+
+class GetAgentsDirTest:
+    def test_get_agents_dir_from_main_file(monkeypatch):
+        """
+        Case 1: __main__.__file__ exists (common in CLI or uv run environments)
+        """
+        fake_main = types.SimpleNamespace(__file__="/tmp/project/testapp/agent.py")
+        monkeypatch.setitem(sys.modules, "__main__", fake_main)
+
+        result = get_agents_dir()
+        assert result == "/tmp/project"
+        result = get_agent_dir()
+        assert result == "/tmp/project/testapp"
+
+    def test_get_agents_dir_from_sys_argv(monkeypatch):
+        """
+        Case 2: Fallback to sys.argv[0]
+        """
+        fake_main = types.SimpleNamespace()
+        monkeypatch.setitem(sys.modules, "__main__", fake_main)
+        monkeypatch.setattr(sys, "argv", ["/tmp/project/testapp/agent.py"])
+
+        result = get_agents_dir()
+        assert result == "/tmp/project"
+        result = get_agent_dir()
+        assert result == "/tmp/project/testapp"
+
+    def test_get_agents_dir_from_cwd(monkeypatch, tmp_path):
+        """
+        Case 3: Fallback to current working directory (REPL or no file context)
+        """
+        fake_main = types.SimpleNamespace()
+        monkeypatch.setitem(sys.modules, "__main__", fake_main)
+        monkeypatch.setattr(sys, "argv", [])
+
+        fake_cwd = tmp_path / "some_dir"
+        fake_cwd.mkdir()
+
+        monkeypatch.setattr(os, "getcwd", lambda: str(fake_cwd))
+        result = get_agents_dir()
+
+        # should return the parent of fake_cwd
+        assert result == str(tmp_path)
+        result = get_agent_dir()
+        assert result == str(tmp_path / "some_dir")

tests/test_runtime_data_collecting.py

@@ -14,6 +14,7 @@
 
 import json
 import os
+import uuid
 
 import pytest
 from utils import generate_events, generate_session
@@ -25,7 +26,7 @@
 USER_ID = "user"
 SESSION_ID = "session"
 
-EVAL_SET_ID = "temp_unittest"
+EVAL_SET_ID = "temp_unittest" + uuid.uuid4().hex
 
 
 @pytest.mark.asyncio
@@ -46,7 +47,7 @@ async def test_runtime_data_collecting():
     recorder = EvalSetRecorder(session_service=session_service, eval_set_id=EVAL_SET_ID)
     dump_path = await recorder.dump(APP_NAME, USER_ID, SESSION_ID)
 
-    assert dump_path == f"/tmp/{APP_NAME}/{recorder.eval_set_id}.evalset.json"
+    # assert dump_path == f"/tmp/{APP_NAME}/{recorder.eval_set_id}.evalset.json"
     assert os.path.exists(dump_path) and os.path.isfile(dump_path)
     assert os.path.getsize(dump_path) > 0