Skip to main content
The SDK agent API has changed from the spec below. The rt.runtimes.create() and rt.deployments.create() methods don’t exist. Instead, define agents with defineAgent() and deploy via runtools deploy. The rt.agents.run() method is not yet implemented in the SDK — use the REST API (POST /v1/run) directly.

​
Creating Agent Runtimes

import { RunTools } from '@runtools/sdk';

const rt = new RunTools({ apiKey: process.env.RUNTOOLS_API_KEY });

const runtime = await rt.runtimes.create({
  slug: 'code-assistant',
  name: 'Code Assistant',
  systemPrompt: `You are an expert software engineer.
Help users build applications with clean, well-documented code.`,
  model: 'claude-opus-4-5',
  tools: ['bash', 'read_file', 'edit_file', 'grep', 'glob', 'web_search'],
});

​
Model Configuration

// Anthropic
const runtime = await rt.runtimes.create({
  model: 'claude-opus-4-5',
  // ...
});

// OpenAI
const runtime = await rt.runtimes.create({
  model: 'gpt-5.2',
  // ...
});

// Google
const runtime = await rt.runtimes.create({
  model: 'gemini-3-pro',
  // ...
});

// Custom endpoint
const runtime = await rt.runtimes.create({
  model: {
    provider: 'custom',
    endpoint: 'https://my-model.example.com/v1/chat',
    apiKey: process.env.MY_MODEL_KEY,
    format: 'openai',
  },
  // ...
});

​
Creating Deployments

const deployment = await rt.deployments.create({
  runtimeSlug: 'code-assistant',
  templateSlug: 'nodejs-20',
  apiSlug: 'my-code-bot',
  
  // Optional
  mounts: [
    { workspaceId: 'shared-libs', path: '/libs' },
  ],
  webhookUrl: 'https://myapp.com/webhook',
  webhookEvents: ['run.completed', 'run.failed'],
  maxConcurrent: 10,
  timeout: 300,
  secrets: ['GITHUB_TOKEN', 'DATABASE_URL'],
});

console.log(deployment.apiEndpoint);
// → POST https://api.runtools.ai/v1/run/my-code-bot

​
Running Agents

​
Simple Run

const result = await rt.agents.run('my-code-bot', {
  message: 'Create a React todo app with TypeScript',
});

console.log(result.output);
console.log(result.devUrl);
console.log(result.files); // Files created/modified

​
Streaming

const run = await rt.agents.run('my-code-bot', {
  message: 'Build a landing page',
  stream: true,
});

for await (const event of run) {
  switch (event.type) {
    case 'thinking':
      console.log('[thinking]', event.content);
      break;
    case 'tool_call':
      console.log('[tool]', event.tool, event.input);
      break;
    case 'tool_result':
      console.log('[result]', event.output);
      break;
    case 'file_edit':
      console.log('[edit]', event.path, event.diff);
      break;
    case 'dev_url':
      console.log('[url]', event.url);
      break;
    case 'error':
      console.error('[error]', event.message);
      break;
    case 'complete':
      console.log('[done]', event.output);
      break;
  }
}

​
With Mounts

// Mount user's project for the agent to work on
const run = await rt.agents.run('my-code-bot', {
  message: 'Fix the bug in the login component',
  mounts: [
    { workspaceId: 'user-123-project', path: '/workspace' },
  ],
});

​
With Context

const run = await rt.agents.run('my-code-bot', {
  message: 'Add dark mode to the app',
  context: {
    files: ['/src/App.tsx', '/src/styles.css'],
    history: previousRun.messages,
  },
});

​
Run Controls

const run = await rt.agents.run('my-code-bot', {
  message: 'Complex task...',
  stream: true,
});

// Pause execution
await run.pause();

// Resume
await run.resume();

// Cancel
await run.cancel();

// Send user input mid-run
await run.sendInput('yes, continue with that approach');

// Access files during run
const files = await run.files.list('/');
const code = await run.files.read('/src/App.tsx');

​
Managing Runtimes

// List runtimes
const runtimes = await rt.runtimes.list();

// Get runtime
const runtime = await rt.runtimes.get('code-assistant');

// Update runtime
await runtime.update({
  systemPrompt: 'Updated prompt...',
  tools: ['bash', 'read_file', 'edit_file', 'gmail'],
});

// Delete runtime
await runtime.delete();

​
Versioning

// Create version
await runtime.createVersion();

// List versions
const versions = await runtime.versions();

// Rollback
await runtime.rollback({ version: 2 });

​
Managing Deployments

// List deployments
const deployments = await rt.deployments.list();

// Get deployment
const deployment = await rt.deployments.get('my-code-bot');

// Update
await deployment.update({
  maxConcurrent: 20,
});

// Delete
await deployment.delete();

​
Run History

// List runs
const runs = await rt.runs.list({
  deployment: 'my-code-bot',
  status: 'completed',
  limit: 50,
});

// Get run details
const run = await rt.runs.get('run-abc123');
console.log(run.messages);
console.log(run.toolCalls);
console.log(run.output);

​
Types

import type {
  AgentRuntime,
  AgentDeployment,
  AgentRun,
  AgentRunEvent,
  AgentRunStatus,
  ModelConfig,
} from '@runtools/sdk';