Merge branch 'dev' into refactor/remove-space

Author: GenerQAQ

docs/api-reference/openapi.json

@@ -187,6 +187,68 @@
         } ]
       }
     },
+    "/agent_skills/{id}/download_to_sandbox" : {
+      "post" : {
+        "description" : "Download all files from an agent skill to a sandbox environment. Files are placed at /skills/{skill_name}/.",
+        "parameters" : [ {
+          "description" : "Agent skill UUID",
+          "in" : "path",
+          "name" : "id",
+          "required" : true,
+          "schema" : {
+            "type" : "string"
+          }
+        } ],
+        "requestBody" : {
+          "content" : {
+            "application/json" : {
+              "schema" : {
+                "$ref" : "#/components/schemas/handler.DownloadSkillToSandboxReq"
+              }
+            }
+          },
+          "description" : "Download to sandbox request",
+          "required" : true
+        },
+        "responses" : {
+          "200" : {
+            "content" : {
+              "application/json" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/_agent_skills__id__download_to_sandbox_post_200_response"
+                }
+              }
+            },
+            "description" : "OK"
+          },
+          "409" : {
+            "content" : {
+              "application/json" : {
+                "schema" : {
+                  "$ref" : "#/components/schemas/serializer.Response"
+                }
+              }
+            },
+            "description" : "Skill directory already exists in sandbox"
+          }
+        },
+        "security" : [ {
+          "BearerAuth" : [ ]
+        } ],
+        "summary" : "Download skill to sandbox",
+        "tags" : [ "agent_skills" ],
+        "x-code-samples" : [ {
+          "label" : "Python",
+          "lang" : "python",
+          "source" : "from acontext import AcontextClient\n\nclient = AcontextClient(api_key='sk_project_token')\n\n# Download skill to sandbox\nresult = client.skills.download_to_sandbox(\n    skill_id='skill-uuid',\n    sandbox_id='sandbox-uuid'\n)\nprint(f\"Success: {result.success}\")\nprint(f\"Skill installed at: {result.dir_path}\")\n"
+        }, {
+          "label" : "JavaScript",
+          "lang" : "javascript",
+          "source" : "import { AcontextClient } from '@acontext/acontext';\n\nconst client = new AcontextClient({ apiKey: 'sk_project_token' });\n\n// Download skill to sandbox\nconst result = await client.skills.downloadToSandbox('skill-uuid', {\n  sandboxId: 'sandbox-uuid'\n});\nconsole.log(`Success: ${result.success}`);\nconsole.log(`Skill installed at: ${result.dir_path}`);\n"
+        } ],
+        "x-codegen-request-body-name" : "request"
+      }
+    },
     "/agent_skills/{id}/file" : {
       "get" : {
         "description" : "Get file content or download URL from agent skill. If the file is text-based (parseable), returns parsed content. Otherwise, returns a presigned download URL.",
@@ -1846,6 +1908,37 @@
         },
         "type" : "object"
       },
+      "handler.DownloadSkillToSandboxReq" : {
+        "properties" : {
+          "sandbox_id" : {
+            "description" : "Target sandbox ID",
+            "type" : "string"
+          }
+        },
+        "required" : [ "sandbox_id" ],
+        "type" : "object"
+      },
+      "handler.DownloadSkillToSandboxResp" : {
+        "properties" : {
+          "description" : {
+            "description" : "Skill description",
+            "type" : "string"
+          },
+          "dir_path" : {
+            "description" : "Full path to the skill directory in sandbox",
+            "type" : "string"
+          },
+          "name" : {
+            "description" : "Skill name",
+            "type" : "string"
+          },
+          "success" : {
+            "description" : "Whether the download was successful",
+            "type" : "boolean"
+          }
+        },
+        "type" : "object"
+      },
       "handler.DownloadToSandboxReq" : {
         "properties" : {
           "file_path" : {
@@ -2613,6 +2706,18 @@
           "type" : "object"
         } ]
       },
