wuying-agentbay-sdk 0.11.0 → 0.13.0

package/docs/api/common-features/advanced/agent.md

@@ -5,77 +5,21 @@
 - [Agent Modules Guide](../../../../../docs/guides/common-features/advanced/agent-modules.md) - Learn about agent modules and custom agents
 
 An Agent to manipulate applications to complete specific tasks.
+According to the use scenary, The agent can a browser use agent which is
+specialized for browser automation tasks, The agent also can be  a computer
+use agent which is specialized for multiple applications automation tasks.
 
 ## Table of contents
 
 
-### Methods
+### Properties
 
-- [executeTask](#executetask)
-- [terminateTask](#terminatetask)
 
-## Methods
-
-### executeTask
-
-▸ **executeTask**(`task`, `maxTryTimes`): `Promise`\<``ExecutionResult``\>
-
-Execute a specific task described in human language.
-
-#### Parameters
-
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `task` | `string` | Task description in human language. |
-| `maxTryTimes` | `number` | Maximum number of retry attempts. |
-
-#### Returns
-
-`Promise`\<``ExecutionResult``\>
-
-ExecutionResult containing success status, task output, and error message if any.
-
-**`Example`**
-
-```typescript
-const agentBay = new AgentBay({ apiKey: 'your_api_key' });
-const result = await agentBay.create({ imageId: 'windows_latest' });
-if (result.success) {
-  const taskResult = await result.session.agent.executeTask('Open notepad', 10);
-  console.log(`Task status: ${taskResult.taskStatus}`);
-  await result.session.delete();
-}
-```
-
-### terminateTask
-
-▸ **terminateTask**(`taskId`): `Promise`\<``ExecutionResult``\>
-
-Terminate a task with a specified task ID.
-
-#### Parameters
-
-| Name | Type | Description |
-| :------ | :------ | :------ |
-| `taskId` | `string` | The ID of the running task. |
-
-#### Returns
-
-`Promise`\<``ExecutionResult``\>
-
-ExecutionResult containing success status, task output, and error message if any.
-
-**`Example`**
+## Properties
 
 ```typescript
-const agentBay = new AgentBay({ apiKey: 'your_api_key' });
-const result = await agentBay.create({ imageId: 'windows_latest' });
-if (result.success) {
-  const taskResult = await result.session.agent.executeTask('Open notepad', 5);
-  const terminateResult = await result.session.agent.terminateTask(taskResult.taskId);
-  console.log(`Terminated: ${terminateResult.taskStatus}`);
-  await result.session.delete();
-}
+browser: [`BrowserUseAgent`](browser-use-agent.md)
+computer: [`ComputerUseAgent`](computer-use-agent.md)
 ```
 
 ## Related Resources

package/docs/api/common-features/advanced/browser-use-agent.md

@@ -0,0 +1,118 @@
+# Class: BrowserUseAgent
+
+## Table of contents
+
+
+### Methods
+
+- [executeTask](#executetask)
+- [initialize](#initialize)
+- [terminateTask](#terminatetask)
+
+## Methods
+
+### executeTask
+
+▸ **executeTask**(`task`, `maxTryTimes`): `Promise`\<``ExecutionResult``\>
+
+Execute a specific task described in human language.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `task` | `string` | Task description in human language. |
+| `maxTryTimes` | `number` | Maximum number of retry attempts. |
+
+#### Returns
+
+`Promise`\<``ExecutionResult``\>
+
+ExecutionResult containing success status, task output, and
+    error message if any.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create({ imageId: 'linux_latest' });
+if (result.success) {
+  const taskResult = await result.session.agent.browser.executeTask(
+    'Navigate to baidu and query the weather of Shanghai',
+    10
+  );
+  console.log(`Task status: ${taskResult.taskStatus}`);
+  await result.session.delete();
+}
+```
+
+### initialize
+
+▸ **initialize**(`options`): `Promise`\<``InitializationResult``\>
+
+Initialize the browser agent with specific options.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `options` | ``AgentOptions`` | agent initialization options |
+
+#### Returns
+
+`Promise`\<``InitializationResult``\>
+
+InitializationResult containing success status, task output,
+    and error message if any.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create({ imageId: 'linux_latest' });
+if (result.success) {
+  options:AgentOptions = new AgentOptions(use_vision=False,
+output_schema=""); const initResult = await
+result.session.agent.browser.initialize(options); console.log(`Initialize
+success: ${initResult.success}`); await result.session.delete();
+}
+```
+
+___
+
+### terminateTask
+
+▸ **terminateTask**(`taskId`): `Promise`\<``ExecutionResult``\>
+
+Terminate a task with a specified task ID.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `taskId` | `string` | The ID of the running task. |
+
+#### Returns
+
+`Promise`\<``ExecutionResult``\>
+
+ExecutionResult containing success status, task output, and
+    error message if any.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create({ imageId: 'linux_latest' });
+if (result.success) {
+  const taskResult = await result.session.agent.browser.executeTask(
+    'Navigate to baidu and query the weather of Shanghai',
+    10
+  );
+  const terminateResult = await result.session.agent.browser.terminateTask(
+    taskResult.taskId
+  );
+  console.log(`Terminated: ${terminateResult.taskStatus}`);
+  await result.session.delete();
+}
+```

package/docs/api/common-features/advanced/computer-use-agent.md

@@ -0,0 +1,85 @@
+# Class: ComputerUseAgent
+
+An Agent to perform tasks on the computer.
+
+## Table of contents
+
+
+### Methods
+
+- [executeTask](#executetask)
+- [terminateTask](#terminatetask)
+
+## Methods
+
+### executeTask
+
+▸ **executeTask**(`task`, `maxTryTimes`): `Promise`\<``ExecutionResult``\>
+
+Execute a specific task described in human language.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `task` | `string` | Task description in human language. |
+| `maxTryTimes` | `number` | Maximum number of retry attempts. |
+
+#### Returns
+
+`Promise`\<``ExecutionResult``\>
+
+ExecutionResult containing success status, task output, and error
+    message if any.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create({ imageId: 'windows_latest' });
+if (result.success) {
+  const taskResult = await result.session.agent.computer.executeTask(
+    'Open notepad',
+    10
+  );
+  console.log(`Task status: ${taskResult.taskStatus}`);
+  await result.session.delete();
+}
+```
+
+### terminateTask
+
+▸ **terminateTask**(`taskId`): `Promise`\<``ExecutionResult``\>
+
+Terminate a task with a specified task ID.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `taskId` | `string` | The ID of the running task. |
+
+#### Returns
+
+`Promise`\<``ExecutionResult``\>
+
+ExecutionResult containing success status, task output, and
+    error message if any.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create({ imageId: 'windows_latest' });
+if (result.success) {
+  const taskResult = await result.session.agent.computer.executeTask(
+    'Open notepad',
+    5
+  );
+  const terminateResult = await result.session.agent.computer.terminateTask(
+    taskResult.taskId
+  );
+  console.log(`Terminated: ${terminateResult.taskStatus}`);
+  await result.session.delete();
+}
+```

package/docs/api/common-features/basics/agentbay.md

@@ -18,10 +18,13 @@ Main class for interacting with the AgentBay cloud runtime environment.
 - [delete](#delete)
 - [get](#get)
 - [list](#list)
+- [pauseAsync](#pauseasync)
+- [resumeAsync](#resumeasync)
 
 ## Properties
 
 ```typescript
+client: ``Client``
 context: [`ContextService`](context.md)
 ```
 
@@ -30,7 +33,7 @@ context: [`ContextService`](context.md)
 
 ### create
 
-▸ **create**(`params?`): `Promise`\<`SessionResult`\>
+▸ **create**(`params`): `Promise`\<`SessionResult`\>
 
 Creates a new AgentBay session with specified configuration.
 
@@ -38,7 +41,7 @@ Creates a new AgentBay session with specified configuration.
 
 | Name | Type | Description |
 | :------ | :------ | :------ |
-| `params` | ``CreateSessionParams`` | Configuration parameters for the session: - labels: Key-value pairs for session metadata - imageId: Custom image ID for the session environment - contextSync: Array of context synchronization configurations - browserContext: Browser-specific context configuration - isVpc: Whether to create a VPC session - policyId: Security policy ID - enableBrowserReplay: Enable browser session recording - extraConfigs: Additional configuration options - framework: Framework identifier for tracking |
+| `params` | [`CreateSessionParams`](session-params.md) \| `CreateSeesionWithParams` | Configuration parameters for the session: - labels: Key-value pairs for session metadata - imageId: Custom image ID for the session environment - contextSync: Array of context synchronization configurations - browserContext: Browser-specific context configuration - isVpc: Whether to create a VPC session - policyId: Security policy ID - enableBrowserReplay: Enable browser session recording - extraConfigs: Additional configuration options - framework: Framework identifier for tracking |
 
 #### Returns
 
@@ -174,6 +177,100 @@ if (result.success) {
 }
 ```
 
+___
+
+### pauseAsync
+
+▸ **pauseAsync**(`session`, `timeout?`, `pollInterval?`): `Promise`\<`SessionPauseResult`\>
+
+Asynchronously pause a session, putting it into a dormant state.
+
+This method directly calls the PauseSessionAsync API without waiting for the session
+to reach the PAUSED state.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `session` | [`Session`](session.md) | `undefined` | The session to pause. |
+| `timeout` | `number` | `600` | Timeout in seconds to wait for the session to pause. Defaults to 600 seconds. |
+| `pollInterval` | `number` | `2.0` | Interval in seconds between status polls. Defaults to 2.0 seconds. |
+
+#### Returns
+
+`Promise`\<`SessionPauseResult`\>
+
+SessionPauseResult indicating success or failure and request ID
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const session = (await agentBay.create()).session;
+const pauseResult = await agentBay.pauseAsync(session);
+await agentBay.resumeAsync(session);
+await session.delete();
+```
+
+**`Remarks`**
+
+**Behavior:**
+- This method does not wait for the session to reach the PAUSED state
+- It only submits the pause request to the API
+- The session state transitions from RUNNING -> PAUSING -> PAUSED
+- Paused sessions consume fewer resources but maintain their state
+
+**`See`**
+
+[resumeAsync](#resumeasync), [Session.pauseAsync](session.md#pauseasync)
+
+___
+
+### resumeAsync
+
+▸ **resumeAsync**(`session`, `timeout?`, `pollInterval?`): `Promise`\<`SessionResumeResult`\>
+
+Asynchronously resume a session from a paused state.
+
+This method directly calls the ResumeSessionAsync API without waiting for the session
+to reach the RUNNING state.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `session` | [`Session`](session.md) | `undefined` | The session to resume. |
+| `timeout` | `number` | `600` | Timeout in seconds to wait for the session to resume. Defaults to 600 seconds. |
+| `pollInterval` | `number` | `2.0` | Interval in seconds between status polls. Defaults to 2.0 seconds. |
+
+#### Returns
+
+`Promise`\<`SessionResumeResult`\>
+
+SessionResumeResult indicating success or failure and request ID
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const session = (await agentBay.create()).session;
+await agentBay.pauseAsync(session);
+const resumeResult = await agentBay.resumeAsync(session);
+await session.delete();
+```
+
+**`Remarks`**
+
+**Behavior:**
+- This method does not wait for the session to reach the RUNNING state
+- It only submits the resume request to the API
+- The session state transitions from PAUSED -> RESUMING -> RUNNING
+- Only sessions in PAUSED state can be resumed
+
+**`See`**
+
+[pauseAsync](#pauseasync), [Session.resumeAsync](session.md#resumeasync)
+
 ## Related Resources
 
 - [Session API Reference](session.md)

package/docs/api/common-features/basics/command.md

@@ -7,7 +7,7 @@
 ## Overview
 
 The Command module provides methods for executing shell commands within a session in the AgentBay cloud environment.
-It supports both synchronous command execution with configurable timeouts.
+Commands support configurable timeouts and optional working directory or environment settings.
 
 Handles command execution operations in the AgentBay cloud environment.
 
@@ -22,24 +22,34 @@ Handles command execution operations in the AgentBay cloud environment.
 
 ### executeCommand
 
-▸ **executeCommand**(`command`, `timeoutMs?`): `Promise`\<`CommandResult`\>
+▸ **executeCommand**(`command`, `timeoutMs?`, `cwd?`, `envs?`): `Promise`\<`CommandResult`\>
 
-Executes a shell command in the session environment.
+Execute a shell command with optional working directory and environment variables.
+
+Executes a shell command in the session environment with configurable timeout,
+working directory, and environment variables. The command runs with session
+user permissions in a Linux shell environment.
 
 #### Parameters
 
 | Name | Type | Default value | Description |
 | :------ | :------ | :------ | :------ |
-| `command` | `string` | `undefined` | The shell command to execute. |
-| `timeoutMs` | `number` | `1000` | Timeout in milliseconds. Defaults to 1000ms. |
+| `command` | `string` | `undefined` | The shell command to execute |
+| `timeoutMs` | `number` | `1000` | Timeout in milliseconds (default: 1000ms/1s). Maximum allowed timeout is 50000ms (50s). If a larger value is provided, it will be automatically limited to 50000ms |
+| `cwd?` | `string` | `undefined` | The working directory for command execution. If not specified, the command runs in the default session directory |
+| `envs?` | `Record`\<`string`, `string`\> | `undefined` | Environment variables as a dictionary of key-value pairs. These variables are set for the command execution only |
 
 #### Returns
 
 `Promise`\<`CommandResult`\>
 
 Promise resolving to CommandResult containing:
-         - success: Whether the command executed successfully
-         - output: Combined stdout and stderr output
+         - success: Whether the command executed successfully (exitCode === 0)
+         - output: Command output for backward compatibility (stdout + stderr)
+         - exitCode: The exit code of the command execution (0 for success)
+         - stdout: Standard output from the command execution
+         - stderr: Standard error from the command execution
+         - traceId: Trace ID for error tracking (only present when exitCode !== 0)
          - requestId: Unique identifier for this API request
          - errorMessage: Error description if execution failed
 
@@ -49,23 +59,30 @@ Promise resolving to CommandResult containing:
 const agentBay = new AgentBay({ apiKey: 'your_api_key' });
 const result = await agentBay.create();
 if (result.success) {
-  const cmdResult = await result.session.command.executeCommand('echo "Hello"', 3000);
+  const cmdResult = await result.session.command.executeCommand('echo "Hello"', 5000);
   console.log('Command output:', cmdResult.output);
+  console.log('Exit code:', cmdResult.exitCode);
+  console.log('Stdout:', cmdResult.stdout);
   await result.session.delete();
 }
 ```
 
-**`Remarks`**
-
-**Behavior:**
-- Executes in a Linux shell environment
-- Combines stdout and stderr in the output
-- Default timeout is 1000ms (1 second)
-- Command runs with session user permissions
-
-**`See`**
+**`Example`**
 
-[FileSystem.readFile](filesystem.md#readfile), [FileSystem.writeFile](filesystem.md#writefile)
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create();
+if (result.success) {
+  const cmdResult = await result.session.command.executeCommand(
+    'pwd',
+    5000,
+    '/tmp',
+    { TEST_VAR: 'test_value' }
+  );
+  console.log('Working directory:', cmdResult.stdout);
+  await result.session.delete();
+}
+```
 
 ## Best Practices
 

package/docs/api/common-features/basics/context-manager.md

@@ -93,8 +93,8 @@ Synchronizes a context with the session. Supports both async and callback modes.
 
 | Name | Type | Default value | Description |
 | :------ | :------ | :------ | :------ |
-| `contextId?` | `string` | `undefined` | Optional context ID to synchronize |
-| `path?` | `string` | `undefined` | Optional path where the context should be mounted |
+| `contextId?` | `string` | `undefined` | Optional context ID to synchronize. If provided, `path` must also be provided. |
+| `path?` | `string` | `undefined` | Optional path where the context should be mounted. If provided, `contextId` must also be provided. |
 | `mode?` | `string` | `undefined` | Optional synchronization mode (e.g., "upload", "download") |
 | `callback?` | ``SyncCallback`` | `undefined` | Optional callback function. If provided, runs in background and calls callback when complete |
 | `maxRetries` | `number` | `150` | Maximum number of retries for polling completion status (default: 150) |
@@ -110,8 +110,27 @@ Promise resolving to ContextSyncResult with success status and request ID
 
 Error if the API call fails
 
+**`Throws`**
+
+Error if `contextId` or `path` is provided without the other parameter.
+              Both must be provided together, or both must be omitted.
+
+**`Example`**
+
+Sync all contexts (no parameters):
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create();
+if (result.success) {
+  const syncResult = await result.session.context.sync();
+  console.log(`Sync: ${syncResult.success}`);
+  await result.session.delete();
+}
+```
+
 **`Example`**
 
+Sync specific context with path:
 ```typescript
 const agentBay = new AgentBay({ apiKey: 'your_api_key' });
 const result = await agentBay.create();

package/docs/api/common-features/basics/filesystem.md

@@ -12,6 +12,7 @@ Handles file operations in the AgentBay cloud environment.
 ### Methods
 
 - [createDirectory](#createdirectory)
+- [deleteFile](#deletefile)
 - [downloadFile](#downloadfile)
 - [editFile](#editfile)
 - [listDirectory](#listdirectory)
@@ -58,6 +59,41 @@ if (result.success) {
 
 ___
 
+### deleteFile
+
+▸ **deleteFile**(`path`): `Promise`\<`BoolResult`\>
+
+Deletes a file at the specified path.
+Corresponds to Python's delete_file() method
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `path` | `string` | Path to the file to delete. |
+
+#### Returns
+
+`Promise`\<`BoolResult`\>
+
+BoolResult with deletion result and requestId
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create();
+if (result.success) {
+  const session = result.session;
+  await session.fileSystem.writeFile('/tmp/to_delete.txt', 'hello');
+  const deleteResult = await session.fileSystem.deleteFile('/tmp/to_delete.txt');
+  console.log('File deleted:', deleteResult.success);
+  await session.delete();
+}
+```
+
+___
+
 ### downloadFile
 
 ▸ **downloadFile**(`remotePath`, `localPath`, `options?`): `Promise`\<`any`\>