Skip to main content

​
Overview

Agents in RunTools combine:
  • Agent Runtime - The logic (system prompt, model, tools, workflow)
  • Sandbox Template - The environment (OS, packages, files)
  • Deployment - The API endpoint
Agent Runtime + Sandbox Template = Deployment = API

​
Creating an Agent

Agents are defined as TypeScript files in your agents/ directory:

​
Agent File Format

agents/code-assistant.ts
import { defineAgent } from '@runtools/sdk';

export default defineAgent({
  slug: 'code-assistant',
  name: 'Code Assistant',
  
  model: 'claude-sonnet-4-20250514',
  
  systemPrompt: `You are an expert software engineer.
You help users build applications by writing clean, well-documented code.
Always explain your reasoning before making changes.`,
  
  tools: ['bash', 'read_file', 'edit_file', 'grep', 'glob', 'web_search'],
  
  // Optional: override default template
  template: 'nodejs-20',
  
  // Optional: deployment settings
  deployment: {
    maxConcurrent: 10,
    timeout: 300,
  },
});

​
Creating via CLI

# Interactive
runtools agent create

# With name
runtools agent create code-assistant

​
Creating via SDK

const runtime = await rt.runtimes.create({
  slug: 'code-assistant',
  name: 'Code Assistant',
  systemPrompt: `You are an expert software engineer...`,
  model: 'claude-sonnet-4-20250514',
  tools: ['bash', 'read_file', 'edit_file', 'grep', 'glob', 'web_search'],
});
Dashboard and Code SyncThe dashboard visual builder and your agents/*.ts files are kept in sync:
  • Build visually in the dashboard → Export as TypeScript file
  • Edit TypeScript files → Changes reflected in dashboard
Code is always the source of truth.

​
Core Tools

These tools are included by default when you scaffold a project with npx create-runtools-app or create an agent in the dashboard. Remove any you don’t need.
ToolDescription
bashExecute shell commands. Run anything available in the sandbox.
read_fileRead file contents with optional line range. Returns numbered lines.
edit_fileEdit files with str_replace. Fuzzy matching finds the right location.
grepSearch file contents using ripgrep. Fast regex search across codebase.
globFind files by name pattern. Returns matching file paths.
web_searchSearch the web. Returns summarized results.
bash can run any command available in the sandbox — python script.py, npm run build, ls -la, etc. Use it for anything not covered by the other tools.

​
Marketplace Tools

Add marketplace tools for external integrations: 
const runtime = await rt.runtimes.create({
  slug: 'email-assistant',
  tools: [
    'bash',
    'read_file',
    'edit_file',
    'gmail',      // Send/read emails
    'slack',      // Post to Slack
    'github',     // Manage repos
  ],
});

Tools Marketplace

Browse available tools

​
Deploying an Agent

​
Push to Dashboard (Preview)

Push your agent to the dashboard for preview before going live: 
runtools push code-assistant
This uploads your agent to the dashboard where you can:
  • Review the configuration
  • Test it interactively
  • Make final adjustments
  • Click “Deploy” when ready

​
Deploy to Production

Deploy directly to production: 
runtools deploy code-assistant
Now you have an API endpoint:
  • POST /v1/run/my-code-bot
  • WS /v1/run/my-code-bot/stream/:runId

​
Running an Agent

​
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); // If a dev server was started

​
With Mounts

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

​
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);
      break;
    case 'dev_url':
      console.log('[url]', event.url);
      break;
    case 'complete':
      console.log('[done]', event.output);
      break;
  }
}

​
Run Controls

Control a running agent: 
const run = await rt.agents.run('my-code-bot', { ... });

// Pause execution (snapshot state)
await run.pause();

// Resume from snapshot
await run.resume();

// Cancel execution
await run.cancel();

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

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

​
Model Selection

RunTools is model-agnostic. Use any provider: 
// 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', // API format
  },
  // ...
});

​
Visual Workflow Builder

For complex agent logic, use the visual workflow builder in the dashboard:
  • Drag-and-drop nodes — Tool Call, Branch, Loop, Respond
  • Connect with edges — Define execution flow
  • Set conditions — Branch based on tool results or context
  • Export as code — Download your workflow as SDK code

Workflow Builder

Open the visual builder in your dashboard

​
Versioning

Create versions and rollback: 
// Create a version
await runtime.createVersion();

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

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

​
Webhooks

Get notified when runs complete: 
const deployment = await rt.deployments.create({
  runtimeSlug: 'code-assistant',
  templateSlug: 'nodejs-20',
  apiSlug: 'my-bot',
  webhookUrl: 'https://myapp.com/webhook',
  webhookEvents: ['run.started', 'run.completed', 'run.failed'],
});

// Your webhook receives:
// {
//   "type": "run.completed",
//   "runId": "run-abc123",
//   "output": "...",
//   "devUrl": "https://..."
// }

​
CLI: Interactive Chat

runtools agent chat my-code-bot

You: Build a todo app with React
[thinking] I'll create a React todo app with TypeScript...
[tool] bash: npx create-vite@latest todo -- --template react-ts
[result] Created project structure
[edit] /src/App.tsx
[tool] bash: npm run dev
[url] https://sandbox-abc123.sandboxes.runtools.ai
[done] Your todo app is running.
You: Add dark mode
[thinking] I'll add a dark mode toggle...

​
Best Practices

Be specific about what the agent should do and how. Include examples if helpful.
Don’t enable tools the agent doesn’t need. Fewer tools = faster, cheaper, more focused.
Match the template to your use case. Don’t use a 2GB ML template for simple Node.js tasks.
Prevent runaway agents with appropriate timeout limits.