Merge remote-tracking branch 'upstream/main'

Author: loveyana

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)
+```

veadk/a2a/ve_a2a_server.py

@@ -35,6 +35,7 @@ def __init__(
             runner=Runner(
                 agent=agent,
                 app_name=app_name,
+                short_term_memory=short_term_memory,
             ),
         )
 

veadk/agent.py

@@ -48,6 +48,7 @@
 from veadk.tracing.base_tracer import BaseTracer
 from veadk.utils.logger import get_logger
 from veadk.utils.patches import patch_asyncio, patch_tracer
+from veadk.tools.builtin_tools.agent_authorization import check_agent_authorization
 from veadk.version import VERSION
 
 patch_tracer()
@@ -123,6 +124,8 @@ class Agent(LlmAgent):
         )
     """
 
+    enable_authz: bool = False
+
     def model_post_init(self, __context: Any) -> None:
         super().model_post_init(None)  # for sub_agents init
 
@@ -184,6 +187,18 @@ def model_post_init(self, __context: Any) -> None:
                 load_memory.custom_metadata["backend"] = self.long_term_memory.backend
             self.tools.append(load_memory)
 
+        if self.enable_authz:
+            if self.before_agent_callback:
+                if isinstance(self.before_agent_callback, list):
+                    self.before_agent_callback.append(check_agent_authorization)
+                else:
+                    self.before_agent_callback = [
+                        self.before_agent_callback,
+                        check_agent_authorization,
+                    ]
+            else:
+                self.before_agent_callback = check_agent_authorization
+
         logger.info(f"VeADK version: {VERSION}")
 
         logger.info(f"{self.__class__.__name__} `{self.name}` init done.")

veadk/cli/cli_clean.py

@@ -24,7 +24,7 @@
 
 @click.command()
 @click.option(
-    "--vefaas-application-name",
+    "--vefaas-app-name",
     required=True,
     help="VeFaaS application name to clean",
 )
@@ -39,7 +39,7 @@
     help="Volcengine secret key, if not set, will use the value of environment variable VOLCENGINE_SECRET_KEY",
 )
 def clean(
-    vefaas_application_name: str, volcengine_access_key: str, volcengine_secret_key: str
+    vefaas_app_name: str, volcengine_access_key: str, volcengine_secret_key: str
 ) -> None:
     """
     Clean and delete a VeFaaS application from the cloud.
@@ -49,7 +49,7 @@ def clean(
     and monitor the deletion process until completion.
 
     Args:
-        vefaas_application_name (str): The name of the VeFaaS application to delete
+        vefaas_app_name (str): The name of the VeFaaS application to delete
         volcengine_access_key (str): Volcengine access key for authentication.
             If None, will use VOLCENGINE_ACCESS_KEY environment variable
         volcengine_secret_key (str): Volcengine secret key for authentication.
@@ -63,24 +63,22 @@ def clean(
     if not volcengine_secret_key:
         volcengine_secret_key = getenv("VOLCENGINE_SECRET_KEY")
 
-    confirm = input(f"Confirm delete cloud app {vefaas_application_name}? (y/N): ")
+    confirm = input(f"Confirm delete cloud app {vefaas_app_name}? (y/N): ")
     if confirm.lower() != "y":
         click.echo("Delete cancelled.")
         return
     else:
         vefaas_client = VeFaaS(
             access_key=volcengine_access_key, secret_key=volcengine_secret_key
         )
-        vefaas_application_id = vefaas_client.find_app_id_by_name(
-            vefaas_application_name
-        )
+        vefaas_application_id = vefaas_client.find_app_id_by_name(vefaas_app_name)
         vefaas_client.delete(vefaas_application_id)
         click.echo(
-            f"Cloud app {vefaas_application_name} delete request has been sent to VeFaaS"
+            f"Cloud app {vefaas_app_name} delete request has been sent to VeFaaS"
         )
         while True:
             try:
-                id = vefaas_client.find_app_id_by_name(vefaas_application_name)
+                id = vefaas_client.find_app_id_by_name(vefaas_app_name)
                 if not id:
                     break
                 time.sleep(3)

veadk/cli/cli_deploy.py

@@ -22,12 +22,12 @@
 
 @click.command()
 @click.option(
-    "--access-key",
+    "--volcengine-access-key",
     default=None,
     help="Volcengine access key",
 )
 @click.option(
-    "--secret-key",
+    "--volcengine-secret-key",
     default=None,
     help="Volcengine secret key",
 )
@@ -52,8 +52,8 @@
 @click.option("--use-adk-web", is_flag=True, help="Whether to use ADK Web")
 @click.option("--path", default=".", help="Local project path")
 def deploy(
-    access_key: str,
-    secret_key: str,
+    volcengine_access_key: str,
+    volcengine_secret_key: str,
     vefaas_app_name: str,
     veapig_instance_name: str,
     veapig_service_name: str,
@@ -77,9 +77,9 @@ def deploy(
     5. Cleaning up temporary files
 
     Args:
-        access_key: Volcengine access key for API authentication. If not provided,
+        volcengine_access_key: Volcengine access key for API authentication. If not provided,
             will use VOLCENGINE_ACCESS_KEY environment variable
-        secret_key: Volcengine secret key for API authentication. If not provided,
+        volcengine_secret_key: Volcengine secret key for API authentication. If not provided,
             will use VOLCENGINE_SECRET_KEY environment variable
         vefaas_app_name: Name of the target Volcengine FaaS application where the
             project will be deployed
@@ -111,10 +111,10 @@ def deploy(
 
     logger = get_logger(__name__)
 
-    if not access_key:
-        access_key = getenv("VOLCENGINE_ACCESS_KEY")
-    if not secret_key:
-        secret_key = getenv("VOLCENGINE_SECRET_KEY")
+    if not volcengine_access_key:
+        volcengine_access_key = getenv("VOLCENGINE_ACCESS_KEY")
+    if not volcengine_secret_key:
+        volcengine_secret_key = getenv("VOLCENGINE_SECRET_KEY")
 
     user_proj_abs_path = Path(path).resolve()
     template_dir_path = Path(vefaas.__file__).parent / "template"

veadk/cli/cli_update.py

@@ -33,7 +33,7 @@
     help="Volcengine secret key for authentication. Defaults to VOLCENGINE_SECRET_KEY environment variable.",
 )
 @click.option(
-    "--application-name",
+    "--vefaas-app-name",
     required=True,
     help="Name of the cloud application to update.",
 )
@@ -45,7 +45,7 @@
 def update(
     volcengine_access_key: str,
     volcengine_secret_key: str,
-    application_name: str,
+    vefaas_app_name: str,
     path: str,
 ) -> None:
     """Update function code of a deployed cloud application on Volcengine FaaS.
@@ -65,7 +65,7 @@ def update(
             If not provided, uses VOLCENGINE_ACCESS_KEY environment variable.
         volcengine_secret_key: Volcengine platform secret key for authentication.
             If not provided, uses VOLCENGINE_SECRET_KEY environment variable.
-        application_name: Name of the existing cloud application to update.
+        vefaas_app_name: Name of the existing cloud application to update.
         path: Local directory path containing the updated agent project.
             Defaults to current directory if not specified.
 
@@ -93,11 +93,11 @@ def update(
     try:
         # Update function code
         updated_app = engine.update_function_code(
-            application_name=application_name,
+            application_name=vefaas_app_name,
             path=path,
         )
 
-        logger.info(f"Successfully updated cloud application '{application_name}'")
+        logger.info(f"Successfully updated cloud application '{vefaas_app_name}'")
         logger.info(f"Endpoint: {updated_app.vefaas_endpoint}")
         logger.info(f"Application ID: {updated_app.vefaas_application_id}")
 

veadk/configs/auth_configs.py

@@ -39,6 +39,10 @@ class VeIdentityConfig(BaseSettings):
     If not provided, the endpoint will be auto-generated based on the region.
     """
 
+    role_session_name: str = "veadk_default_assume_role_session"
+    """Role session name, used to distinguish different sessions in audit logs.
+    """
+
     def get_endpoint(self) -> str:
         """Get the endpoint URL for Identity service.