update doc

Author: Yunnglin

README.md

@@ -91,7 +91,52 @@ async def main():
 
 asyncio.run(main())
 ```
+---
+
+## Agent Model Tool Calling (OpenAI Tools)
+
+Expose sandbox tools to the Agent in OpenAI Tools format, allowing the model to trigger tools and execute them securely in the sandbox.
+
+````python
+import asyncio, os, json
+from openai import OpenAI
+from ms_enclave.sandbox.manager import SandboxManagerFactory
+from ms_enclave.sandbox.model import DockerSandboxConfig, SandboxType
+
+async def demo():
+    client = OpenAI(
+        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
+        api_key=os.getenv("DASHSCOPE_API_KEY")
+    )
+    async with SandboxManagerFactory.create_manager() as m:
+        cfg = DockerSandboxConfig(image="python:3.11-slim", tools_config={"python_executor": {}, "shell_executor": {}})
+        sid = await m.create_sandbox(SandboxType.DOCKER, cfg)
 
+        tools = list((await m.get_sandbox_tools(sid)).values())
+        messages = [{"role": "user", "content": "Print 'hello' in Python, then list /sandbox via shell."}]
+
+        rsp = client.chat.completions.create(model="qwen-plus", messages=messages, tools=tools, tool_choice="auto")
+        msg = rsp.choices[0].message
+        messages.append(msg.model_dump())
+
+        if getattr(msg, "tool_calls", None):
+            for tc in msg.tool_calls:
+                name = tc.function.name
+                args = json.loads(tc.function.arguments or "{}")
+                result = await m.execute_tool(sid, name, args)
+                messages.append({"role": "tool", "content": result.model_dump_json(), "tool_call_id": tc.id, "name": name})
+            final = client.chat.completions.create(model="qwen-plus", messages=messages)
+            print(final.choices[0].message.content or "")
+        else:
+            print(msg.content or "")
+
+asyncio.run(demo())
+````
+
+**Notes:**
+- Use `get_sandbox_tools(sandbox_id)` to retrieve tool schemas (OpenAI-compatible)
+- Pass `tools=...` to the model, handle returned `tool_calls` and execute them in the sandbox
+- Call the model again to generate the final answer
 ---
 
 ## Typical Usage Patterns & Examples

README_zh.md

@@ -96,6 +96,53 @@ asyncio.run(main())
 
 ---
 
+## Agent 模型工具调用（OpenAI Tools）
+
+将沙箱工具以 OpenAI Tools 形式暴露给 Agent，模型触发工具后在沙箱中安全执行。
+
+````python
+import asyncio, os, json
+from openai import OpenAI
+from ms_enclave.sandbox.manager import SandboxManagerFactory
+from ms_enclave.sandbox.model import DockerSandboxConfig, SandboxType
+
+async def demo():
+    client = OpenAI(
+        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1",
+        api_key=os.getenv("DASHSCOPE_API_KEY")
+    )
+    async with SandboxManagerFactory.create_manager() as m:
+        cfg = DockerSandboxConfig(image="python:3.11-slim", tools_config={"python_executor": {}, "shell_executor": {}})
+        sid = await m.create_sandbox(SandboxType.DOCKER, cfg)
+
+        tools = list((await m.get_sandbox_tools(sid)).values())
+        messages = [{"role": "user", "content": "Print 'hello' in Python, then list /sandbox via shell."}]
+
+        rsp = client.chat.completions.create(model="qwen-plus", messages=messages, tools=tools, tool_choice="auto")
+        msg = rsp.choices[0].message
+        messages.append(msg.model_dump())
+
+        if getattr(msg, "tool_calls", None):
+            for tc in msg.tool_calls:
+                name = tc.function.name
+                args = json.loads(tc.function.arguments or "{}")
+                result = await m.execute_tool(sid, name, args)
+                messages.append({"role": "tool", "content": result.model_dump_json(), "tool_call_id": tc.id, "name": name})
+            final = client.chat.completions.create(model="qwen-plus", messages=messages)
+            print(final.choices[0].message.content or "")
+        else:
+            print(msg.content or "")
+
+asyncio.run(demo())
+````
+
+说明：
+- 使用 `get_sandbox_tools(sandbox_id)` 获取工具 schema（OpenAI 兼容）
+- 将 `tools=...` 传入模型，处理返回的 `tool_calls` 并在沙箱执行
+- 再次调用模型生成最终答案
+
+---
+
 ## 典型使用方式与示例
 
 

docs/en/docs/getting-started/quickstart.md

@@ -153,3 +153,154 @@ if __name__ == '__main__':
 ```bash
 python quickstart_app.py
 ```
+---
+
+## Method 3: Agent Tool Execution
+
+When your Agent supports OpenAI Tools (function calling), you can expose sandbox tools as callable functions, allowing the model to trigger tools and execute them in the sandbox.
+
+### Use Cases
+- Need the LLM to autonomously decide when to run Python code or Shell commands
+- Want to inject safely controlled code execution capabilities into the Agent
+
+### Usage Steps
+1) Create a manager and sandbox, and enable tools
+2) Retrieve the sandbox's tool schema (OpenAI-compatible format)
+3) Call the model (tools=...), collect tool_calls
+4) Execute corresponding tools in the sandbox and append tool messages
+5) Let the model generate the final answer again
+
+### Code Example
+````python
+import asyncio
+import json
+import os
+from typing import Any, Dict, List, Optional
+
+from openai import OpenAI
+from ms_enclave.sandbox.manager import SandboxManagerFactory
+from ms_enclave.sandbox.model import DockerSandboxConfig, SandboxType
+
+async def run_agent_with_sandbox() -> None:
+    """
+    Create a sandbox, bind tools to an agent (qwen-plus via DashScope), and execute tool calls.
+    Prints final model output and minimal tool execution results.
+    """
+
+    client = OpenAI(
+        base_url="https://dashscope.aliyuncs.com/compatible-mode/v1", 
+        api_key=os.environ.get("DASHSCOPE_API_KEY")
+    )
+
+    async with SandboxManagerFactory.create_manager() as manager:
+        config = DockerSandboxConfig(
+            image="python:3.11-slim",
+            tools_config={
+                "python_executor": {}, 
+                "shell_executor": {}, 
+                "file_operation": {}
+            },
+            volumes={os.path.abspath("./output"): {"bind": "/sandbox/data", "mode": "rw"}},
+        )
+
+        sandbox_id = await manager.create_sandbox(SandboxType.DOCKER, config)
+
+        # Fetch available tools from the sandbox and convert to OpenAI format
+        available_tools = await manager.get_sandbox_tools(sandbox_id)
+
+        messages: List[Dict[str, Any]] = [
+            {
+                "role": "system",
+                "content": (
+                    "You can run Python code and shell commands inside a managed sandbox using provided tools. "
+                    "Always use tools to perform code execution or shell operations, then summarize results concisely."
+                ),
+            },
+            {
+                "role": "user",
+                "content": (
+                    "1) Run Python to print 'hi from sandbox' and compute 123456*654321.\n"
+                    "2) Run a shell command to list /sandbox/data directory.\n"
+                    "Finally, summarize the outputs."
+                ),
+            },
+        ]
+
+        # First model call with tools bound
+        completion = client.chat.completions.create(
+            model="qwen-plus", messages=messages, tools=list(available_tools.values()), tool_choice="auto"
+        )
+        msg = completion.choices[0].message
+
+        messages.append(msg.model_dump())
+
+        # Handle tool calls; execute in sandbox and feed results back to the model
+        tool_summaries: List[str] = []
+        if getattr(msg, "tool_calls", None):
+            for call in msg.tool_calls:
+                name = call.function.name
+                args = json.loads(call.function.arguments or "{}")
+                tool_result = await manager.execute_tool(sandbox_id, name, args)
+                tool_summaries.append(f"{name} => {args} => {tool_result.status}")
+                messages.append(
+                    {
+                        "role": "tool",
+                        "content": tool_result.model_dump_json(),
+                        "tool_call_id": call.id,
+                        "name": name,
+                    }
+                )
+
+            # Ask the model to produce the final answer after tool results are added
+            final = client.chat.completions.create(model="qwen-plus", messages=messages)
+            final_text = final.choices[0].message.content or ""
+            print("Model output:" + "=" * 20)
+            print(final_text)
+        else:
+            # If no tool calls were made, just print the model output
+            print("Model output:" + "=" * 20)
+            print(msg.content or "")
+
+        # Minimal summary of executed tools
+        if tool_summaries:
+            print("Executed tools:" + "=" * 20)
+            for s in tool_summaries:
+                print(f"- {s}")
+
+
+def main() -> None:
+    """Entry point."""
+    asyncio.run(run_agent_with_sandbox())
+
+if __name__ == "__main__":
+    main()
+
+````
+
+> Tip: Any model/service compatible with OpenAI Tools can use this pattern; you need to pass the sandbox tool schema to tools and execute each tool_call sequentially.
+
+Output Example:
+```text
+[INFO:ms_enclave] Local sandbox manager started
+[INFO:ms_enclave] Created and started sandbox a3odo8es of type docker
+[INFO:ms_enclave] [📦 a3odo8es] hi from sandbox
+[INFO:ms_enclave] [📦 a3odo8es] hello.txt
+Model output:====================
+- Python printed: `hi from sandbox`
+- Computed `123456 * 654321 = 80779853376`
+- The `/sandbox/data` directory contains one file: `hello.txt`
+
+Summary: The sandbox successfully executed the print and multiplication tasks, and the data directory listing revealed a single file named `hello.txt`.
+Executed tools:====================
+- python_executor => {'code': "print('hi from sandbox')\n123456 * 654321"} => success
+- shell_executor => {'command': 'ls /sandbox/data'} => success
+[INFO:ms_enclave] Cleaning up 1 sandboxes
+[INFO:ms_enclave] Deleted sandbox a3odo8es
+[INFO:ms_enclave] Local sandbox manager stopped
+```
+
+## Summary
+
+- **For experiments, scripts, unit tests** -> Recommended: **SandboxFactory**.
+- **For backend services, task scheduling, production environments** -> Recommended: **SandboxManagerFactory**.
+- **Need model to autonomously call tools** -> Use **SandboxManager** combined with OpenAI Tools.

docs/en/mkdocs.yml

@@ -69,6 +69,13 @@ theme:
 
 # Add social links (bottom right)
 extra:
+  alternate:
+    - name: English
+      link: https://ms-enclave.readthedocs.io/en/latest/ 
+      lang: en
+    - name: 中文
+      link: https://ms-enclave.readthedocs.io/zh-cn/latest/
+      lang: zh
   social:
     - icon: fontawesome/brands/github
       link: https://github.com/modelscope/ms-enclave