Create Agent - Runtools.ai

curl -X POST https://api.runtools.ai/v1/agents \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "code-assistant",
    "name": "Code Assistant",
    "model": "claude-sonnet-4",
    "systemPrompt": "You are a careful software engineering assistant.",
    "tools": ["exec_command", "write_stdin", "apply_patch", "web_search", "get_dev_url"],
    "sandbox": "build-runner",
    "executionMode": "in_sandbox",
    "maxIterations": 25,
    "maxTokens": 16384
  }'

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

export default defineAgent({
  slug: 'code-assistant',
  name: 'Code Assistant',
  model: 'claude-sonnet-4',
  systemPrompt: 'You are a careful software engineering assistant.',
  tools: ['exec_command', 'write_stdin', 'apply_patch', 'web_search', 'get_dev_url'],
  sandbox: 'build-runner',
  executionMode: 'in_sandbox',
});

{
  "data": {
    "id": "agt_abc123",
    "slug": "code-assistant",
    "action": "created",
    "version": 1,
    "sandboxId": "sandbox-abc123",
    "targetDeviceId": null,
    "endpoint": "https://api.runtools.ai/v1/agents/code-assistant/run"
  }
}

POST

agents

curl -X POST https://api.runtools.ai/v1/agents \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "code-assistant",
    "name": "Code Assistant",
    "model": "claude-sonnet-4",
    "systemPrompt": "You are a careful software engineering assistant.",
    "tools": ["exec_command", "write_stdin", "apply_patch", "web_search", "get_dev_url"],
    "sandbox": "build-runner",
    "executionMode": "in_sandbox",
    "maxIterations": 25,
    "maxTokens": 16384
  }'

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

export default defineAgent({
  slug: 'code-assistant',
  name: 'Code Assistant',
  model: 'claude-sonnet-4',
  systemPrompt: 'You are a careful software engineering assistant.',
  tools: ['exec_command', 'write_stdin', 'apply_patch', 'web_search', 'get_dev_url'],
  sandbox: 'build-runner',
  executionMode: 'in_sandbox',
});

{
  "data": {
    "id": "agt_abc123",
    "slug": "code-assistant",
    "action": "created",
    "version": 1,
    "sandboxId": "sandbox-abc123",
    "targetDeviceId": null,
    "endpoint": "https://api.runtools.ai/v1/agents/code-assistant/run"
  }
}

POST /v1/agents upserts an agent by organization and slug. For sandbox-backed agents, create a sandbox first and pass its ID or name in sandbox. Mount a workspace on that sandbox when the agent needs durable storage and persistent filesystem memory across runs.

Request Body

string

required

URL-safe agent slug. Use lowercase letters, numbers, and hyphens.

string

Display name. Defaults to slug.

string

Human-readable description.

string

Model identifier. Defaults to the platform default when omitted.

string

Agent instructions.

array

Core tool names and Tool Hub slugs available to the agent.

string

Sandbox ID or name for in_sandbox agents. If that sandbox has a workspace mounted, the agent can use the mount path as durable storage.

string

default:"in_sandbox"

in_sandbox, managed, or local-mac.

string

Required for local-mac agents.

array

Attached workspace or sandbox resources for managed and local-mac agents.

object

Environment variables. Secret references can be resolved server-side when configured.

number

Maximum agentic turns.

number

Maximum output tokens.

number

Sampling temperature.

Response

string

Agent ID.

string

Agent slug.

string

created or updated.

number

Agent definition version.

string

Linked sandbox ID for sandbox-backed agents.

string

Compatibility URL for the per-agent run endpoint. New code should prefer POST /v1/run.

curl -X POST https://api.runtools.ai/v1/agents \
  -H "X-API-Key: $RUNTOOLS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "code-assistant",
    "name": "Code Assistant",
    "model": "claude-sonnet-4",
    "systemPrompt": "You are a careful software engineering assistant.",
    "tools": ["exec_command", "write_stdin", "apply_patch", "web_search", "get_dev_url"],
    "sandbox": "build-runner",
    "executionMode": "in_sandbox",
    "maxIterations": 25,
    "maxTokens": 16384
  }'

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

export default defineAgent({
  slug: 'code-assistant',
  name: 'Code Assistant',
  model: 'claude-sonnet-4',
  systemPrompt: 'You are a careful software engineering assistant.',
  tools: ['exec_command', 'write_stdin', 'apply_patch', 'web_search', 'get_dev_url'],
  sandbox: 'build-runner',
  executionMode: 'in_sandbox',
});

{
  "data": {
    "id": "agt_abc123",
    "slug": "code-assistant",
    "action": "created",
    "version": 1,
    "sandboxId": "sandbox-abc123",
    "targetDeviceId": null,
    "endpoint": "https://api.runtools.ai/v1/agents/code-assistant/run"
  }
}

Notes

The SDK does not expose rt.runtimes or rt.deployments. Agent definitions are deployed with runtools deploy or direct POST /v1/agents.
Use rt.agent.run() or POST /v1/run to execute an existing agent.
in_sandbox agents require a linked sandbox. The run path wakes paused sandboxes when possible before dispatching.
local-mac agents require a targetDeviceId from RunMesh.
For sandbox-backed agents, conversation threads preserve chat context and mounted workspaces preserve files.

Models Deployments

​Request Body

​Response

​Notes

Request Body

Response

Notes