wuying-agentbay-sdk 0.10.2 → 0.12.0

package/docs/examples/common-features/basics/mcp_tool_direct_call/README.md

@@ -0,0 +1,142 @@
+# MCP Tool Direct Call Example (TypeScript)
+
+This example demonstrates how to list available MCP tools and call them directly using the AgentBay TypeScript SDK.
+
+## Prerequisites
+
+- Node.js 16 or higher
+- AgentBay TypeScript SDK installed (`npm install wuying-agentbay-sdk`)
+- AgentBay API Key (set as environment variable `AGENTBAY_API_KEY`)
+
+## Running the Example
+
+```bash
+# Set your API key
+export AGENTBAY_API_KEY=your_api_key_here
+
+# Run the example
+cd typescript/docs/examples/common-features/advanced/mcp_tool_direct_call
+npx ts-node main.ts
+```
+
+## What This Example Does
+
+1. **Creates a Session**: Initializes an AgentBay session
+2. **Lists MCP Tools**: Retrieves all available MCP tools using `session.listMcpTools()`
+3. **Finds Shell Tool**: Locates the 'shell' tool and displays its details
+4. **Calls Shell Tool**: Executes commands using `session.callMcpTool()`:
+   - Echo command: `echo 'Hello from MCP Tool!'`
+   - Directory command: `pwd`
+   - Error handling: Invalid command demonstration
+5. **Cleanup**: Properly deletes the session
+
+## Expected Output
+
+```
+Initializing AgentBay client...
+
+1. Creating session...
+✓ Session created successfully
+  Session ID: sess-xxxxx
+  Request ID: req-xxxxx
+
+2. Listing available MCP tools...
+✓ Found 69 MCP tools
+  Request ID: req-xxxxx
+
+  Available tools (showing first 10):
+  1. get_resource
+     Description: The command to retrieve a wuying mcp runtime URL...
+     Server: mcp-server
+
+  2. system_screenshot
+     Description: Captures a full-screen screenshot...
+     Server: mcp-server
+
+  ...
+
+3. Finding 'shell' tool details...
+✓ Found 'shell' tool
+  Description: Executes an shell command with timeout...
+  Server: wuying_shell
+  Input Schema:
+    {
+      "type": "object",
+      "required": ["command", "timeout_ms"],
+      "properties": {
+        "command": {
+          "type": "string",
+          "description": "client input command"
+        },
+        "timeout_ms": {
+          "type": "integer",
+          "default": 1000,
+          "description": "Command execution timeout (unit: milliseconds)..."
+        }
+      }
+    }
+
+4. Calling 'shell' tool...
+✓ Tool call successful
+  Request ID: req-xxxxx
+  Output:
+    Hello from MCP Tool!
+
+5. Calling 'shell' tool with different command...
+✓ Tool call successful
+  Request ID: req-xxxxx
+  Current directory:
+    /home/wuying
+
+6. Demonstrating error handling (invalid command)...
+✓ Error handled correctly
+  Request ID: req-xxxxx
+  Error message: Execution failed. Error code:127 Error message: sh: 1: this_command_does_not_exist_12345: not found
+
+7. Cleaning up...
+✓ Session deleted successfully
+  Request ID: req-xxxxx
+
+============================================================
+Example completed successfully!
+============================================================
+```
+
+## Key API Methods
+
+### `session.listMcpTools()`
+
+Lists all available MCP tools for the session.
+
+**Returns:** `Promise<McpToolsResult>` containing:
+- `tools`: Array of `McpTool` objects
+- `requestId`: API request identifier
+
+### `session.callMcpTool(toolName, args)`
+
+Calls an MCP tool directly.
+
+**Parameters:**
+- `toolName` (string): Name of the MCP tool
+- `args` (Record<string, any>): Tool arguments
+
+**Returns:** `Promise<McpToolResult>` containing:
+- `success` (boolean): Whether the call succeeded
+- `data` (string): Tool output
+- `errorMessage` (string): Error message if failed
+- `requestId` (string): API request identifier
+
+## Use Cases
+
+This direct MCP tool calling approach is useful when you need to:
+
+1. **Discover Available Tools**: List all tools before deciding which to use
+2. **Call Tools Directly**: Bypass module-specific wrappers for direct access
+3. **Custom Tool Integration**: Build custom workflows with any available tool
+4. **Tool Exploration**: Inspect tool schemas and test different arguments
+
+## Related Documentation
+
+- [Session API Reference](../../../../api/common-features/basics/session.md#callmcptool)
+- [Common Features Guide](../../../../../../docs/guides/common-features/README.md)
+

package/docs/examples/common-features/basics/mcp_tool_direct_call/main.ts

@@ -0,0 +1,135 @@
+/**
+ * Example: List MCP Tools and Call a Tool
+ *
+ * This example demonstrates:
+ * 1. Creating a session
+ * 2. Listing all available MCP tools
+ * 3. Calling a specific tool (shell command)
+ * 4. Cleaning up the session
+ */
+
+import { AgentBay } from 'wuying-agentbay-sdk';
+
+async function main() {
+  // Initialize AgentBay client
+  console.log('Initializing AgentBay client...');
+  const agentBay = new AgentBay();
+
+  // Create a session
+  console.log('\n1. Creating session...');
+  const sessionResult = await agentBay.create();
+  const session = sessionResult.session;
+  console.log('✓ Session created successfully');
+  console.log(`  Session ID: ${session.getSessionId()}`);
+  console.log(`  Request ID: ${sessionResult.requestId}`);
+
+  try {
+    // List all available MCP tools
+    console.log('\n2. Listing available MCP tools...');
+    const toolsResult = await session.listMcpTools();
+    console.log(`✓ Found ${toolsResult.tools.length} MCP tools`);
+    console.log(`  Request ID: ${toolsResult.requestId}`);
+
+    // Display first 10 tools
+    console.log('\n  Available tools (showing first 10):');
+    for (let i = 0; i < Math.min(10, toolsResult.tools.length); i++) {
+      const tool = toolsResult.tools[i];
+      console.log(`  ${i + 1}. ${tool.name}`);
+      console.log(`     Description: ${tool.description}`);
+      console.log(`     Server: ${tool.server}`);
+      if (tool.inputSchema.required) {
+        console.log(`     Required params: ${tool.inputSchema.required.join(', ')}`);
+      }
+      console.log();
+    }
+
+    // Find and display the shell tool details
+    console.log("\n3. Finding 'shell' tool details...");
+    const shellTool = toolsResult.tools.find((tool: any) => tool.name === 'shell');
+
+    if (shellTool) {
+      console.log("✓ Found 'shell' tool");
+      console.log(`  Description: ${shellTool.description}`);
+      console.log(`  Server: ${shellTool.server}`);
+      console.log(`  Input Schema:`);
+      console.log(`    ${JSON.stringify(shellTool.inputSchema, null, 4)}`);
+    } else {
+      console.log("✗ 'shell' tool not found");
+      return;
+    }
+
+    // Call the shell tool
+    console.log("\n4. Calling 'shell' tool...");
+    const result = await session.callMcpTool('shell', {
+      command: "echo 'Hello from MCP Tool!'",
+      timeout_ms: 1000
+    });
+
+    if (result.success) {
+      console.log('✓ Tool call successful');
+      console.log(`  Request ID: ${result.requestId}`);
+      console.log(`  Output:`);
+      console.log(`    ${result.data}`);
+    } else {
+      console.log('✗ Tool call failed');
+      console.log(`  Error: ${result.errorMessage}`);
+      console.log(`  Request ID: ${result.requestId}`);
+    }
+
+    // Call another command to demonstrate flexibility
+    console.log("\n5. Calling 'shell' tool with different command...");
+    const result2 = await session.callMcpTool('shell', {
+      command: 'pwd',
+      timeout_ms: 1000
+    });
+
+    if (result2.success) {
+      console.log('✓ Tool call successful');
+      console.log(`  Request ID: ${result2.requestId}`);
+      console.log(`  Current directory:`);
+      console.log(`    ${result2.data}`);
+    } else {
+      console.log('✗ Tool call failed');
+      console.log(`  Error: ${result2.errorMessage}`);
+    }
+
+    // Demonstrate error handling
+    console.log('\n6. Demonstrating error handling (invalid command)...');
+    const result3 = await session.callMcpTool('shell', {
+      command: 'this_command_does_not_exist_12345',
+      timeout_ms: 1000
+    });
+
+    if (result3.success) {
+      console.log('✓ Command executed');
+      console.log(`  Output: ${result3.data}`);
+    } else {
+      console.log('✓ Error handled correctly');
+      console.log(`  Request ID: ${result3.requestId}`);
+      console.log(`  Error message: ${result3.errorMessage.substring(0, 100)}...`);
+    }
+
+  } finally {
+    // Clean up - delete the session
+    console.log('\n7. Cleaning up...');
+    const deleteResult = await agentBay.delete(session);
+    if (deleteResult.success) {
+      console.log('✓ Session deleted successfully');
+      console.log(`  Request ID: ${deleteResult.requestId}`);
+    } else {
+      console.log('✗ Failed to delete session');
+      console.log(`  Error: ${deleteResult.errorMessage}`);
+    }
+  }
+
+  console.log('\n' + '='.repeat(60));
+  console.log('Example completed successfully!');
+  console.log('='.repeat(60));
+}
+
+// Run the example
+main().catch((error) => {
+  console.error('Error running example:', error);
+  process.exit(1);
+});
+

package/docs/examples/common-features/basics/session-creation/README.md

@@ -0,0 +1,28 @@
+# Session Creation and Management Example
+
+This example demonstrates how to create, list, and delete sessions using the Wuying AgentBay SDK. It covers:
+
+- Initializing the AgentBay client
+- Creating a session with default parameters
+- Listing all available sessions
+- Creating multiple sessions
+- Deleting sessions
+- Verifying session deletion
+
+This example is useful for understanding the session lifecycle and how to manage multiple sessions.
+
+## Running the Example
+
+```bash
+cd session-creation
+npx ts-node session-creation.ts
+```
+
+Make sure you have set the `AGENTBAY_API_KEY` environment variable or replace the placeholder in the code with your actual API key.
+
+## Prerequisites
+
+- Node.js installed
+- TypeScript installed
+- ts-node installed (`npm install -g ts-node`)
+- Required dependencies installed (`npm install`)

package/docs/examples/common-features/basics/session-creation/session-creation.ts

@@ -0,0 +1,295 @@
+
+import { AgentBay, log, logError, CreateSessionParams, ContextSync, newSyncPolicy, ContextStatusData, newCreateSessionParams, MobileExtraConfig, AppManagerRule, ExtraConfigs } from 'wuying-agentbay-sdk'
+
+
+
+/**
+ * Create a session with default parameters
+ */
+async function createSessionWithDefaultParams() {
+  // Initialize the AgentBay client
+  const agent_bay = new AgentBay({ apiKey: process.env.AGENTBAY_API_KEY });
+
+  try {
+    // Create a session with default parameters
+    const result = await agent_bay.create();
+
+    if (result.success && result.session) {
+      log(`Session created successfully with ID: ${result.session.sessionId}`);
+      log(`Request ID: ${result.requestId}`);
+
+      // Clean up
+      const deleteResult = await agent_bay.delete(result.session);
+      if (deleteResult.success) {
+        log('Session deleted successfully');
+      } else {
+        log(`Failed to delete session: ${deleteResult.errorMessage}`);
+      }
+    } else {
+      log(`Failed to create session: ${result.errorMessage}`);
+    }
+  } catch (error) {
+    logError('Error:', error);
+  }
+}
+
+/**
+ * Create a session with labels
+ */
+async function createSessionWithLabels() {
+  // Initialize the AgentBay client
+  const agent_bay = new AgentBay({ apiKey: process.env.AGENTBAY_API_KEY });
+
+  try {
+    // Define labels
+    const labels = {
+      environment: 'development',
+      project: 'example',
+      owner: 'user123'
+    };
+
+    // Create session parameters with labels
+    const params: CreateSessionParams = {
+      labels
+    };
+
+    // Create a session with the parameters
+    const result = await agent_bay.create(params);
+
+    if (result.success && result.session) {
+      log(`Session with labels created successfully with ID: ${result.session.sessionId}`);
+      log(`Request ID: ${result.requestId}`);
+
+      // Verify the labels were set
+      const labelResult = await result.session.getLabels();
+      if (labelResult.success && labelResult.data) {
+        log('Retrieved labels:');
+        Object.entries(labelResult.data).forEach(([key, value]) => {
+          log(`  ${key}: ${value}`);
+        });
+      }
+
+      // Clean up
+      const deleteResult = await agent_bay.delete(result.session);
+      if (deleteResult.success) {
+        log('Session deleted successfully');
+      } else {
+        log(`Failed to delete session: ${deleteResult.errorMessage}`);
+      }
+    } else {
+      log(`Failed to create session with labels: ${result.errorMessage}`);
+    }
+  } catch (error) {
+    logError('Error:', error);
+  }
+}
+
+/**
+ * Create a session with persistent context
+ */
+async function createSessionWithContext() {
+  // Initialize the AgentBay client
+  const agent_bay = new AgentBay({ apiKey: process.env.AGENTBAY_API_KEY });
+
+  try {
+    // Create or get a persistent context
+    const contextResult = await agent_bay.context.get('example-context', true);
+
+    if (contextResult.success && contextResult.context) {
+      log(`Using context with ID: ${contextResult.context.id}`);
+
+      // Create a session linked to the context
+      const params = newCreateSessionParams()
+        .addContextSync(contextResult.context.id, "/home/wuying");
+
+      const sessionResult = await agent_bay.create(params);
+
+      if (sessionResult.success && sessionResult.session) {
+        log(`Session with context created successfully with ID: ${sessionResult.session.sessionId}`);
+        log(`Request ID: ${sessionResult.requestId}`);
+
+        // Clean up
+        const deleteResult = await agent_bay.delete(sessionResult.session);
+        if (deleteResult.success) {
+          log('Session deleted successfully');
+        } else {
+          log(`Failed to delete session: ${deleteResult.errorMessage}`);
+        }
+      } else {
+        log(`Failed to create session with context: ${sessionResult.errorMessage}`);
+      }
+    } else {
+      log(`Failed to get or create context: ${contextResult.errorMessage}`);
+    }
+  } catch (error) {
+    logError('Error:', error);
+  }
+}
+
+/**
+ * Create a session with context synchronization
+ */
+async function createSessionWithContextSync() {
+  // Initialize the AgentBay client
+  const agent_bay = new AgentBay({ apiKey: process.env.AGENTBAY_API_KEY });
+
+  try {
+    // Create or get a persistent context
+    const contextResult = await agent_bay.context.get('example-sync-context', true);
+
+    if (contextResult.success && contextResult.context) {
+      log(`Using context with ID: ${contextResult.context.id}`);
+
+      // Create a context sync configuration with default policy
+      const contextId = contextResult.context.id;
+      const path = '/mnt/persistent'
+      const policy = newSyncPolicy();
+      const contextSync = new ContextSync(contextId,path,policy);
+
+      // Create a session with context synchronization
+      const params: CreateSessionParams = {
+        contextSync: [contextSync]
+      };
+
+      const sessionResult = await agent_bay.create(params);
+
+      if (sessionResult.success && sessionResult.session) {
+        log(`Session with context sync created successfully with ID: ${sessionResult.session.sessionId}`);
+        log(`Request ID: ${sessionResult.requestId}`);
+
+        // List the synchronized contexts
+        // Wait for context to be synchronized
+        await new Promise(resolve => setTimeout(resolve, 2000));
+
+        const listResult = await sessionResult.session.context.info();
+        if (listResult.requestId && listResult.contextStatusData.length > 0) {
+          log(`Found ${listResult.contextStatusData.length} synchronized contexts:`);
+          listResult.contextStatusData.forEach((ctx:ContextStatusData) => {
+
+            log(`Context ID: ${ctx.contextId}, Path: ${ctx.path}, State: ${ctx.status}`);
+          });
+        }
+
+        // Clean up
+        const deleteResult = await agent_bay.delete(sessionResult.session);
+        if (deleteResult.success) {
+          log('Session deleted successfully');
+        } else {
+          log(`Failed to delete session: ${deleteResult.errorMessage}`);
+        }
+      } else {
+        log(`Failed to create session with context sync: ${sessionResult.errorMessage}`);
+      }
+    } else {
+      log(`Failed to get or create context: ${contextResult.errorMessage}`);
+    }
+  } catch (error) {
+    logError('Error:', error);
+  }
+}
+
+/**
+ * Create a mobile session with extra configurations
+ */
+async function createMobileSessionWithExtraConfigs() {
+  // Initialize the AgentBay client
+  const agent_bay = new AgentBay({ apiKey: process.env.AGENTBAY_API_KEY });
+
+  try {
+    // Create mobile configuration with app manager rule, resolution lock, navigation bar control, and uninstall protection
+    const appRule: AppManagerRule = {
+      ruleType: "White",
+      appPackageNameList: [
+        "com.android.settings",
+        "com.example.test.app",
+        "com.trusted.service",
+        "com.system.essential.service"
+      ]
+    };
+
+    const mobileConfig: MobileExtraConfig = {
+      lockResolution: true,  // Lock screen resolution for consistent testing
+      appManagerRule: appRule,
+      hideNavigationBar: true,  // Hide navigation bar for immersive experience
+      uninstallBlacklist: [  // Protect critical apps from uninstallation
+        "com.android.systemui",
+        "com.android.settings",
+        "com.google.android.gms"
+      ]
+    };
+
+    const extraConfigs: ExtraConfigs = {
+      mobile: mobileConfig
+    };
+
+    // Create session parameters with extra configurations
+    const params = newCreateSessionParams()
+      .withImageId("mobile_latest")
+      .withLabels({
+        project: "mobile-testing",
+        environment: "development",
+        config_type: "comprehensive"
+      })
+      .withExtraConfigs(extraConfigs);
+
+    // Create session
+    const result = await agent_bay.create(params);
+
+    if (result.success && result.session) {
+      log(`Mobile session with extra configs created with ID: ${result.session.sessionId}`);
+      log(`Request ID: ${result.requestId}`);
+      log('Extra configurations applied:');
+      log(`- Lock Resolution: ${mobileConfig.lockResolution}`);
+      log(`- Hide Navigation Bar: ${mobileConfig.hideNavigationBar}`);
+      log(`- App Manager Rule Type: ${appRule.ruleType}`);
+      log(`- Managed Apps: ${appRule.appPackageNameList.length}`);
+      appRule.appPackageNameList.forEach(pkg => {
+        log(`  - ${pkg}`);
+      });
+      log(`- Uninstall Protection: ${mobileConfig.uninstallBlacklist?.length} packages`);
+      mobileConfig.uninstallBlacklist?.forEach(pkg => {
+        log(`  - ${pkg}`);
+      });
+
+      // Clean up
+      const deleteResult = await agent_bay.delete(result.session);
+      if (deleteResult.success) {
+        log('Mobile session deleted successfully');
+      } else {
+        log(`Failed to delete mobile session: ${deleteResult.errorMessage}`);
+      }
+    } else {
+      log(`Failed to create mobile session: ${result.errorMessage}`);
+    }
+  } catch (error) {
+    logError('Error:', error);
+  }
+}
+
+/**
+ * Run all examples
+ */
+async function main() {
+  log('Session Creation Examples');
+  log('=========================');
+
+  log('\n1. Creating session with default parameters...');
+  await createSessionWithDefaultParams();
+
+  log('\n2. Creating session with labels...');
+  await createSessionWithLabels();
+
+  log('\n3. Creating session with context...');
+  await createSessionWithContext();
+
+  log('\n4. Creating session with context synchronization...');
+  await createSessionWithContextSync();
+
+  log('\n5. Creating mobile session with extra configurations...');
+  await createMobileSessionWithExtraConfigs();
+}
+
+main().catch(error => {
+  logError('Error in main:', error);
+  process.exit(1);
+});

package/docs/examples/common-features/basics/session-pause-resume/README.md

@@ -0,0 +1,53 @@
+# Session Pause and Resume Example
+
+This example demonstrates how to pause and resume sessions using the Wuying AgentBay SDK. Pausing a session puts it into a dormant state, consuming fewer resources while maintaining its state. Resuming a session brings it back to an active state.
+
+## Features Demonstrated
+
+- Pausing and resuming sessions
+- Handling non-existent session operations
+- Using custom timeout and polling interval parameters
+- Checking session status before and after operations
+- Performing work in sessions before and after pause/resume cycles
+
+## Running the Example
+
+```bash
+cd session-pause-resume
+npx ts-node session-pause-resume.ts
+```
+
+Make sure you have set the `AGENTBAY_API_KEY` environment variable or replace the placeholder in the code with your actual API key.
+
+## Prerequisites
+
+- Node.js installed
+- TypeScript installed
+- ts-node installed (`npm install -g ts-node`)
+- Required dependencies installed (`npm install`)
+
+## Understanding Session States
+
+When working with pause and resume operations, sessions can be in different states:
+
+1. **RUNNING**: Session is active and ready to accept commands
+2. **PAUSING**: Session is transitioning to paused state
+3. **PAUSED**: Session is in dormant state, consuming fewer resources
+4. **RESUMING**: Session is transitioning back to running state
+
+The pause and resume operations are asynchronous, meaning they initiate the state transition and then poll for completion.
+
+## Best Practices
+
+1. **Always check operation results**: Verify that pause and resume operations succeeded
+2. **Handle errors gracefully**: Non-existent sessions and other errors should be handled appropriately
+3. **Use appropriate timeouts**: Custom timeout values can be used based on your specific requirements
+4. **Verify session state**: Check session status before and after operations to ensure expected behavior
+5. **Clean up resources**: Always delete sessions when done to avoid resource leaks
+
+## Use Cases
+
+- **Cost optimization**: Pause sessions during idle periods to reduce resource consumption
+- **Long-running workflows**: Suspend sessions overnight or during maintenance windows
+- **Development and testing**: Pause test environments when not actively working on them
+- **Batch processing**: Pause and resume processing jobs based on system load