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.

​
Overview

Agents combine a model, instructions, tools, execution mode, and optional resources. You can create them in the dashboard, upsert them through POST /v1/agents, deploy them from agents/*.ts, and run them through the CLI, SDK, or REST API.

​
Define an Agent

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', 'get_dev_url'],
  sandbox: 'dev-env',
  maxIterations: 25,
  maxTokens: 16384,
  temperature: 0.4,
});
Deploy: 
runtools deploy

​
Execution Modes

ModeDescription
in_sandboxDefault. The agent runs against one linked sandbox
managedThe agent runs in the managed runtime and can attach workspaces or sandboxes as resources
local-macThe agent is bound to one registered RunMesh device
For in_sandbox, set sandbox to a sandbox slug from sandboxes/*.ts or an existing sandbox reference.

​
Filesystem Memory

When an in_sandbox agent needs durable storage, mount a workspace into the linked sandbox. The sandbox gives the agent an environment to run commands and use file tools; the workspace mount is the part of that environment that persists across agent runs and sandbox lifecycle changes.
sandboxes/dev-env.ts
import { defineSandbox } from '@runtools/sdk';

export default defineSandbox({
  slug: 'dev-env',
  name: 'Development Environment',
  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: 'Work carefully in the mounted project workspace.',
  tools: ['exec_command', 'write_stdin', 'apply_patch', 'view_image', 'web_search'],
  sandbox: 'dev-env',
});
The agent can read and write /workspace during each run. Conversation threads preserve dialogue context; workspaces preserve repo files, artifacts, task notes, and other filesystem state. For managed, use resources: 
export default defineAgent({
  slug: 'release-coordinator',
  executionMode: 'managed',
  model: 'claude-sonnet-4',
  systemPrompt: 'Coordinate release work across attached resources.',
  tools: ['web_search'],
  resources: [
    { type: 'workspace', resourceId: 'shared-docs' },
    { type: 'sandbox', resourceId: 'release-env', alias: 'release-box' },
  ],
});

​
Run an Agent

runtools agent run code-assistant "Create a REST API with Express and TypeScript"

​
Threads

Use threads for persisted conversations: 
const first = await rt.agent.run('code-assistant', 'Start a todo app', {
  thread: true,
});

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

const threads = await rt.agent.threads('code-assistant');
The lower-level thread API is available through rt.threads for listing cloud threads, reading event history, archiving, renaming, compacting, and subscribing to live frames.

​
Attachments

For file inputs, create an upload target and include the returned message part in the next run: 
const { part } = await rt.agent.uploadAttachment({
  threadId,
  agentSlug: 'code-assistant',
  filename: 'requirements.md',
  contentType: 'text/markdown',
  data: fileBytes,
});

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

​
Tools

Agents can use tool slugs from three sources:
SourceExample
Agent runtime toolsexec_command, write_stdin, apply_patch, view_image, web_search, get_dev_url
Marketplace toolsgithub, gmail, slack
Custom org toolsAny defineTool() deployed from your project
Install marketplace tools before using them: 
runtools tool search github
runtools tool install github
runtools oauth connect github

​
Configuration

defineAgent() validates common model parameters:
FieldRange
maxIterations1-100
maxTokens1-128000
temperature0-2
topP0-1
presencePenalty / frequencyPenalty-2 to 2
toolChoiceauto, none, required, or a specific tool
Provider-specific options pass through in providerOptions.

​
Best Practices

defineAgent() should contain serializable configuration. Put integration logic in tools.
OAuth tokens are resolved by Runtools services, so agents do not need provider tokens in prompts or sandbox files.
Threads preserve context and expose live event streams for UI surfaces.