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

# Create Agent

> Create or update an agent definition

`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

<ParamField body="slug" type="string" required>
  URL-safe agent slug. Use lowercase letters, numbers, and hyphens.
</ParamField>

<ParamField body="name" type="string">
  Display name. Defaults to `slug`.
</ParamField>

<ParamField body="description" type="string">
  Human-readable description.
</ParamField>

<ParamField body="model" type="string">
  Model identifier. Defaults to the platform default when omitted.
</ParamField>

<ParamField body="systemPrompt" type="string">
  Agent instructions.
</ParamField>

<ParamField body="tools" type="array">
  Core tool names and Tool Hub slugs available to the agent.
</ParamField>

<ParamField body="sandbox" type="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.
</ParamField>

<ParamField body="executionMode" type="string" default="in_sandbox">
  `in_sandbox`, `managed`, or `local-mac`.
</ParamField>

<ParamField body="targetDeviceId" type="string">
  Required for `local-mac` agents.
</ParamField>

<ParamField body="resources" type="array">
  Attached workspace or sandbox resources for `managed` and `local-mac` agents.
</ParamField>

<ParamField body="env" type="object">
  Environment variables. Secret references can be resolved server-side when configured.
</ParamField>

<ParamField body="maxIterations" type="number">
  Maximum agentic turns.
</ParamField>

<ParamField body="maxTokens" type="number">
  Maximum output tokens.
</ParamField>

<ParamField body="temperature" type="number">
  Sampling temperature.
</ParamField>

## Response

<ResponseField name="id" type="string">
  Agent ID.
</ResponseField>

<ResponseField name="slug" type="string">
  Agent slug.
</ResponseField>

<ResponseField name="action" type="string">
  `created` or `updated`.
</ResponseField>

<ResponseField name="version" type="number">
  Agent definition version.
</ResponseField>

<ResponseField name="sandboxId" type="string">
  Linked sandbox ID for sandbox-backed agents.
</ResponseField>

<ResponseField name="endpoint" type="string">
  Compatibility URL for the per-agent run endpoint. New code should prefer `POST /v1/run`.
</ResponseField>

<RequestExample>
  ```bash cURL theme={null}
  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
    }'
  ```

  ```typescript SDK definitions theme={null}
  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',
  });
  ```
</RequestExample>

<ResponseExample>
  ```json 201 Created theme={null}
  {
    "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"
    }
  }
  ```
</ResponseExample>

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