wuying-agentbay-sdk 0.10.2 → 0.12.0

package/docs/examples/common-features/advanced/agent-module-example/README.md

@@ -0,0 +1,40 @@
+# Agent Module Example
+
+This example demonstrates how to use the Agent module to execute AI-powered tasks using natural language descriptions.
+
+## Overview
+
+The Agent module allows you to execute complex tasks using human-readable instructions, monitor task status, and terminate running tasks. This capability extends the functionality of cloud sessions by adding AI-powered automation.
+
+## Running the Example
+
+1. Ensure you have the AgentBay SDK installed
+2. Set the `AGENTBAY_API_KEY` environment variable with your valid API key
+3. Run the example:
+
+```bash
+cd docs/examples/typescript
+npx ts-node agent-module-example.ts
+```
+
+## What the Example Does
+
+1. Initializes the AgentBay client with your API key
+2. Creates a new session
+3. Executes a simple task using the Agent module ("Calculate the square root of 144")
+4. Displays the task results
+5. Cleans up by deleting the session
+
+## Key Concepts
+
+- **Session Creation**: All Agent operations happen within a session context
+- **Task Execution**: Tasks are executed using natural language descriptions
+- **Result Handling**: Task results include success status, output, and error information
+- **Resource Management**: Sessions should be properly deleted when no longer needed
+
+## Next Steps
+
+Try modifying the task description to perform different operations, such as:
+- "Find the current weather in New York City"
+- "Calculate the factorial of 10"
+- "List the prime numbers between 1 and 100"

package/docs/examples/common-features/advanced/agent-module-example.ts

@@ -0,0 +1,66 @@
+/**
+ * Basic example of using the Agent module to execute tasks.
+ * This example demonstrates:
+ * - Creating a session with Agent capabilities
+ * - Executing a simple task using natural language
+ * - Handling task results
+ */
+
+import { AgentBay } from 'wuying-agentbay-sdk';
+
+async function main() {
+  // Get API key from environment variable
+  const apiKey = process.env.AGENTBAY_API_KEY;
+  if (!apiKey) {
+    console.log("Error: AGENTBAY_API_KEY environment variable not set");
+    return;
+  }
+
+  // Initialize AgentBay client
+  console.log("Initializing AgentBay client...");
+  const agentBay = new AgentBay({ apiKey });
+
+  try {
+    // Create a session with Windows latest image for Agent capabilities
+    console.log("Creating a new session with Windows latest image...");
+    const sessionResult = await agentBay.create({ imageId: "windows_latest" });
+
+    if (sessionResult.success) {
+      const session = sessionResult.session;
+      console.log(`Session created with ID: ${session.sessionId}`);
+
+      // Execute a task using the Agent
+      const taskDescription = "Calculate the square root of 144";
+      console.log(`Executing task: ${taskDescription}`);
+      
+      const executionResult = await session.agent.executeTask(taskDescription, 5);
+      
+      if (executionResult.success) {
+        console.log("Task completed successfully!");
+        console.log(`Task ID: ${executionResult.taskId}`);
+        console.log(`Task status: ${executionResult.taskStatus}`);
+      } else {
+        console.log(`Task failed: ${executionResult.errorMessage}`);
+        if (executionResult.taskId) {
+          console.log(`Task ID: ${executionResult.taskId}`);
+        }
+      }
+
+      // Clean up - delete the session
+      const deleteResult = await agentBay.delete(session);
+      if (deleteResult.success) {
+        console.log("Session deleted successfully");
+      } else {
+        console.log(`Failed to delete session: ${deleteResult.errorMessage}`);
+      }
+    } else {
+      console.log(`Failed to create session: ${sessionResult.errorMessage}`);
+    }
+  } catch (error) {
+    console.error("Error in main function:", error);
+  }
+}
+
+if (require.main === module) {
+  main().catch(console.error);
+}

package/docs/examples/common-features/advanced/archive-upload-mode-example/README.md

