Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.runtools.ai/llms.txt

Use this file to discover all available pages before exploring further.

​
Define Agents

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

export default defineAgent({
  slug: 'code-assistant',
  name: 'Code Assistant',
  model: 'claude-sonnet-4',
  systemPrompt: 'You are a careful software engineer.',
  tools: ['exec_command', 'write_stdin', 'apply_patch', 'view_image', 'web_search'],
  sandbox: 'dev-env',
  maxIterations: 25,
});
Deploy with runtools deploy.

​
Execution Modes

export default defineAgent({
  slug: 'managed-researcher',
  executionMode: 'managed',
  model: 'claude-sonnet-4',
  systemPrompt: 'Research with attached resources.',
  tools: ['web_search'],
  resources: [
    { type: 'workspace', resourceId: 'shared-docs' },
  ],
});
Supported modes are in_sandbox, managed, and local-mac.

​
Persistent Files

For in_sandbox agents, mount a workspace on the linked sandbox. The agent works through the sandbox, and files under the mount path persist as the agent’s filesystem memory.
sandboxes/dev-env.ts
import { defineSandbox } from '@runtools/sdk';

export default defineSandbox({
  slug: 'dev-env',
  template: 'base-ubuntu',
  mounts: [
    {
      workspaceId: '9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e',
      path: '/workspace',
    },
  ],
});
agents/code-assistant.ts
import { defineAgent } from '@runtools/sdk';

export default defineAgent({
  slug: 'code-assistant',
  model: 'claude-sonnet-4',
  systemPrompt: 'Use /workspace for durable project state.',
  tools: ['exec_command', 'write_stdin', 'apply_patch', 'web_search'],
  sandbox: 'dev-env',
});
Threads preserve conversation context. Workspaces preserve files, generated artifacts, and repo state.

​
Run Agents

const result = await rt.agent.run(
  'code-assistant',
  'Add tests for the auth module',
  {
    maxTokens: 4096,
    maxTurns: 20,
    temperature: 0.3,
  },
);

console.log(result.result);

​
Threads

const first = await rt.agent.run('code-assistant', 'Start a new project', {
  thread: true,
});

await rt.agent.run('code-assistant', 'Add a login page', {
  threadId: first.threadId,
});

const threads = await rt.agent.threads('code-assistant', 20);
const detail = await rt.agent.getThread(first.threadId!, 'code-assistant');
await rt.agent.deleteThread(first.threadId!, 'code-assistant');
Threaded runs can return THREAD_BUSY if another run is active on the same thread.

​
Attachments

const { part, attachment } = await rt.agent.uploadAttachment({
  threadId,
  agentSlug: 'code-assistant',
  filename: 'spec.md',
  contentType: 'text/markdown',
  data: bytes,
});

await rt.agent.run('code-assistant', 'Use the attached spec', {
  threadId,
  attachments: [part],
});

​
Manage Agents

const agents = await rt.agent.list();
await rt.agent.setVisibility('code-assistant', 'org');
The create/update/delete agent definition lifecycle is usually handled by runtools deploy or the dashboard. Direct REST endpoints are documented in Create Agent.

​
Types

import type {
  AgentDefinition,
  AgentRunOptions,
  AgentRunResult,
  AgentThread,
  AgentAttachmentUploadInput,
} from '@runtools/sdk';