Agents SDK - Runtools.ai

Two halves of the same package: defineAgent() describes an agent in a file you deploy, and rt.agent runs agents and works with their threads. (For the tools an agent can call, see Tools.)

Define Agents

agents/code-assistant.ts

import { defineAgent } from '@runtools-ai/sdk';

export default defineAgent({
  slug: 'code-assistant',
  name: 'Code Assistant',
  model: 'claude-sonnet-4.5',
  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.5',
  systemPrompt: 'Research with attached resources.',
  tools: ['web_search'],
  resources: [
    { type: 'workspace', resourceId: 'shared-docs' },
  ],
});

Supported modes are in_sandbox, managed, and local-mac. local-mac agents require a targetDeviceId from RunMesh:

export default defineAgent({
  slug: 'code-on-my-mac',
  executionMode: 'local-mac',
  targetDeviceId: 'node_abc123',
  model: 'claude-opus-4.6',
  tools: ['exec_command', 'write_stdin', 'apply_patch', 'view_image', 'web_search'],
});

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-ai/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-ai/sdk';

export default defineAgent({
  slug: 'code-assistant',
  model: 'claude-sonnet-4.5',
  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);

Manage runs

Inspect or stop runs after they start:

const runs = await rt.agent.listRuns({ agent: 'code-assistant', status: 'running', limit: 20 });
const run = await rt.agent.getRun(runs[0].id);
await rt.agent.cancelRun(run.id);

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.threads.list({ limit: 20 });
const detail = await rt.threads.get(first.threadId!);
const events = await rt.threads.getEvents(first.threadId!);
await rt.threads.archive(first.threadId!);

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-ai/sdk';

​Define Agents

​Execution Modes

​Persistent Files

​Run Agents

​Manage runs

​Threads

​Attachments

​Manage Agents

​Types