@@ -0,0 +1,212 @@
+# Archive Upload Mode Context Sync Example
+
+This directory contains examples demonstrating the Archive upload mode functionality for context synchronization in the AgentBay SDK.
+
+## Overview
+
+The Archive upload mode is designed for efficient file transfer by compressing files before uploading them to the context storage. This is particularly useful when:
+
+- Working with large files
+- Dealing with many files
+- Optimizing bandwidth usage
+- Reducing upload time for compressible content
+
+## Files
+
+### `archive-upload-mode-example.ts`
+
+A comprehensive example that demonstrates:
+
+1. **Context Creation**: Creating a context for Archive upload mode
+2. **Sync Policy Configuration**: Setting up sync policy with Archive uploadMode
+3. **Session Management**: Creating and managing sessions with context sync
+4. **File Operations**: Writing files to the context path
+5. **Context Info**: Retrieving context status information
+6. **File Verification**: Verifying file information and properties
+7. **Cleanup**: Proper session cleanup and error handling
+
+## Key Features Demonstrated
+
+### Archive Upload Mode Configuration
+
+```typescript
+// Configure sync policy with Archive upload mode
+const syncPolicy = newSyncPolicy();
+syncPolicy.uploadPolicy!.uploadMode = "Archive"; // Set to Archive mode
+
+// Create context sync with Archive mode
+const contextSync = newContextSync(
+  contextId,
+  "/tmp/archive-mode-test",
+  syncPolicy
+);
+```
+
+### Session Creation with Context Sync
+
+```typescript
+const sessionParams: CreateSessionParams = {
+  labels: {
+    example: `archive-mode-${uniqueId}`,
+    type: "archive-upload-demo",
+    uploadMode: "Archive"
+  },
+  contextSync: [contextSync]
+};
+
+const sessionResult = await agentBay.create(sessionParams);
+```
+
+### File Operations
+
+```typescript
+const fileSystem = new FileSystem(session);
+
+// Write file to context path
+const writeResult = await fileSystem.writeFile(filePath, fileContent, "overwrite");
+
+// Get file information
+const fileInfoResult = await fileSystem.getFileInfo(filePath);
+```
+
+### Context Information Retrieval
+
+```typescript
+// Get context status information
+const infoResult = await session.context.info();
+
+// Display context status details
+infoResult.contextStatusData.forEach((status, index) => {
+  console.log(`Context ID: ${status.contextId}`);
+  console.log(`Path: ${status.path}`);
+  console.log(`Status: ${status.status}`);
+  console.log(`Task Type: ${status.taskType}`);
+});
+```
+
+## Running the Example
+
+### Prerequisites
+
+1. **Environment Setup**: Set your AgentBay API key
+   ```bash
+   export AGENTBAY_API_KEY="your-api-key-here"
+   ```
+
+2. **Dependencies**: Ensure you have the AgentBay SDK installed
+   ```bash
+   npm install
+   ```
+
+### Execution
+
+```bash
+# Navigate to the project root
+cd /path/to/wuying-agentbay-sdk
+
+# Run the example
+npx ts-node docs/example/archive-upload-mode-example.ts
+```
+
+### Expected Output
+
+The example will output detailed logs showing:
+
+```
+🚀 Archive Upload Mode Context Sync Example
+============================================================
+
+📦 Step 1: Creating context for Archive upload mode...
+✅ Context created successfully!
+   Context ID: ctx_xxxxx
+   Request ID: req_xxxxx
+
+⚙️  Step 2: Configuring sync policy with Archive upload mode...
+✅ Sync policy configured with uploadMode: Archive
+
+🔧 Step 3: Creating context sync configuration...
+✅ Context sync created:
+   Context ID: ctx_xxxxx
+   Path: /tmp/archive-mode-test
+   Upload Mode: Archive
+
+🏗️  Step 4: Creating session with Archive mode context sync...
+✅ Session created successfully!
+   Session ID: sess_xxxxx
+   Request ID: req_xxxxx
+   App Instance ID: app_xxxxx
+
+📝 Step 5: Creating test files in Archive mode context...
+📄 Creating file: /tmp/archive-mode-test/test-file-5kb.txt
+📊 File content size: 5120 bytes
+✅ File write successful!
+   Request ID: req_xxxxx
+
+📊 Step 6: Testing context info functionality...
+✅ Context info retrieved successfully!
+   Request ID: req_xxxxx
+   Context status data count: X
+
+📋 Context status details:
+   [0] Context ID: ctx_xxxxx
+       Path: /tmp/archive-mode-test
+       Status: Success
+       Task Type: upload
+
+🔍 Step 7: Verifying file information...
+✅ File info retrieved successfully!
+   Request ID: req_xxxxx
+📄 File details:
+   Size: 5120 bytes
+   Is Directory: false
+   Modified Time: 2025-10-22T09:52:00Z
+   Mode: 644
+
+🎉 Archive upload mode example completed successfully!
+✅ All operations completed without errors.
+
+🧹 Step 8: Cleaning up session...
+✅ Session deleted successfully!
+   Success: true
+   Request ID: req_xxxxx
+```
+
+## Related Documentation
+
+- [Context Sync Documentation](../../../../../../docs/guides/common-features/basics/data-persistence.md)
+- [Session Management Guide](../../../../../../docs/guides/common-features/basics/session-management.md)
+- [File Operations Guide](../../../../../../docs/guides/common-features/basics/file-operations.md)
+
+## Troubleshooting
+
+### Common Issues
+
+1. **API Key Not Set**
+   ```
+   Warning: AGENTBAY_API_KEY environment variable not set
+   ```
+   **Solution**: Set the environment variable or update the API key in the code
+
+2. **Context Creation Failed**
+   ```
+   Context creation failed: [error message]
+   ```
+   **Solution**: Check your API key and network connectivity
+
+3. **Session Creation Failed**
+   ```
+   Session creation failed: [error message]
+   ```
+   **Solution**: Verify context sync configuration and try again
+
+4. **File Operation Failed**
+   ```
+   File write failed: [error message]
+   ```
+   **Solution**: Check file path permissions and available disk space
+
+## Support
+
+For additional help:
+- [GitHub Issues](https://github.com/aliyun/wuying-agentbay-sdk/issues)
+- [Documentation Home](../../../../../../README.md)

package/docs/examples/common-features/advanced/archive-upload-mode-example/archive-upload-mode-example.ts

@@ -0,0 +1,213 @@
+import { AgentBay, CreateSessionParams, Session, newContextSync, newSyncPolicy, FileSystem } from "wuying-agentbay-sdk";
+
+/**
+ * Archive Upload Mode Context Sync Example
+ * 
+ * This example demonstrates how to use Archive upload mode for context synchronization.
+ * Archive mode compresses files before uploading, which is more efficient for large files
+ * or when dealing with many files.
+ * 
+ * Features demonstrated:
+ * - Creating context with Archive upload mode
+ * - Session creation with context sync
+ * - File operations in the context path
+ * - Context sync and info operations
+ * - Proper cleanup and error handling
+ */
+
+function getAPIKey(): string {
+  const apiKey = process.env.AGENTBAY_API_KEY;
+  if (!apiKey) {
+    console.warn("Warning: AGENTBAY_API_KEY environment variable not set. Using default key.");
+    return "your-api-key-here"; // Replace with your actual API key
+  }
+  return apiKey;
+}
+
+function generateUniqueId(): string {
+  const timestamp = Date.now() * 1000 + Math.floor(Math.random() * 1000);
+  const randomPart = Math.floor(Math.random() * 10000);
+  return `${timestamp}-${randomPart}`;
+}
+
+async function archiveUploadModeExample(): Promise<void> {
+  console.log("🚀 Archive Upload Mode Context Sync Example");
+  console.log("=" .repeat(60));
+
+  // Initialize AgentBay client
+  const agentBay = new AgentBay({ apiKey: getAPIKey() });
+  const uniqueId = generateUniqueId();
+  
+  let session: Session | null = null;
+
+  try {
+    // Step 1: Create context for Archive mode
+    console.log("\n📦 Step 1: Creating context for Archive upload mode...");
+    const contextName = `archive-mode-context-${uniqueId}`;
+    const contextResult = await agentBay.context.get(contextName, true);
+    
+    if (!contextResult.success) {
+      throw new Error(`Context creation failed: ${contextResult.errorMessage}`);
+    }
+    
+    console.log(`✅ Context created successfully!`);
+    console.log(`   Context ID: ${contextResult.contextId}`);
+    console.log(`   Request ID: ${contextResult.requestId}`);
+
+    // Step 2: Configure sync policy with Archive upload mode
+    console.log("\n⚙️  Step 2: Configuring sync policy with Archive upload mode...");
+    const syncPolicy = newSyncPolicy();
+    syncPolicy.uploadPolicy!.uploadMode = "Archive"; // Set to Archive mode
+    
+    console.log(`✅ Sync policy configured with uploadMode: ${syncPolicy.uploadPolicy!.uploadMode}`);
+
+    // Step 3: Create context sync configuration
+    console.log("\n🔧 Step 3: Creating context sync configuration...");
+    const contextSync = newContextSync(
+      contextResult.contextId,
+      "/tmp/archive-mode-test",
+      syncPolicy
+    );
+
+    console.log(`✅ Context sync created:`);
+    console.log(`   Context ID: ${contextSync.contextId}`);
+    console.log(`   Path: ${contextSync.path}`);
+    console.log(`   Upload Mode: ${contextSync.policy?.uploadPolicy?.uploadMode}`);
+
+    // Step 4: Create session with Archive mode context sync
+    console.log("\n🏗️  Step 4: Creating session with Archive mode context sync...");
+    const sessionParams: CreateSessionParams = {
+      labels: {
+        example: `archive-mode-${uniqueId}`,
+        type: "archive-upload-demo",
+        uploadMode: "Archive"
+      },
+      contextSync: [contextSync]
+    };
+
+    const sessionResult = await agentBay.create(sessionParams);
+    if (!sessionResult.success) {
+      throw new Error(`Session creation failed: ${sessionResult.errorMessage}`);
+    }
+
+    session = sessionResult.session!;
+    console.log(`✅ Session created successfully!`);
+    console.log(`   Session ID: ${session!.sessionId}`);
+    console.log(`   Request ID: ${sessionResult.requestId}`);
+
+    // Get session info to verify setup
+    const sessionInfo = await agentBay.getSession(session!.sessionId);
+    if (sessionInfo.success && sessionInfo.data) {
+      console.log(`   App Instance ID: ${sessionInfo.data.appInstanceId}`);
+    }
+
+    // Step 5: Create and write test files
+    console.log("\n📝 Step 5: Creating test files in Archive mode context...");
+    const fileSystem = new FileSystem(session!);
+    
+    // Generate 5KB test content
+    const contentSize = 5 * 1024; // 5KB
+    const baseContent = "Archive mode test successful! This is a test file created in the session path. ";
+    const repeatedContent = baseContent.repeat(Math.ceil(contentSize / baseContent.length));
+    const fileContent = repeatedContent.substring(0, contentSize);
+    
+    const filePath = "/tmp/archive-mode-test/test-file-5kb.txt";
+    
+    console.log(`📄 Creating file: ${filePath}`);
+    console.log(`📊 File content size: ${fileContent.length} bytes`);
+
+    const writeResult = await fileSystem.writeFile(filePath, fileContent, "overwrite");
+    
+    if (!writeResult.success) {
+      throw new Error(`File write failed: ${writeResult.errorMessage}`);
+    }
+
+    console.log(`✅ File write successful!`);
+    console.log(`   Request ID: ${writeResult.requestId}`);
+
+    // Step 6: Test context info functionality
+    console.log("\n📊 Step 6: Testing context info functionality...");
+    const infoResult = await session!.context.info();
+    
+    if (!infoResult.success) {
+      throw new Error(`Context info failed: ${infoResult.errorMessage}`);
+    }
+
+    console.log(`✅ Context info retrieved successfully!`);
+    console.log(`   Request ID: ${infoResult.requestId}`);
+    console.log(`   Context status data count: ${infoResult.contextStatusData.length}`);
+    
+    // Display context status details
+    if (infoResult.contextStatusData.length > 0) {
+      console.log("\n📋 Context status details:");
+      infoResult.contextStatusData.forEach((status, index) => {
+        console.log(`   [${index}] Context ID: ${status.contextId}`);
+        console.log(`       Path: ${status.path}`);
+        console.log(`       Status: ${status.status}`);
+        console.log(`       Task Type: ${status.taskType}`);
+        if (status.errorMessage) {
+          console.log(`       Error: ${status.errorMessage}`);
+        }
+      });
+    }
+
+    // Step 7: Verify file information
+    console.log("\n🔍 Step 7: Verifying file information...");
+    const fileInfoResult = await fileSystem.getFileInfo(filePath);
+    
+    if (!fileInfoResult.success) {
+      throw new Error(`Get file info failed: ${fileInfoResult.errorMessage}`);
+    }
+
+    console.log(`✅ File info retrieved successfully!`);
+    console.log(`   Request ID: ${fileInfoResult.requestId}`);
+    
+    if (fileInfoResult.fileInfo) {
+      console.log(`📄 File details:`);
+      console.log(`   Size: ${fileInfoResult.fileInfo.size} bytes`);
+      console.log(`   Is Directory: ${fileInfoResult.fileInfo.isDirectory}`);
+      console.log(`   Modified Time: ${fileInfoResult.fileInfo.modTime}`);
+      console.log(`   Mode: ${fileInfoResult.fileInfo.mode}`);
+    }
+
+    console.log("\n🎉 Archive upload mode example completed successfully!");
+    console.log("✅ All operations completed without errors.");
+
+  } catch (error) {
+    console.error("\n❌ Error occurred during example execution:");
+    console.error(error);
+  } finally {
+    // Step 8: Cleanup
+    if (session) {
+      console.log("\n🧹 Step 8: Cleaning up session...");
+      try {
+        const deleteResult = await agentBay.delete(session, true);
+        console.log(`✅ Session deleted successfully!`);
+        console.log(`   Success: ${deleteResult.success}`);
+        console.log(`   Request ID: ${deleteResult.requestId}`);
+      } catch (deleteError) {
+        console.error(`❌ Failed to delete session: ${deleteError}`);
+      }
+    }
+  }
+}
+
+// Main execution
+async function main(): Promise<void> {
+  try {
+    await archiveUploadModeExample();
+  } catch (error) {
+    console.error("❌ Example execution failed:", error);
+    process.exit(1);
+  }
+}
+
+// Run the example if this file is executed directly
+if (require.main === module) {
+  main().catch((error) => {
+    console.error("❌ Unhandled error:", error);
+    process.exit(1);
+  });
+}
+
+export { archiveUploadModeExample };

package/docs/examples/common-features/advanced/vpc-session-example/README.md

@@ -0,0 +1,47 @@
+# VPC Session Example
+
+This example demonstrates how to create and use VPC (Virtual Private Cloud) sessions with the AgentBay SDK.
+
+## Overview
+
+VPC sessions provide enhanced security and networking capabilities by running your cloud sessions within a private network environment. This example shows how to create a VPC session and use its available modules.
+
+## Running the Example
+
+1. Ensure you have the AgentBay SDK installed
+2. Set the `AGENTBAY_API_KEY` environment variable with your valid API key
+3. Run the example:
+
+```bash
+cd docs/examples/typescript
+npx ts-node vpc-session-example.ts
+```
+
+## What the Example Does
+
+1. Initializes the AgentBay client with your API key
+2. Creates a new VPC session with specific parameters
+3. Tests FileSystem operations by writing and reading a file
+4. Tests Command operations by executing system commands
+5. Cleans up by deleting the session
+
+## Key Concepts
+
+- **VPC Session Creation**: VPC sessions are created by setting the `isVpc` parameter to `true`
+- **Module Availability**: VPC sessions have limited module availability compared to standard sessions
+- **Resource Management**: VPC sessions should be properly deleted when no longer needed
+- **Security**: VPC sessions provide network isolation for sensitive operations
+
+## Available Modules in VPC Sessions
+
+1. **FileSystem**: File and directory operations
+2. **Command**: Command execution
+3. **System Tools**: Specialized system-level tools
+4. **Browser Tools**: Browser automation capabilities
+
+## Next Steps
+
+Try modifying the example to:
+- Use context synchronization with VPC sessions
+- Test different command executions
+- Implement error handling for unavailable modules

package/docs/examples/common-features/advanced/vpc-session-example.ts

@@ -0,0 +1,106 @@
+/**
+ * Basic example of creating and using a VPC session.
+ * This example demonstrates:
+ * - Creating a VPC session with specific parameters
+ * - Using FileSystem operations in a VPC session
+ * - Using Command execution in a VPC session
+ * - Proper session cleanup
+ */
+
+import { AgentBay, newCreateSessionParams } from 'wuying-agentbay-sdk';
+
+async function main() {
+  // Get API key from environment variable
+  const apiKey = process.env.AGENTBAY_API_KEY;
+  if (!apiKey) {
+    console.log("Error: AGENTBAY_API_KEY environment variable not set");
+    return;
+  }
+
+  // Initialize AgentBay client
+  console.log("Initializing AgentBay client...");
+  const agentBay = new AgentBay({ apiKey });
+
+  try {
+    // Create a VPC session
+    console.log("Creating a VPC session...");
+    const params = newCreateSessionParams()
+      .withImageId("linux_latest")
+      .withIsVpc(true)
+      .withLabels({
+        "test-type": "vpc-basic-example",
+        "purpose": "demonstration",
+        "timestamp": Math.floor(Date.now() / 1000).toString()
+      });
+
+    const sessionResult = await agentBay.create(params);
+
+    if (!sessionResult.success) {
+      console.log(`Failed to create VPC session: ${sessionResult.errorMessage}`);
+      return;
+    }
+
+    const session = sessionResult.session;
+    console.log(`VPC session created successfully with ID: ${session.sessionId}`);
+
+    try {
+      // Test FileSystem operations
+      console.log("\n--- Testing FileSystem operations ---");
+      const testFilePath = "/tmp/vpc_example_test.txt";
+      const testContent = `Hello from VPC session! Created at ${new Date().toISOString()}`;
+
+      // Write file
+      const writeResult = await session.fileSystem.writeFile(testFilePath, testContent);
+      if (writeResult.success) {
+        console.log("✓ File written successfully");
+      } else {
+        console.log(`⚠ File write failed: ${writeResult.errorMessage}`);
+      }
+
+      // Read file
+      const readResult = await session.fileSystem.readFile(testFilePath);
+      if (readResult.success) {
+        console.log(`✓ File read successfully. Content: ${readResult.content}`);
+      } else {
+        console.log(`⚠ File read failed: ${readResult.errorMessage}`);
+      }
+
+      // Test Command operations
+      console.log("\n--- Testing Command operations ---");
+
+      // Get current user
+      const cmdResult = await session.command.executeCommand("whoami");
+      if (cmdResult.success) {
+        console.log(`✓ Current user: ${cmdResult.output.trim()}`);
+      } else {
+        console.log(`⚠ Command execution failed: ${cmdResult.errorMessage}`);
+      }
+
+      // List directory contents
+      const lsResult = await session.command.executeCommand("ls -la /tmp");
+      if (lsResult.success) {
+        console.log("✓ Directory listing successful");
+        console.log(`  Output:\n${lsResult.output}`);
+      } else {
+        console.log(`⚠ Directory listing failed: ${lsResult.errorMessage}`);
+      }
+
+    } finally {
+      // Clean up - delete the session
+      console.log("\n--- Cleaning up ---");
+      const deleteResult = await agentBay.delete(session);
+      if (deleteResult.success) {
+        console.log("✓ VPC session deleted successfully");
+      } else {
+        console.log(`⚠ Failed to delete VPC session: ${deleteResult.errorMessage}`);
+      }
+    }
+
+  } catch (error) {
+    console.error("Error in main function:", error);
+  }
+}
+
+if (require.main === module) {
+  main().catch(console.error);
+}