Computer Agents SDK

Official TypeScript/JavaScript SDK for the Computer Agents Cloud API.

Installation

npm install computer-agents
# or
pnpm add computer-agents
# or
yarn add computer-agents

Quick Start

import { ComputerAgentsClient } from 'computer-agents';

const client = new ComputerAgentsClient({
  apiKey: process.env.COMPUTER_AGENTS_API_KEY
});

// Execute a task
const result = await client.run('Create a REST API with Flask', {
  environmentId: 'env_xxx',
  onEvent: (event) => console.log(event.type)
});

console.log(result.content);

Features

• Full TypeScript support with complete type definitions
• SSE streaming for real-time execution progress
• Simple, intuitive API that mirrors the REST API structure
• Zero dependencies - uses native fetch

API Reference

Creating a Client

const client = new ComputerAgentsClient({
  apiKey: 'tb_xxx',                              // Required
  baseUrl: 'https://api.computer-agents.com',   // Optional (default)
  timeout: 60000,                                // Optional (default: 60s)
  debug: false                                   // Optional
});

Running Tasks

The simplest way to execute a task:

// One-shot execution
const result = await client.run('Fix the TypeScript errors', {
  environmentId: 'env_xxx'
});

// With streaming progress
const result = await client.run('Build a REST API', {
  environmentId: 'env_xxx',
  onEvent: (event) => {
    if (event.type === 'response.item.completed') {
      console.log(event.item);
    }
  }
});

// Continue a conversation
const followUp = await client.run('Add authentication', {
  environmentId: 'env_xxx',
  threadId: result.threadId
});

Threads

For multi-turn conversations:

// Create a thread
const thread = await client.threads.create({
  environmentId: 'env_xxx'
});

// Send a message
const result = await client.threads.sendMessage(thread.id, {
  content: 'Create a REST API',
  onEvent: (event) => console.log(event)
});

// List threads
const threads = await client.threads.list();

// Get a specific thread
const thread = await client.threads.get('thread_xxx');

// Delete a thread
await client.threads.delete('thread_xxx');

Environments

Manage isolated execution environments:

// Create an environment with custom configuration
const env = await client.environments.create({
  name: 'data-science',
  description: 'Environment for data processing',
  runtimes: { python: '3.12', nodejs: '20' },
  packages: {
    system: ['ffmpeg'],
    python: ['pandas', 'numpy'],
    node: ['typescript']
  },
  internetAccess: true
});

// List environments
const environments = await client.environments.list();

// Get an environment
const env = await client.environments.get('env_xxx');

// Get default environment (creates one if doesn't exist)
const defaultEnv = await client.environments.getDefault();

// Update an environment
await client.environments.update('env_xxx', {
  description: 'Updated description'
});

// Delete an environment
await client.environments.delete('env_xxx');

Runtime Management

// List all available runtimes and versions
const available = await client.environments.listAvailableRuntimes();
// { python: ['3.9', '3.10', '3.11', '3.12', '3.13'], nodejs: ['18', '20', '22'], ... }

// Get current runtimes for an environment
const runtimes = await client.environments.getRuntimes('env_xxx');
// { python: '3.12', nodejs: '20' }

// Set runtime versions (triggers rebuild)
await client.environments.setRuntimes('env_xxx', {
  python: '3.12',
  nodejs: '20',
  go: '1.22'
});

Package Management

// List installed packages
const packages = await client.environments.listPackages('env_xxx');
// { system: ['ffmpeg'], python: ['pandas'], node: ['typescript'] }

// Install packages (triggers rebuild)
await client.environments.installPackages('env_xxx', 'python', ['requests', 'beautifulsoup4']);
await client.environments.installPackages('env_xxx', 'system', ['imagemagick']);
await client.environments.installPackages('env_xxx', 'node', ['tsx']);

// Uninstall a package (triggers rebuild)
await client.environments.uninstallPackage('env_xxx', 'python', 'requests');

Dockerfile Customization

// Get Dockerfile configuration
const dockerfile = await client.environments.getDockerfile('env_xxx');
// { baseImage: '...', dockerfileExtensions: '...', effectiveDockerfile: '...' }

