AsyncCommand API Reference

March 2, 2026 · View on GitHub

💡 Sync Version: This documentation covers the asynchronous API. For synchronous operations, see Command.

⚡ Performance Advantage: Async API enables concurrent operations with 4-6x performance improvements for parallel tasks.

Command Execution Guide - 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. Commands support configurable timeouts and optional working directory or environment settings.

AsyncCommand

class AsyncCommand(AsyncBaseService)

Async command execution service for session shells in the AgentBay cloud environment.

Use this class for non-blocking command execution; for blocking/synchronous usage, refer to the Command service in the sync API.

execute_command

async def execute_command(
        command: str,
        timeout_ms: int = 50000,
        cwd: Optional[str] = None,
        envs: Optional[Dict[str, str]] = None) -> CommandResult

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.

Arguments:

command: The shell command to execute
timeout_ms: Timeout in milliseconds (default: 50000ms/50s).
cwd: The working directory for command execution. If not specified,

the command runs in the default session directory envs: Environment variables as a dictionary of key-value pairs. These variables are set for the command execution only

Returns:

CommandResult: Result object containing:

success: Whether the command executed successfully (exit_code == 0)
output: Command output for backward compatibility (stdout + stderr)
exit_code: The exit code of the command execution (0 for success)
stdout: Standard output from the command execution
stderr: Standard error from the command execution
trace_id: Trace ID for error tracking (only present when exit_code != 0)
request_id: Unique identifier for this API request
error_message: Error description if execution failed

Raises:

CommandError: If the command execution fails due to system errors

Example:

session = agent_bay.create().session result = await session.command.execute_command("echo 'Hello, World!'") print(result.output) print(result.exit_code) await session.delete()

Example:

result = await session.command.execute_command( "pwd", timeout_ms=5000, cwd="/tmp", envs={"TEST_VAR": "test_value"} ) print(result.stdout) await session.delete()

run

async def run(command: str,
              timeout_ms: int = 50000,
              cwd: Optional[str] = None,
              envs: Optional[Dict[str, str]] = None) -> CommandResult

Alias of execute_command() for better ergonomics and LLM friendliness.

exec

async def exec(command: str,
               timeout_ms: int = 50000,
               cwd: Optional[str] = None,
               envs: Optional[Dict[str, str]] = None) -> CommandResult

Alias of execute_command() for better ergonomics and LLM friendliness.

Best Practices

Always specify appropriate timeout values based on expected command duration
Handle command execution errors gracefully
Use absolute paths when referencing files in commands
Be aware that commands run with session user permissions
Clean up temporary files created by commands