wuying-agentbay-sdk 0.10.2 → 0.11.0

package/docs/api/codespace/code.md

@@ -0,0 +1,77 @@
+# Class: Code
+
+## 💻 Related Tutorial
+
+- [Code Execution Guide](../../../../docs/guides/codespace/code-execution.md) - Execute code in isolated environments
+
+## Overview
+
+The Code module provides secure code execution capabilities in isolated environments.
+It supports multiple programming languages including Python, JavaScript, and more.
+
+
+## Requirements
+
+- Requires `code_latest` image for code execution features
+
+Handles code execution operations in the AgentBay cloud environment.
+
+## Table of contents
+
+
+### Methods
+
+- [runCode](#runcode)
+
+## Methods
+
+### runCode
+
+▸ **runCode**(`code`, `language`, `timeoutS?`): `Promise`\<`CodeExecutionResult`\>
+
+Execute code in the specified language with a timeout.
+Corresponds to Python's run_code() method
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `code` | `string` | `undefined` | The code to execute. |
+| `language` | `string` | `undefined` | The programming language of the code. Must be either 'python' or 'javascript'. |
+| `timeoutS` | `number` | `60` | The timeout for the code execution in seconds. Default is 60s. Note: Due to gateway limitations, each request cannot exceed 60 seconds. |
+
+#### Returns
+
+`Promise`\<`CodeExecutionResult`\>
+
+CodeExecutionResult with code execution output and requestId
+
+**`Throws`**
+
+Error if an unsupported language is specified.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create({ imageId: "code_latest" });
+if (result.success) {
+  const codeResult = await result.session.code.runCode('print("Hello")', "python");
+  console.log(codeResult.result);
+  await result.session.delete();
+}
+```
+
+## Best Practices
+
+1. Validate code syntax before execution
+2. Set appropriate execution timeouts
+3. Handle execution errors and exceptions
+4. Use proper resource limits to prevent resource exhaustion
+5. Clean up temporary files after code execution
+
+
+## Related Resources
+
+- [Session API Reference](../common-features/basics/session.md)
+

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

@@ -0,0 +1,84 @@
+# Class: Agent
+
+## 🤖 Related Tutorial
+
+- [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.
+
+## 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.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.executeTask('Open notepad', 5);
+  const terminateResult = await result.session.agent.terminateTask(taskResult.taskId);
+  console.log(`Terminated: ${terminateResult.taskStatus}`);
+  await result.session.delete();
+}
+```
+
+## Related Resources
+
+- [Session API Reference](../../common-features/basics/session.md)
+

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

@@ -0,0 +1,221 @@
+# Class: Oss
+
+## ☁️ Related Tutorial
+
+- [OSS Integration Guide](../../../../../docs/guides/common-features/advanced/oss-integration.md) - Integrate with Alibaba Cloud OSS for file storage
+
+Handles OSS operations in the AgentBay cloud environment.
+
+## Table of contents
+
+
+### Methods
+
+- [download](#download)
+- [downloadAnonymous](#downloadanonymous)
+- [envInit](#envinit)
+- [upload](#upload)
+- [uploadAnonymous](#uploadanonymous)
+
+## Methods
+
+### download
+
+▸ **download**(`bucket`, `object`, `path`): `Promise`\<`OSSDownloadResult`\>
+
+Download a file from OSS.
+Corresponds to Python's download() method
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `bucket` | `string` | The OSS bucket name |
+| `object` | `string` | The OSS object key |
+| `path` | `string` | The local file path to save the downloaded file |
+
+#### Returns
+
+`Promise`\<`OSSDownloadResult`\>
+
+OSSDownloadResult with download result and requestId
+
+**`Throws`**
+
+APIError if the operation fails.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const createResult = await agentBay.create();
+if (createResult.success) {
+  await createResult.session.oss.envInit('key_id', 'key_secret', 'token', 'oss-cn-hangzhou.aliyuncs.com', 'cn-hangzhou');
+  const result = await createResult.session.oss.download('my-bucket', 'my-folder/file.txt', '/path/to/save/file.txt');
+  console.log('Download success:', result.success);
+  await createResult.session.delete();
+}
+```
+
+___
+
+### downloadAnonymous
+
+▸ **downloadAnonymous**(`url`, `path`): `Promise`\<`OSSDownloadResult`\>
+
+Download a file from OSS using an anonymous URL.
+Corresponds to Python's download_anonymous() method
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `url` | `string` | The anonymous download URL |
+| `path` | `string` | The local file path to save the downloaded file |
+
+#### Returns
+
+`Promise`\<`OSSDownloadResult`\>
+
+OSSDownloadResult with download result and requestId
+
+**`Throws`**
+
+APIError if the operation fails.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const createResult = await agentBay.create();
+if (createResult.success) {
+  const result = await createResult.session.oss.downloadAnonymous('https://example.com/file.txt', '/path/to/save/file.txt');
+  console.log('Anonymous download success:', result.success);
+  await createResult.session.delete();
+}
+```
+
+___
+
+### envInit
+
+▸ **envInit**(`accessKeyId`, `accessKeySecret`, `securityToken`, `endpoint?`, `region?`): `Promise`\<`OSSClientResult`\>
+
+Initialize OSS environment variables with the specified STS temporary credentials.
+Corresponds to Python's env_init() method
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `accessKeyId` | `string` | The access key ID from STS temporary credentials |
+| `accessKeySecret` | `string` | The access key secret from STS temporary credentials |
+| `securityToken` | `string` | The security token from STS temporary credentials (required) |
+| `endpoint?` | `string` | The OSS endpoint (optional) |
+| `region?` | `string` | The OSS region (optional) |
+
+#### Returns
+
+`Promise`\<`OSSClientResult`\>
+
+OSSClientResult with client configuration and requestId
+
+**`Throws`**
+
+APIError if the operation fails.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const createResult = await agentBay.create();
+if (createResult.success) {
+  const result = await createResult.session.oss.envInit('sts_key_id', 'sts_key_secret', 'sts_token', 'oss-cn-hangzhou.aliyuncs.com', 'cn-hangzhou');
+  console.log('OSS initialized:', result.success);
+  await createResult.session.delete();
+}
+```
+
+___
+
+### upload
+
+▸ **upload**(`bucket`, `object`, `path`): `Promise`\<`OSSUploadResult`\>
+
+Upload a file to OSS.
+Corresponds to Python's upload() method
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `bucket` | `string` | The OSS bucket name |
+| `object` | `string` | The OSS object key |
+| `path` | `string` | The local file path to upload |
+
+#### Returns
+
+`Promise`\<`OSSUploadResult`\>
+
+OSSUploadResult with upload result and requestId
+
+**`Throws`**
+
+APIError if the operation fails.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const createResult = await agentBay.create();
+if (createResult.success) {
+  await createResult.session.oss.envInit('key_id', 'key_secret', 'token', 'oss-cn-hangzhou.aliyuncs.com', 'cn-hangzhou');
+  const result = await createResult.session.oss.upload('my-bucket', 'my-folder/file.txt', '/path/to/local/file.txt');
+  console.log('Upload success:', result.success);
+  await createResult.session.delete();
+}
+```
+
+___
+
+### uploadAnonymous
+
+▸ **uploadAnonymous**(`url`, `path`): `Promise`\<`OSSUploadResult`\>
+
+Upload a file to OSS using an anonymous URL.
+Corresponds to Python's upload_anonymous() method
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `url` | `string` | The anonymous upload URL |
+| `path` | `string` | The local file path to upload |
+
+#### Returns
+
+`Promise`\<`OSSUploadResult`\>
+
+OSSUploadResult with upload result and requestId
+
+**`Throws`**
+
+APIError if the operation fails.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const createResult = await agentBay.create();
+if (createResult.success) {
+  const result = await createResult.session.oss.uploadAnonymous('https://example.com/upload', '/path/to/local/file.txt');
+  console.log('Anonymous upload success:', result.success);
+  await createResult.session.delete();
+}
+```
+
+## Related Resources
+
+- [Session API Reference](../../common-features/basics/session.md)
+- [FileSystem API Reference](../../common-features/basics/filesystem.md)
+

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

@@ -0,0 +1,181 @@
+# Class: AgentBay
+
+## 🚀 Related Tutorial
+
+- [First Session Tutorial](../../../../../docs/quickstart/first-session.md) - Get started with creating your first AgentBay session
+
+Main class for interacting with the AgentBay cloud runtime environment.
+
+## Table of contents
+
+
+### Properties
+
+
+### Methods
+
+- [create](#create)
+- [delete](#delete)
+- [get](#get)
+- [list](#list)
+
+## Properties
+
+```typescript
+context: [`ContextService`](context.md)
+```
+
+
+## Methods
+
+### create
+
+▸ **create**(`params?`): `Promise`\<`SessionResult`\>
+
+Creates a new AgentBay session with specified configuration.
+
+#### Parameters
+
+| 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 |
+
+#### Returns
+
+`Promise`\<`SessionResult`\>
+
+Promise resolving to SessionResult containing:
+         - success: Whether session creation succeeded
+         - session: Session object for interacting with the environment
+         - requestId: Unique identifier for this API request
+         - errorMessage: Error description if creation failed
+
+**`Throws`**
+
+Error if API call fails or authentication is invalid.
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create({ labels: { project: 'demo' } });
+if (result.success) {
+  await result.session.filesystem.readFile('/etc/hostname');
+  await result.session.delete();
+}
+```
+
+**`Remarks`**
+
+**Behavior:**
+- Creates a new isolated cloud runtime environment
+- Automatically creates file transfer context if not provided
+- Waits for context synchronization if contextSync is specified
+- For VPC sessions, includes VPC-specific configuration
+- Browser replay creates a separate recording context
+
+**`See`**
+
+[get](#get), [list](#list), [Session.delete](session.md#delete)
+
+___
+
+### delete
+
+▸ **delete**(`session`, `syncContext?`): `Promise`\<``DeleteResult``\>
+
+Delete a session by session object.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `session` | [`Session`](session.md) | `undefined` | The session to delete. |
+| `syncContext` | `boolean` | `false` | Whether to sync context data (trigger file uploads) before deleting the session. Defaults to false. |
+
+#### Returns
+
+`Promise`\<``DeleteResult``\>
+
+DeleteResult indicating success or failure and request ID
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const result = await agentBay.create();
+if (result.success) {
+  await agentBay.delete(result.session);
+}
+```
+
+___
+
+### get
+
+▸ **get**(`sessionId`): `Promise`\<`SessionResult`\>
+
+Get a session by its ID.
+
+This method retrieves a session by calling the GetSession API
+and returns a SessionResult containing the Session object and request ID.
+
+#### Parameters
+
+| Name | Type | Description |
+| :------ | :------ | :------ |
+| `sessionId` | `string` | The ID of the session to retrieve |
+
+#### Returns
+
+`Promise`\<`SessionResult`\>
+
+Promise resolving to SessionResult with the Session instance, request ID, and success status
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: 'your_api_key' });
+const createResult = await agentBay.create();
+if (createResult.success) {
+  const result = await agentBay.get(createResult.session.sessionId);
+  await result.session?.filesystem.readFile('/etc/hostname');
+  await result.session?.delete();
+}
+```
+
+### list
+
+▸ **list**(`labels?`, `page?`, `limit?`): `Promise`\<``SessionListResult``\>
+
+Returns paginated list of session IDs filtered by labels.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `labels` | `Record`\<`string`, `string`\> | `{}` | Optional labels to filter sessions (defaults to empty object) |
+| `page?` | `number` | `undefined` | Optional page number for pagination (starting from 1, defaults to 1) |
+| `limit` | `number` | `10` | Optional maximum number of items per page (defaults to 10) |
+
+#### Returns
+
+`Promise`\<``SessionListResult``\>
+
+SessionListResult - Paginated list of session IDs that match the labels
+
+**`Example`**
+
+```typescript
+const agentBay = new AgentBay({ apiKey: "your_api_key" });
+const result = await agentBay.list({ project: "demo" }, 1, 10);
+if (result.success) {
+  console.log(`Found ${result.sessionIds.length} sessions`);
+}
+```
+
+## Related Resources
+
+- [Session API Reference](session.md)
+- [Context API Reference](context.md)
+

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

@@ -0,0 +1,83 @@
+# Class: Command
+
+## ⚡ Related Tutorial
+
+- [Command Execution Guide](../../../../../docs/guides/common-features/basics/command-execution.md) - Learn how to execute commands in sessions
+
+## 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.
+
+Handles command execution operations in the AgentBay cloud environment.
+
+## Table of contents
+
+
+### Methods
+
+- [executeCommand](#executecommand)
+
+## Methods
+
+### executeCommand
+
+▸ **executeCommand**(`command`, `timeoutMs?`): `Promise`\<`CommandResult`\>
+
+Executes a shell command in the session environment.
+
+#### Parameters
+
+| Name | Type | Default value | Description |
+| :------ | :------ | :------ | :------ |
+| `command` | `string` | `undefined` | The shell command to execute. |
+| `timeoutMs` | `number` | `1000` | Timeout in milliseconds. Defaults to 1000ms. |
+
+#### Returns
+
+`Promise`\<`CommandResult`\>
+
+Promise resolving to CommandResult containing:
+         - success: Whether the command executed successfully
+         - output: Combined stdout and stderr output
+         - requestId: Unique identifier for this API request
+         - errorMessage: Error description if execution failed
+
+**`Example`**
+
+```typescript
+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);
+  console.log('Command output:', cmdResult.output);
+  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`**
+
+[FileSystem.readFile](filesystem.md#readfile), [FileSystem.writeFile](filesystem.md#writefile)
+
+## Best Practices
+
+1. Always specify appropriate timeout values based on expected command duration
+2. Handle command execution errors gracefully
+3. Use absolute paths when referencing files in commands
+4. Be aware that commands run with session user permissions
+5. Clean up temporary files created by commands
+
+
+## Related Resources
+
+- [Session API Reference](session.md)
+- [FileSystem API Reference](filesystem.md)
+