// Set Dockerfile extensions (triggers rebuild)
await client.environments.setDockerfileExtensions('env_xxx',
  'RUN pip install custom-package\nRUN apt-get install -y custom-tool'
);

// Validate Dockerfile syntax without building
const validation = await client.environments.validateDockerfile('env_xxx',
  'RUN pip install something'
);
// { valid: true, warnings: [], effectiveDockerfile: '...' }

Build Management

// Trigger a build
const build = await client.environments.triggerBuild('env_xxx');
// { buildId: 'build_xxx', status: 'building', message: 'Build started' }

// Force rebuild even if up to date
await client.environments.triggerBuild('env_xxx', true);

// Get build status
const status = await client.environments.getBuildStatus('env_xxx');
// { buildStatus: 'ready', buildHash: '...', imageTag: '...', lastBuildAt: '...' }

// Get build logs
const logs = await client.environments.getBuildLogs('env_xxx');
// { logs: '...', buildStatus: 'ready' }

// Test build (validates without caching)
const test = await client.environments.testBuild('env_xxx');
// { success: true, logs: '...', duration: 45000 }

Agents

Configure agent behavior:

// Create an agent
const agent = await client.agents.create({
  name: 'Code Assistant',
  model: 'gpt-4o',
  instructions: 'You are a helpful coding assistant.'
});

// List agents
const agents = await client.agents.list();

// Update an agent
await client.agents.update('agent_xxx', {
  instructions: 'Updated instructions'
});

Files

Manage files in environment workspaces:

// List files in an environment
const files = await client.files.listFiles('env_xxx');

// Upload a file
await client.files.uploadFile({
  environmentId: 'env_xxx',
  filename: 'app.py',
  path: 'src',  // optional subdirectory
  content: 'print("hello")'
});

// Download file content
const content = await client.files.getFile('env_xxx', 'src/app.py');

// Download as Buffer
const buffer = await client.files.downloadFile('env_xxx', 'src/app.py');

// Move/rename a file
await client.files.moveFile({
  environmentId: 'env_xxx',
  sourcePath: 'old-name.py',
  destPath: 'new-name.py'
});

// Delete a file
await client.files.deleteFile('env_xxx', 'src/app.py');

Schedules

Automate task execution:

// Create a schedule
const schedule = await client.schedules.create({
  name: 'Daily Report',
  agentId: 'agent_xxx',
  agentName: 'Reporter',
  task: 'Generate daily report',
  scheduleType: 'recurring',
  cronExpression: '0 9 * * *'
});

// List schedules
const schedules = await client.schedules.list();

// Trigger a schedule manually
await client.schedules.trigger('schedule_xxx');

Billing

Track usage and manage budgets:

// Get budget status
const status = await client.budget.getStatus();

// Check if can execute
const canRun = await client.budget.canExecute();

// Get billing records
const records = await client.billing.listRecords({ limit: 10 });

// Get usage stats
const stats = await client.billing.getStats({ period: 'month' });

Git Operations

Manage version control:

// Get diff
const diff = await client.git.diff('env_xxx');

// Commit changes
await client.git.commit('env_xxx', {
  message: 'Add new feature'
});

// Push to remote
await client.git.push('env_xxx');

Error Handling

import { ComputerAgentsClient, ApiClientError } from 'computer-agents';

try {
  await client.run('Task', { environmentId: 'env_xxx' });
} catch (error) {
  if (error instanceof ApiClientError) {
    console.error(`API Error: ${error.message}`);
    console.error(`Status: ${error.status}`);
    console.error(`Code: ${error.code}`);
  }
}

Environment Variables

| Variable | Description | |----------|-------------| | COMPUTER_AGENTS_API_KEY | API key for authentication |

TypeScript

Full type definitions are included:

import type {
  // Core types
  Thread,
  Environment,
  CloudAgent,
  Schedule,
  BudgetStatus,
  MessageStreamEvent,

  // Environment configuration
  RuntimeConfig,
  PackagesConfig,
  AvailableRuntimes,
  PackageType,
  BuildStatus,
  BuildStatusResult,
  DockerfileResult,
} from 'computer-agents';

License

MIT