+      "_agent_skills__id__download_to_sandbox_post_200_response" : {
+        "allOf" : [ {
+          "$ref" : "#/components/schemas/serializer.Response"
+        }, {
+          "properties" : {
+            "data" : {
+              "$ref" : "#/components/schemas/handler.DownloadSkillToSandboxResp"
+            }
+          },
+          "type" : "object"
+        } ]
+      },
       "_agent_skills__id__file_get_200_response" : {
         "allOf" : [ {
           "$ref" : "#/components/schemas/serializer.Response"

docs/chore/async_python.mdx

@@ -26,7 +26,7 @@ Every method is available in async client, just add `await` prefix to the method
 
 ## Async Agentic Tools
 
-The [Filesystem Tools](/tool/disk_tools) and [Skill Tools](/tool/skill_tools) also support async operations. Use `async_format_context()` and `async_execute_tool()` methods with `AcontextAsyncClient`.
+The [Filesystem Tools](/tool/disk_tools), [Skill Tools](/tool/skill_tools), and [Sandbox Tools](/tool/bash_tools) also support async operations. Use `async_format_context()` and `async_execute_tool()` methods with `AcontextAsyncClient`.
 
 ### Async Disk Tools
 
@@ -132,6 +132,76 @@ while True:
         )
 ```
 
+### Async Sandbox Tools
+
+```python Python
+import json
+from acontext import AcontextAsyncClient
+from acontext.agent.sandbox import SANDBOX_TOOLS
+from openai import AsyncOpenAI
+
+# Initialize async clients
+acontext_client = AcontextAsyncClient(
+    api_key=os.getenv("ACONTEXT_API_KEY"),
+)
+openai_client = AsyncOpenAI()
+
+# Create sandbox and disk
+sandbox = await acontext_client.sandboxes.create()
+disk = await acontext_client.disks.create()
+
+# Create async sandbox context (optionally mount skills)
+ctx = await SANDBOX_TOOLS.async_format_context(
+    acontext_client,
+    sandbox_id=sandbox.sandbox_id,
+    disk_id=disk.id,
+    # mount_skills=["skill-uuid-1", "skill-uuid-2"]
+)
+
+# Get tool schemas for OpenAI
+tools = SANDBOX_TOOLS.to_openai_tool_schema()
+
+# Get context prompt to include in system message
+context_prompt = ctx.get_context_prompt()
+
+# Async agentic loop
+messages = [
+    {
+        "role": "system",
+        "content": f"You are a helpful assistant.\n\n{context_prompt}",
+    },
+    {"role": "user", "content": "Create a Python script and run it"}
+]
+
+while True:
+    response = await openai_client.chat.completions.create(
+        model="gpt-4.1",
+        messages=messages,
+        tools=tools,
+    )
+
+    message = response.choices[0].message
+    messages.append(message)
+
+    if not message.tool_calls:
+        print(f"🤖 Assistant: {message.content}")
+        break
+
+    # Execute each tool call asynchronously
+    for tool_call in message.tool_calls:
+        print(f"⚙️ Called {tool_call.function.name}")
+        result = await SANDBOX_TOOLS.async_execute_tool(
+            ctx, tool_call.function.name, json.loads(tool_call.function.arguments)
+        )
+        print(f"🔍 Result: {result}")
+        messages.append(
+            {"role": "tool", "tool_call_id": tool_call.id, "content": result}
+        )
+
+# Clean up
+await acontext_client.sandboxes.kill(sandbox.sandbox_id)
+```
+
 <Tip>
 The async versions are identical to the sync versions except:
 - Use `AcontextAsyncClient` instead of `AcontextClient`

docs/docs.json

@@ -48,8 +48,8 @@
             "group": "Agent Tools",
             "icon": "wand-magic-sparkles",
             "pages": [
-              "tool/disk_tools",
-              "tool/skill_tools"
+              "tool/bash_tools",
+              "tool/disk_tools"
             ]
           },
           {
@@ -89,7 +89,8 @@
             "pages": [
               "chore/per-user",
               "chore/async_python",
-              "chore/badge"
+              "chore/badge",
+              "tool/skill_tools"
             ]
           },
           {

docs/store/sandbox.mdx

@@ -6,13 +6,13 @@ description: "Execute code in isolated, ephemeral sandbox environments"
 The Sandbox API provides secure, isolated environments for executing shell commands. 
 Each sandbox is a temporary container that runs independently, perfect for running untrusted code or testing scripts.
 
-{/* ## Setup Sandbox for your Agent
+## Setup Sandbox for your Agent
 
-<Card title="Agentic Bash Tools" icon="terminal" href="/tool/bash_tools">
-Give your agent the ability to execute commands with pre-built tools.
+<Card title="Agentic Sandbox Tools" icon="terminal" href="/tool/bash_tools">
+Give your agent the ability to execute commands, edit files, and export results with pre-built tools.
 </Card>
 
-If you'd like to know the details of Sandbox APIs, please read the following documentation. */}
+If you'd like to know the details of Sandbox APIs, please read the following documentation.
 
 ## What you'll build
 

docs/store/skill.mdx

@@ -7,9 +7,15 @@ The Skills API provides storage and management for [Agent Skills](https://agents
 
 ## Setup Skills for your Agent
 
-<Card title="Agentic Skill Tools" icon="wand-magic-sparkles" href="/tool/skill_tools">
-Enable your agent to access and utilize skills with pre-built tools.
+<CardGroup cols={2}>
+<Card title="Sandbox with Skills" icon="terminal" href="/tool/bash_tools#mounting-skills-in-sandbox">
+Mount skills in a sandbox to execute skill scripts and access skill files.
+</Card>
+
+<Card title="Skill Content Tools" icon="wand-magic-sparkles" href="/tool/skill_tools">
+Enable your agent to read skill files with pre-built tools. No sandbox required.
 </Card>
+</CardGroup>
 
 If you'd like to know the details of Skills APIs, please read the following documentation.