Skip to main content
POST
/
v1
/
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
  }'

{
  "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"
  }
}

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.

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

​
slug
string
required
URL-safe agent slug. Use lowercase letters, numbers, and hyphens.
​
name
string
Display name. Defaults to slug.
​
description
string
Human-readable description.
​
model
string
Model identifier. Defaults to the platform default when omitted.
​
systemPrompt
string
Agent instructions.
​
tools
array
Core tool names and Tool Hub slugs available to the agent.
​
sandbox
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.
​
executionMode
string
default:"in_sandbox"
in_sandbox, managed, or local-mac.
​
targetDeviceId
string
Required for local-mac agents.
​
resources
array
Attached workspace or sandbox resources for managed and local-mac agents.
​
env
object
Environment variables. Secret references can be resolved server-side when configured.
​
maxIterations
number
Maximum agentic turns.
​
maxTokens
number
Maximum output tokens.
​
temperature
number
Sampling temperature.

​
Response

​
id
string
Agent ID.
​
slug
string
Agent slug.
​
action
string
created or updated.
​
version
number
Agent definition version.
​
sandboxId
string
Linked sandbox ID for sandbox-backed agents.
​
endpoint
string
Convenience URL for the legacy per-agent run endpoint.
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
  }'

{
  "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() to execute an existing agent.
  • in_sandbox agents require a linked sandbox.
  • For sandbox-backed agents, conversation threads preserve chat context and mounted workspaces preserve files.