Computer Agents SDK

The official TypeScript/JavaScript SDK for interacting with the Computer Agents Cloud API. Execute AI agents in isolated cloud environments with full streaming support.

Installation


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

Quick Example


import { ComputerAgentsClient } from 'computer-agents';
 
const client = new ComputerAgentsClient({
  apiKey: process.env.COMPUTER_AGENTS_API_KEY
});
 
// Execute a task with streaming
const result = await client.run('Create a REST API with Flask', {
  environmentId: 'env_xxx',
  onEvent: (event) => {
    if (event.type === 'response.item.completed') {
      console.log(event.item);
    }
  }
});
 
console.log(result.content);
console.log('Thread ID:', result.threadId);

Features

Full TypeScript support - Complete type definitions for all resources
SSE streaming - Real-time execution progress with event callbacks
Simple API - Clean, intuitive interface that mirrors the REST API
Zero dependencies - Uses native fetch for HTTP requests
Multi-turn conversations - Thread-based execution with session continuity

Client Configuration


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

Environment Variables

The SDK automatically checks for API keys in environment variables:

Variable	Description
`COMPUTER_AGENTS_API_KEY`	Primary API key variable
`TESTBASE_API_KEY`	Legacy fallback variable

Core Concepts

Environments

Isolated execution environments with their own file systems, environment variables, and configurations.


// Create an environment
const env = await client.environments.create({
  name: 'my-project',
  internetAccess: true
});
 
// Use in executions
const result = await client.run('Build the app', {
  environmentId: env.id
});

Threads

Persistent conversation contexts that maintain state across multiple executions.


// Create a thread
const thread = await client.threads.create({
  environmentId: 'env_xxx'
});
 
// Send messages to the thread
const result = await client.threads.sendMessage(thread.id, {
  content: 'Create a user model',
  onEvent: (event) => console.log(event.type)
});
 
// Continue the conversation
const followUp = await client.threads.sendMessage(thread.id, {
  content: 'Add validation to the model'
});

The `run()` Method

The simplest way to execute tasks. Handles thread creation automatically.


// One-shot execution
const result = await client.run('Fix TypeScript errors', {
  environmentId: 'env_xxx'
});
 
// Continue a conversation
const followUp = await client.run('Now add tests', {
  environmentId: 'env_xxx',
  threadId: result.threadId
});

Available Resources

Resource	Description
`client.threads`	Conversation threads with streaming
`client.environments`	Isolated execution environments
`client.agents`	Agent configurations
`client.files`	File management in environments
`client.schedules`	Scheduled task execution
`client.subscription`	Subscription status and usage
`client.git`	Git operations on workspaces

See API Resources for detailed documentation on each resource.

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}`);
  }
}

TypeScript Support

Full type definitions are included:


import type {
  Thread,
  Environment,
  CloudAgent,
  Schedule,
  SubscriptionStatus,
  MessageStreamEvent,
} from 'computer-agents';

Next Steps

Quick Start - Get up and running in 5 minutes
API Resources - Deep dive into each resource
Streaming & Events - Handle real-time execution events
Advanced Patterns - Production patterns and best practices

Example: Full Workflow


import { ComputerAgentsClient } from 'computer-agents';
 
const client = new ComputerAgentsClient({
  apiKey: process.env.COMPUTER_AGENTS_API_KEY
});
 
async function main() {
  // 1. Create or get an environment
  const environments = await client.environments.list();
  let env = environments.find(e => e.isDefault);
 
  if (!env) {
    env = await client.environments.create({
      name: 'default',
      internetAccess: true,
      isDefault: true
    });
  }
 
  // 2. Execute a multi-step task
  const result1 = await client.run('Create a Python Flask API with /health endpoint', {
    environmentId: env.id,
    onEvent: (event) => {
      if (event.type === 'response.item.completed') {
        console.log('Progress:', event.item.type);
      }
    }
  });
 
  console.log('Step 1 complete:', result1.content);
 
  // 3. Continue the conversation
  const result2 = await client.run('Add a /users endpoint with CRUD operations', {
    environmentId: env.id,
    threadId: result1.threadId
  });
 
  console.log('Step 2 complete:', result2.content);
 
  // 4. Check the files
  const files = await client.files.listFiles(env.id);
  console.log('Files created:', files.map(f => f.path));
}
 
main().catch(console.error);