test-wuying-agentbay-sdk/docs/api/common-features/basics/session.md

TypeScript SDK for interacting with the Wuying AgentBay cloud runtime environment

# Class: Session

## 🔧 Related Tutorial

- [Session Management Guide](../../../../../docs/guides/common-features/basics/session-management.md) - Detailed tutorial on session lifecycle and management

Represents a session in the AgentBay cloud environment.

## Table of contents


### Properties


### Methods

- [callMcpTool](#callmcptool)
- [delete](#delete)
- [getLabels](#getlabels)
- [getLink](#getlink)
- [getLinkAsync](#getlinkasync)
- [info](#info)
- [listMcpTools](#listmcptools)
- [pauseAsync](#pauseasync)
- [resumeAsync](#resumeasync)
- [setLabels](#setlabels)

## Properties

```typescript
agent: [`Agent`](../advanced/agent.md)
browser: [`Browser`](../../browser-use/browser.md)
code: [`Code`](../../codespace/code.md)
command: [`Command`](command.md)
computer: [`Computer`](../../computer-use/computer.md)
context: [`ContextManager`](context-manager.md)
enableBrowserReplay: `boolean` = `false`
fileSystem: [`FileSystem`](filesystem.md)
fileTransferContextId: ``null`` | `string` = `null`
httpPort: `string` = `""`
isVpc: `boolean` = `false`
mcpTools: `McpTool`[] = `[]`
mobile: [`Mobile`](../../mobile-use/mobile.md)
networkInterfaceIp: `string` = `""`
oss: [`Oss`](../advanced/oss.md)
recordContextId: ``null`` | `string` = `null`
resourceUrl: `string` = `""`
sessionId: `string`
token: `string` = `""`
```


## Methods

### callMcpTool

▸ **callMcpTool**(`toolName`, `args`, `autoGenSession?`): `Promise`\<``McpToolResult``\>

Call an MCP tool and return the result in a format compatible with Agent.

#### Parameters

| Name | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| `toolName` | `string` | `undefined` | Name of the MCP tool to call |
| `args` | `any` | `undefined` | Arguments to pass to the tool |
| `autoGenSession` | `boolean` | `false` | Whether to automatically generate session if not exists (default: false) |

#### Returns

`Promise`\<``McpToolResult``\>

McpToolResult containing the response data

**`Example`**

```typescript
const agentBay = new AgentBay({ apiKey: 'your_api_key' });
const result = await agentBay.create();
if (result.success) {
  const shellResult = await result.session.callMcpTool('shell', { command: "echo 'Hello'" });
  console.log(`Output: ${shellResult.data}`);
  await result.session.delete();
}
```

**`Remarks`**

For press_keys tool, key names are automatically normalized to correct case format.
This improves case compatibility (e.g., "CTRL" -> "Ctrl", "tab" -> "Tab").

___

### delete

▸ **delete**(`syncContext?`): `Promise`\<``DeleteResult``\>

Deletes the session and releases all associated resources.

#### Parameters

| Name | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| `syncContext` | `boolean` | `false` | Whether to synchronize context data before deletion. If true, uploads all context data to OSS. If false but browser replay is enabled, syncs only the recording context. Defaults to false. |

#### Returns

`Promise`\<``DeleteResult``\>

Promise resolving to DeleteResult containing:
         - success: Whether deletion succeeded
         - requestId: Unique identifier for this API request
         - errorMessage: Error description if deletion failed

**`Throws`**

Error if the API call fails or network issues occur.

**`Example`**

```typescript
const agentBay = new AgentBay({ apiKey: 'your_api_key' });
const result = await agentBay.create();
if (result.success) {
  await result.session.fileSystem.writeFile('/tmp/data.txt', 'data');
  const deleteResult = await result.session.delete(true);
  console.log('Session deleted:', deleteResult.success);
}
```

**`Remarks`**

**Behavior:**
- If `syncContext=true`: Uploads all context data to OSS before deletion
- If `syncContext=false` but browser replay enabled: Syncs only recording context
- If `syncContext=false` and no browser replay: Deletes immediately without sync
- Continues with deletion even if context sync fails
- Releases all associated resources (browser, computer, mobile, etc.)

**Best Practices:**
- Use `syncContext=true` when you need to preserve context data for later retrieval
- For temporary sessions, use `syncContext=false` for faster cleanup
- Always call `delete()` when done to avoid resource leaks
- Handle deletion errors gracefully in production code

**`See`**

[info](#info), [ContextManager.sync](context-manager.md#sync)

___

### getLabels

▸ **getLabels**(): `Promise`\<`OperationResult`\>

Gets the labels for this session.

#### Returns

`Promise`\<`OperationResult`\>

OperationResult containing the labels as data and request ID

**`Throws`**

Error if the operation fails (matching Python SessionError)

**`Example`**

```typescript
const agentBay = new AgentBay({ apiKey: 'your_api_key' });
const result = await agentBay.create();
if (result.success) {
  await result.session.setLabels({ project: 'demo', env: 'test' });
  const getResult = await result.session.getLabels();
  console.log('Labels:', JSON.stringify(getResult.data));
  await result.session.delete();
}
```

___

### getLink

▸ **getLink**(`protocolType?`, `port?`, `options?`): `Promise`\<`OperationResult`\>

Retrieves an access link for the session.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `protocolType?` | `string` | Protocol type for the link (optional, reserved for future use) |
| `port?` | `number` | Specific port number to access (must be in range [30100, 30199]). If not specified, returns the default session link. |
| `options?` | `string` | - |

#### Returns

`Promise`\<`OperationResult`\>

Promise resolving to OperationResult containing:
         - success: Whether the operation succeeded
         - data: String URL for accessing the session
         - requestId: Unique identifier for this API request
         - errorMessage: Error description if operation failed

**`Throws`**

Error if the API call fails or port is out of valid range.

**`Example`**

```typescript
const agentBay = new AgentBay({ apiKey: 'your_api_key' });
const result = await agentBay.create();
if (result.success) {
  const linkResult = await result.session.getLink();
  console.log(`Session link: ${linkResult.data}`);
  await result.session.delete();
}
```

**`Remarks`**

**Behavior:**
- Without port: Returns the default session access URL
- With port: Returns URL for accessing specific port-mapped service
- Port must be in range [30100, 30199] for port forwarding
- For ADB connections, use `session.mobile.getAdbUrl()` with appropriate ADB public key

**Best Practices:**
- Use default link for general session access
- Use port-specific links when you've started services on specific ports
- Validate port range before calling to avoid errors

**`See`**

[info](#info)

___

### getLinkAsync

▸ **getLinkAsync**(`protocolType?`, `port?`, `options?`): `Promise`\<`OperationResult`\>

Asynchronously get a link associated with the current session.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `protocolType?` | `string` | Optional protocol type to use for the link |
| `port?` | `number` | Optional port to use for the link (must be in range [30100, 30199]) |
| `options?` | `string` | - |

#### Returns

`Promise`\<`OperationResult`\>

OperationResult containing the link as data and request ID

**`Throws`**

Error if the operation fails (matching Python SessionError)

**`Example`**

```typescript
const agentBay = new AgentBay({ apiKey: 'your_api_key' });
const result = await agentBay.create();
if (result.success) {
  const linkResult = await result.session.getLinkAsync(undefined, 30150);
  console.log(`Port link: ${linkResult.data}`);
  await result.session.delete();
}
```

___

### info

▸ **info**(): `Promise`\<`OperationResult`\>

Retrieves detailed information about the current session.

#### Returns

`Promise`\<`OperationResult`\>

Promise resolving to OperationResult containing:
         - success: Whether the operation succeeded (always true if no exception)
         - data: SessionInfo object with the following fields:
           - sessionId (string): The session identifier
           - resourceUrl (string): URL for accessing the session
           - appId (string): Application ID (for desktop sessions)
           - authCode (string): Authentication code
           - connectionProperties (string): Connection configuration
           - resourceId (string): Resource identifier
           - resourceType (string): Type of resource (e.g., "Desktop")
           - ticket (string): Access ticket
         - requestId: Unique identifier for this API request
         - errorMessage: Error description if operation failed

**`Throws`**

Error if the API request fails or response is invalid.

**`Example`**

```typescript
const agentBay = new AgentBay({ apiKey: 'your_api_key' });
const result = await agentBay.create();
if (result.success) {
  const infoResult = await result.session.info();
  console.log(`Session ID: ${infoResult.data.sessionId}`);
  console.log(`Resource URL: ${infoResult.data.resourceUrl}`);
  await result.session.delete();
}
```

**`Remarks`**

**Behavior:**
- This method calls the GetMcpResource API to retrieve session metadata
- The returned SessionInfo contains:
  - sessionId: The session identifier
  - resourceUrl: URL for accessing the session
  - Desktop-specific fields (appId, authCode, connectionProperties, etc.)
    are populated from the DesktopInfo section of the API response
- Session info is retrieved from the AgentBay API in real-time
- The resourceUrl can be used for browser-based access
- Desktop-specific fields (appId, authCode) are only populated for desktop sessions
- This method does not modify the session state

**`See`**

[delete](#delete), [getLink](#getlink)

___

### listMcpTools

▸ **listMcpTools**(`imageId?`): `Promise`\<`McpToolsResult`\>

List MCP tools available for this session.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `imageId?` | `string` | Optional image ID, defaults to session's imageId or "linux_latest" |

#### Returns

`Promise`\<`McpToolsResult`\>

McpToolsResult containing tools list and request ID

**`Example`**

```typescript
const agentBay = new AgentBay({ apiKey: 'your_api_key' });
const result = await agentBay.create();
if (result.success) {
  const toolsResult = await result.session.listMcpTools();
  console.log(`Found ${toolsResult.tools.length} MCP tools`);
  await result.session.delete();
}
```

___

### pauseAsync

▸ **pauseAsync**(`timeout?`, `pollInterval?`): `Promise`\<`SessionPauseResult`\>

Asynchronously pause this session, putting it into a dormant state.

This method calls the PauseSessionAsync API to initiate the pause operation and then polls
the GetSession API to check the session status until it becomes PAUSED or until timeout is reached.
During the paused state, resource usage and costs are reduced while session state is preserved.

#### Parameters

| Name | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| `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`\>

Promise resolving to SessionPauseResult containing:
         - success: Whether the pause operation succeeded
         - requestId: Unique identifier for this API request
         - status: Final session status (should be "PAUSED" if successful)
         - errorMessage: Error description if pause failed

**`Throws`**

Error if the API call fails or network issues occur.

**`Example`**

```typescript
const agentBay = new AgentBay({ apiKey: 'your_api_key' });
const result = await agentBay.create();
if (result.success) {
  const pauseResult = await result.session.pauseAsync();
  if (pauseResult.success) {
    console.log('Session paused successfully');
  }
}
```

**`Remarks`**

**Behavior:**
- Initiates pause operation through PauseSessionAsync API
- Polls session status until PAUSED state or timeout
- Session state transitions: RUNNING -> PAUSING -> PAUSED
- All session state is preserved during pause

**Important Notes:**
- Paused sessions cannot perform operations (deletion, task execution, etc.)
- Use [resumeAsync](#resumeasync) to restore the session to RUNNING state
- During pause, both resource usage and costs are lower
- If timeout is exceeded, returns with success=false

**`See`**

[resumeAsync](#resumeasync)

___

### resumeAsync

▸ **resumeAsync**(`timeout?`, `pollInterval?`): `Promise`\<`SessionResumeResult`\>

Asynchronously resume this session from a paused state.

This method calls the ResumeSessionAsync API to initiate the resume operation and then polls
the GetSession API to check the session status until it becomes RUNNING or until timeout is reached.
After resuming, the session restores full functionality and can perform all operations normally.

#### Parameters

| Name | Type | Default value | Description |
| :------ | :------ | :------ | :------ |
| `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`\>

Promise resolving to SessionResumeResult containing:
         - success: Whether the resume operation succeeded
         - requestId: Unique identifier for this API request
         - status: Final session status (should be "RUNNING" if successful)
         - errorMessage: Error description if resume failed

**`Throws`**

Error if the API call fails or network issues occur.

**`Example`**

```typescript
const agentBay = new AgentBay({ apiKey: 'your_api_key' });
const result = await agentBay.get('paused_session_id');
if (result.success) {
  const resumeResult = await result.session.resumeAsync();
  if (resumeResult.success) {
    console.log('Session resumed successfully');
  }
}
```

**`Remarks`**

**Behavior:**
- Initiates resume operation through ResumeSessionAsync API
- Polls session status until RUNNING state or timeout
- Session state transitions: PAUSED -> RESUMING -> RUNNING
- All previous session state is restored during resume

**Important Notes:**
- Only sessions in PAUSED state can be resumed
- After resume, the session can perform all operations normally
- Use [pauseAsync](#pauseasync) to put a session into PAUSED state
- If timeout is exceeded, returns with success=false

**`See`**

[pauseAsync](#pauseasync)

___

### setLabels

▸ **setLabels**(`labels`): `Promise`\<`OperationResult`\>

Sets the labels for this session.

#### Parameters

| Name | Type | Description |
| :------ | :------ | :------ |
| `labels` | `Record`\<`string`, `string`\> | The labels to set for the session. |

#### Returns

`Promise`\<`OperationResult`\>

OperationResult indicating success or failure with request ID

**`Throws`**

Error if the operation fails (matching Python SessionError)

**`Example`**

```typescript
const agentBay = new AgentBay({ apiKey: 'your_api_key' });
const result = await agentBay.create();
if (result.success) {
  const setResult = await result.session.setLabels({ project: 'demo', env: 'test' });
  console.log('Labels set:', setResult.success);
  await result.session.delete();
}
```

## Related Resources

- [FileSystem API Reference](filesystem.md)
- [Command API Reference](command.md)
- [Context API Reference](context.md)
- [Context Manager API Reference](context-manager.md)
- [OSS API Reference](../../common-features/advanced/oss.md)