> ## 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.

# Agents SDK

> Define and run agents with `defineAgent()` and `rt.agent`

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](/sdk/tools).)

## Define Agents

```typescript agents/code-assistant.ts theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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.

```typescript sandboxes/dev-env.ts theme={null}
import { defineSandbox } from '@runtools-ai/sdk';

export default defineSandbox({
  slug: 'dev-env',
  template: 'base-ubuntu',
  mounts: [
    {
      workspaceId: '9b84ef42-9c3a-4930-9d4c-45c7f5c22d8e',
      path: '/workspace',
    },
  ],
});
```

```typescript agents/code-assistant.ts theme={null}
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

```typescript theme={null}
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:

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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

```typescript theme={null}
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](/api-reference/agents/create-runtime).

## Types

```typescript theme={null}
import type {
  AgentDefinition,
  AgentRunOptions,
  AgentRunResult,
  AgentThread,
  AgentAttachmentUploadInput,
} from '@runtools-ai/sdk';
```