> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.runtype.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.runtype.com/_mcp/server.

# Create agent

POST https://api.runtype.com/v1/agents
Content-Type: application/json

Create a new agent with optional capabilities and configuration. Supports runtype, external, and claude\_managed agent types. External-agent auth credentials are accepted on write but returned as \<redacted>; a configuration copied from a management response must replace that placeholder with the real credential before create.

Reference: https://docs.runtype.com/api-reference/runtype-api/agents/create-agent

## Authentication

- `Authorization` header (bearer token, required) — API key or Clerk session token

## Servers

- `https://api.runtype.com` (Production, default)
- `https://api.runtype-staging.com` (Staging)

## Request

### Body (application/json)

This endpoint expects an object.

- `name` (string, required)
- `agentType` (enum, optional, default: runtype)
  - Allowed values: `runtype`, `external`, `claude_managed`
- `capabilities` (list of V1AgentsPostRequestBodyContentApplicationJsonSchemaCapabilitiesItems, optional)
- `claudeManagedConfig` (V1AgentsPostRequestBodyContentApplicationJsonSchemaClaudeManagedConfig, optional)
- `config` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfig, optional)
- `description` (string, optional)
- `externalConfig` (V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfig, optional)
- `icon` (string, optional)
- `maxTurns` (integer, optional)
- `primaryFlowId` (any, optional, deprecated) — primaryFlowId is retired: primary-flow agents were removed (ADR 0024). Attach the flow to the agent as a runtime tool (\{ toolType: 'flow', flowId }) or dispatch the flow directly via POST /v1/dispatch.

## Response

### 201

Agent created

- `agentType` (string, required)
- `capabilities` (list of V1AgentsPostResponsesContentApplicationJsonSchemaCapabilitiesItems, required)
- `claudeManagedConfig` (map from string to any, required, nullable)
- `config` (map from string to any, required, nullable)
- `configHash` (string, required, nullable)
- `createdAt` (string, required)
- `description` (string, required, nullable)
- `draftVersionId` (string, required, nullable)
- `externalConfig` (map from string to any, required, nullable) — External-agent configuration. Configured auth.credentials values are write-only and returned as \<redacted>, never plaintext.
- `healthStatus` (string, required, nullable)
- `icon` (string, required, nullable)
- `id` (string, required)
- `lastHealthCheckAt` (string, required, nullable)
- `lastModifiedSource` (string, required, nullable)
- `name` (string, required)
- `organizationId` (string, required, nullable)
- `publishedVersionId` (string, required, nullable)
- `status` (string, required)
- `updatedAt` (string, required)
- `userId` (string, required)
- `_warnings` (list of string, optional)
- `dashboardUrl` (string, optional)
- `sandboxCapabilityIssues` (list of V1AgentsPostResponsesContentApplicationJsonSchemaSandboxCapabilityIssuesItems, optional)

## Errors

### 400 Bad Request Error

Validation error

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 401 Unauthorized Error

Unauthorized

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 402 Payment Required Error

Feature not available

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 403 Forbidden Error

Insufficient permissions

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 404 Not Found Error

Feature not available in production

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

### 500 Internal Server Error

Internal server error

- `error` (string, required)
- `code` (string, optional) — Stable error code. `insufficient_scope` marks an API key that lacks a scope this request needs.
- `details` (list of ErrorDetailsItems, optional)
- `requiredScopes` (list of string, optional) — On `insufficient_scope`: every API key scope this request needs.

## Types

### V1AgentsPostRequestBodyContentApplicationJsonSchemaCapabilitiesItems

- `toolName` (string, required)
- `enabled` (boolean, optional)
- `flowId` (string, optional)
- `parametersSchema` (any, optional)
- `subAgentId` (string, optional)
- `toolDescription` (string, optional)
- `toolId` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaClaudeManagedConfig

- `setupMode` (enum, required)
  - Allowed values: `create`, `connect`
- `anthropicAgentId` (string, optional)
- `anthropicAgentVersion` (integer, optional)
- `anthropicEnvironmentId` (string, optional)
- `cachedAgentInfo` (V1AgentsPostRequestBodyContentApplicationJsonSchemaClaudeManagedConfigCachedAgentInfo, optional)
- `customTools` (list of V1AgentsPostRequestBodyContentApplicationJsonSchemaClaudeManagedConfigCustomToolsItems, optional)
- `mcpServers` (list of V1AgentsPostRequestBodyContentApplicationJsonSchemaClaudeManagedConfigMcpServersItems, optional)
- `model` (string, optional)
- `outputHandoff` (boolean, optional) — Scheduled and batch runs only. When true, files the agent writes to /mnt/session/outputs/ are stored as runtype-asset:// handles and the session is resumed for one delivery turn that lists them (for example, to attach them with send_email).
- `systemPrompt` (string, optional)
- `timeoutMs` (integer, optional, nullable)
- `toolPermissions` (V1AgentsPostRequestBodyContentApplicationJsonSchemaClaudeManagedConfigToolPermissions, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfig

- `advisor` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigAdvisor, optional, nullable)
- `artifacts` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigArtifacts, optional)
- `busyMessageRouting` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigBusyMessageRouting, optional)
- `contextManagement` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigContextManagement, optional)
- `durability` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigDurability, optional)
- `errorHandling` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigErrorHandling, optional)
- `frequencyPenalty` (double, optional)
- `loggingPolicy` (enum, optional)
  - Allowed values: `default`, `on`, `off`
- `loopConfig` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigLoopConfig, optional)
- `maxTokens` (integer, optional)
- `memory` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigMemory, optional)
- `model` (string, optional)
- `piiRedaction` (enum, optional)
  - Allowed values: `default`, `off`, `redact`
- `presencePenalty` (double, optional)
- `reasoning` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigReasoning, optional)
- `sandbox` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigSandbox, optional)
- `seed` (integer, optional)
- `state` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigState, optional)
- `systemPrompt` (string, optional)
- `temperature` (double, optional)
- `temporal` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigTemporal, optional)
- `tenancyStrategy` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigTenancyStrategy, optional)
- `tools` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigTools, optional)
- `topK` (integer, optional)
- `topP` (double, optional)
- `voice` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoice, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfig

- `endpoint` (string, required)
- `agentCardUrl` (string, optional)
- `auth` (V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigAuth, optional)
- `cachedAgentCard` (V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigCachedAgentCard, optional)
- `deviceId` (string, optional)
- `framework` (enum, optional)
  - Allowed values: `langchain`, `vercel_ai`, `crewai`, `cloudflare`, `autogen`, `flue`, `mastra`, `custom`
- `identityAssertion` (boolean, optional) — Send a short-lived, Runtype-signed identity assertion (ES256 JWT, `aud` = endpoint host) in the `X-Runtype-Identity` header. Requires a tenancy strategy and a resolved tenant or end user; a call without one is refused before it reaches the agent.
- `protocol` (enum, optional)
  - Allowed values: `a2a`, `runtype-stream`
- `retryCount` (integer, optional)
- `skillOrchestration` (V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigSkillOrchestration, optional)
- `skillOrchestrator` (V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigSkillOrchestrator, optional)
- `skillsOverride` (list of V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigSkillsOverrideItems, optional)
- `timeoutMs` (integer, optional)
- `transport` (enum, optional)
  - Allowed values: `http`, `device`

### V1AgentsPostResponsesContentApplicationJsonSchemaCapabilitiesItems

- `displayOrder` (integer, required, nullable)
- `enabled` (boolean, required)
- `flowId` (string, required, nullable)
- `id` (string, required)
- `subAgentId` (string, required, nullable)
- `toolDescription` (string, required, nullable)
- `toolId` (string, required, nullable)
- `toolName` (string, required)
- `agentId` (string, optional)
- `createdAt` (string, optional)
- `parametersSchema` (any, optional)

### V1AgentsPostResponsesContentApplicationJsonSchemaSandboxCapabilityIssuesItems

- `code` (enum, required)
  - Allowed values: `unsupported_sandbox_capability`
- `message` (string, required)
- `path` (string, required)
- `requested` (string, required)
- `supported` (list of string, required)

### ErrorDetailsItems

- `message` (string, required)
- `code` (string, optional) — Stable Runtype validation code (e.g. MISSING_REQUIRED_FIELD, INVALID_ENUM).
- `path` (string, optional) — Dotted JSON path to the offending field.
- `suggestion` (string, optional) — Actionable hint (allowed values, accepted range, …).

### V1AgentsPostRequestBodyContentApplicationJsonSchemaClaudeManagedConfigCachedAgentInfo

- `description` (string, optional)
- `fetchedAt` (string, optional)
- `model` (string, optional)
- `name` (string, optional)
- `tools` (list of V1AgentsPostRequestBodyContentApplicationJsonSchemaClaudeManagedConfigCachedAgentInfoToolsItems, optional)
- `version` (double, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaClaudeManagedConfigCustomToolsItems

- `capabilityId` (string, required)
- `toolDescription` (string, required)
- `toolName` (string, required)
- `parametersSchema` (map from string to any, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaClaudeManagedConfigMcpServersItems

- `url` (string, required)
- `name` (string, optional)
- `target` (any, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaClaudeManagedConfigToolPermissions

- `bash` (boolean, optional)
- `edit` (boolean, optional)
- `glob` (boolean, optional)
- `grep` (boolean, optional)
- `read` (boolean, optional)
- `webFetch` (boolean, optional)
- `webSearch` (boolean, optional)
- `write` (boolean, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigAdvisor

- `model` (string, required)
- `systemPrompt` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigArtifacts

- `enabled` (boolean, required)
- `types` (list of enum, required)
  - Allowed values: `markdown`, `component`

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigBusyMessageRouting

- `classifierModel` (string, optional)
- `mode` (enum, optional)
  - Allowed values: `enforced`, `off`

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigContextManagement

- `compaction` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigContextManagementCompaction, optional)
- `toolResults` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigContextManagementToolResults, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigDurability

- `forced` (enum, optional)
  - Allowed values: `durable`, `in_process`
- `maxBudgetMs` (integer, optional, nullable)
- `watchLeaseMs` (integer, optional, nullable)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigErrorHandling

- `onError` (enum, required)
  - Allowed values: `fail`, `continue`, `fallback`
- `fallbacks` (list of V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigErrorHandlingFallbacksItems, optional)
- `triggers` (list of V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigErrorHandlingTriggersItems, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigLoopConfig

- `enableReflection` (boolean, optional)
- `maxCost` (double, optional)
- `maxTurns` (integer, optional)
- `reflectionInterval` (integer, optional)
- `treatLengthCutoffAsFailure` (boolean, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigMemory

- `enabled` (boolean, required)
- `injectSummary` (boolean, optional)
- `pointerScope` (enum, optional)
  - Allowed values: `shared`, `alias`, `version`
- `profileTemplate` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigReasoning

- boolean
- V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigReasoning1

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigSandbox

- `enabled` (boolean, required)
- `codingAgents` (list of enum, optional) — Coding agents the Sandbox can run as typed sessions. Non-empty adds the agent_session_* tools; empty or absent adds none.
  - Allowed values: `opencode`
- `instanceType` (enum, optional) — Only standard-4 is supported on the hosted Agent Sandbox path; other sizes cannot be enabled.
  - Allowed values: `standard-1`, `standard-2`, `standard-3`, `standard-4`
- `networkAccess` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigSandboxNetworkAccess, optional)
- `persistence` (enum, optional) — Supported: ephemeral or conversation. Named remains parseable for stored configs but cannot be enabled.
  - Allowed values: `ephemeral`, `conversation`, `named`
- `provider` (enum, optional) — Only runtype-sandbox is currently supported. Daytona is retained for stored-config parsing but rejected at authoring/execution.
  - Allowed values: `runtype-sandbox`, `daytona`
- `secretEnv` (map from string to string, optional)
- `setupCommands` (list of string, optional)
- `sleepAfter` (enum, optional)
  - Allowed values: `5m`, `15m`, `30m`, `1h`
- `ttl` (enum, optional)
  - Allowed values: `5m`, `1h`, `24h`, `unlimited`

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigState

- `initial` (map from string to any, optional)
- `mergeStrategy` (enum, optional, default: merge)
  - Allowed values: `replace`, `merge`
- `predictState` (list of V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigStatePredictStateItems, optional)
- `schema` (map from string to any, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigTemporal

- `elapsedThresholdSeconds` (integer, optional)
- `groundNow` (boolean, optional)
- `injectElapsed` (boolean, optional)
- `timezone` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigTenancyStrategy

- `preset` (enum, required)
  - Allowed values: `internal`, `tenant-isolated`, `end-user-isolated`
- `assuranceFloor` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigTenancyStrategyAssuranceFloor, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigTools

- `approval` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsApproval, optional)
- `codeModeConfig` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsCodeModeConfig, optional)
- `intent` (enum, optional)
  - Allowed values: `mandatory`, `best-effort`
- `maxToolCalls` (integer, optional)
- `mcpServers` (list of V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsMcpServersItems, optional)
- `perToolLimits` (map from string to V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsPerToolLimits, optional)
- `runtimeTools` (list of V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsRuntimeToolsItems, optional)
- `subagentConfig` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsSubagentConfig, optional)
- `toolCallStrategy` (enum, optional)
  - Allowed values: `auto`, `required`, `none`
- `toolConfigs` (map from string to map from string to any, optional)
- `toolIds` (list of string, optional)
- `toolSearch` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsToolSearch, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoice

- `directTools` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceDirectTools, optional)
- `disclosure` (boolean, optional)
- `elevenLabs` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceElevenLabs, optional)
- `enabled` (boolean, optional)
- `endpointing` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceEndpointing, optional)
- `greeting` (string, optional)
- `interruptionMode` (enum, optional)
  - Allowed values: `none`, `cancel`, `barge-in`
- `language` (string, optional)
- `provider` (string, optional)
- `speech` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceSpeech, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigAuth

- `type` (enum, required)
  - Allowed values: `none`, `bearer`, `api_key`, `basic`
- `credentials` (string, optional)
- `headerName` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigCachedAgentCard

- `capabilities` (V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigCachedAgentCardCapabilities, optional)
- `description` (string, optional)
- `fetchedAt` (string, optional)
- `name` (string, optional)
- `protocolVersion` (string, optional)
- `skills` (list of V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigCachedAgentCardSkillsItems, optional)
- `version` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigSkillOrchestration

- enum
  - Allowed values: `delegate`, `managed`
- enum
  - Allowed values: `agent_skill`, `runtype`, `none`

### V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigSkillOrchestrator

- `model` (string, required)
- `frequencyPenalty` (double, optional)
- `presencePenalty` (double, optional)
- `reasoning` (V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigSkillOrchestratorReasoning, optional)
- `seed` (integer, optional)
- `systemPrompt` (string, optional)
- `temperature` (double, optional)
- `topK` (integer, optional)
- `topP` (double, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigSkillsOverrideItems

- `enabled` (boolean, required)
- `id` (string, required)
- `exposedDescription` (string, optional)
- `exposedName` (string, optional)
- `isNew` (boolean, optional)
- `role` (enum, optional)
  - Allowed values: `orchestrator`, `tool`, `standalone`, `hidden`

### V1AgentsPostRequestBodyContentApplicationJsonSchemaClaudeManagedConfigCachedAgentInfoToolsItems

- `type` (string, required)
- `name` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigContextManagementCompaction

- `enabled` (boolean, optional)
- `instructions` (string, optional)
- `model` (string, optional)
- `retainRecentTokens` (integer, optional)
- `strategy` (enum, optional)
  - Allowed values: `auto`, `provider_native`, `summary`
- `thresholdRatio` (double, optional)
- `thresholdTokens` (integer, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigContextManagementToolResults

- `pruneHotWindowTokens` (integer, optional)
- `pruneMode` (enum, optional)
  - Allowed values: `mask`, `off`
- `inlineThresholdChars` (integer, optional, deprecated) — Deprecated and ignored. Tool results are never spilled.

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigErrorHandlingFallbacksItems

- V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigErrorHandlingFallbacksItems0
- V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigErrorHandlingFallbacksItems1
- V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigErrorHandlingFallbacksItems2

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigErrorHandlingTriggersItems

- `type` (enum, required)
  - Allowed values: `error`, `empty-output`

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigReasoning1

- `enabled` (boolean, required)
- `budgetTokens` (integer, optional)
- `effort` (string, optional)
- `includeThoughts` (boolean, optional)
- `reasoningEffort` (enum, optional)
  - Allowed values: `minimal`, `low`, `medium`, `high`, `xhigh`, `max`
- `reasoningSummary` (enum, optional)
  - Allowed values: `auto`, `detailed`
- `thinkingBudget` (integer, optional)
- `thinkingLevel` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigSandboxNetworkAccess

- enum
  - Allowed values: `none`, `essentials`, `open`
- V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigSandboxNetworkAccess1

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigStatePredictStateItems

- `stateKey` (string, required)
- `tool` (string, required)
- `toolArgument` (string, required)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigTenancyStrategyAssuranceFloor

- `endUser` (enum, optional)
  - Allowed values: `asserted`, `verified`
- `tenant` (enum, optional)
  - Allowed values: `asserted`, `verified`

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsApproval

- `require` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsApprovalRequire, required)
- `approver` (enum, optional)
  - Allowed values: `owner`, `end-user`
- `choices` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsApprovalChoices, optional)
- `requestReason` (boolean, optional)
- `timeout` (double, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsCodeModeConfig

- `toolPool` (list of string, required)
- `description` (string, optional)
- `timeoutMs` (integer, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsMcpServersItems

- `id` (string, required)
- `allowedTools` (list of string, optional)
- `auth` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsMcpServersItemsAuth, optional)
- `enabled` (boolean, optional)
- `identityAudiences` (list of string, optional)
- `name` (string, optional)
- `target` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsMcpServersItemsTarget, optional)
- `timeout` (double, optional)
- `transport` (enum, optional)
  - Allowed values: `streamable_http`, `rest`
- `url` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsPerToolLimits

- `maxCalls` (double, optional)
- `required` (boolean, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsRuntimeToolsItems

- `config` (map from string to any, required)
- `description` (string, required)
- `name` (string, required)
- `parametersSchema` (map from string to any, required)
- `toolType` (enum, required)
  - Allowed values: `flow`, `custom`, `external`, `local`, `advisor`, `subagent`, `search`
- `hiddenParameterNames` (list of string, optional)
- `idempotent` (boolean, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsSubagentConfig

- `toolPool` (list of string, required)
- `allowNesting` (boolean, optional)
- `defaultExecutionMode` (enum, optional)
  - Allowed values: `attached`, `detached`
- `defaultMaxTurns` (integer, optional)
- `defaultModel` (string, optional)
- `defaultNotify` (enum, optional)
  - Allowed values: `none`, `narrate`, `react`
- `defaultTimeoutMs` (integer, optional)
- `detachedMaxBudgetMs` (integer, optional)
- `detachedNoProgressBudgetMs` (integer, optional)
- `executionModes` (list of enum, optional)
  - Allowed values: `attached`, `detached`
- `maxSpawnsPerRun` (integer, optional)
- `maxTurnsLimit` (integer, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsToolSearch

- `alwaysLoaded` (list of string, optional)
- `enabled` (boolean, optional)
- `threshold` (double, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceDirectTools

- `enabled` (boolean, optional)
- `model` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceElevenLabs

- `modelId` (string, optional)
- `similarity` (double, optional)
- `stability` (double, optional)
- `voiceId` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceEndpointing

- `strategy` (enum, required)
  - Allowed values: `provider_vad`, `server_vad`, `client_commit`, `manual`
- `silenceMs` (integer, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceSpeech

- `mode` (enum, required)
  - Allowed values: `pipeline`, `speech_to_speech`, `provider_managed`
- `synthesizer` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceSpeechSynthesizer, required)
- `transcriber` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceSpeechTranscriber, required)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigCachedAgentCardCapabilities

- `pushNotifications` (boolean, optional)
- `statefulness` (enum, optional)
  - Allowed values: `none`, `task`, `session`
- `streaming` (boolean, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigCachedAgentCardSkillsItems

- `id` (string, required)
- `name` (string, required)
- `description` (string, optional)
- `inputSchema` (map from string to any, optional)
- `outputSchema` (map from string to any, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigSkillOrchestratorReasoning

- boolean
- V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigSkillOrchestratorReasoning1

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigErrorHandlingFallbacksItems0

- `type` (enum, required)
  - Allowed values: `retry`
- `delay` (integer, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigErrorHandlingFallbacksItems1

- `model` (string, required)
- `type` (enum, required)
  - Allowed values: `model`
- `delay` (integer, optional)
- `maxTokens` (integer, optional)
- `temperature` (double, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigErrorHandlingFallbacksItems2

- `message` (string, required)
- `type` (enum, required)
  - Allowed values: `message`
- `delay` (integer, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigSandboxNetworkAccess1

- `allow` (list of string, optional)
- `profile` (enum, optional)
  - Allowed values: `none`, `essentials`, `open`

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsApprovalRequire

- list of string
- boolean

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsApprovalChoices

- `alwaysAllow` (boolean, optional)
- `alwaysDeny` (boolean, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsMcpServersItemsAuth

- `type` (enum, required)
  - Allowed values: `api_key`, `bearer`, `basic`, `custom_header`, `headers`, `none`
- `headerName` (string, optional)
- `headers` (map from string to string, optional)
- `password` (string, optional)
- `token` (string, optional)
- `username` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigToolsMcpServersItemsTarget

- `deploymentId` (string, required)
- `kind` (enum, required)
  - Allowed values: `sandbox-deployment`
- `bearerSecretName` (string, optional)
- `path` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceSpeechSynthesizer

- `provider` (string, required)
- `model` (string, optional)
- `settings` (V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceSpeechSynthesizerSettings, optional)
- `voiceId` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceSpeechTranscriber

- `provider` (string, required)
- `model` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaExternalConfigSkillOrchestratorReasoning1

- `enabled` (boolean, required)
- `budgetTokens` (integer, optional)
- `effort` (string, optional)
- `includeThoughts` (boolean, optional)
- `reasoningEffort` (enum, optional)
  - Allowed values: `minimal`, `low`, `medium`, `high`, `xhigh`, `max`
- `reasoningSummary` (enum, optional)
  - Allowed values: `auto`, `detailed`
- `thinkingBudget` (integer, optional)
- `thinkingLevel` (string, optional)

### V1AgentsPostRequestBodyContentApplicationJsonSchemaConfigVoiceSpeechSynthesizerSettings

- `similarity` (double, optional)
- `stability` (double, optional)

## Examples

**Request**

```json
{
  "name": "My New Agent",
  "agentType": "runtype",
  "config": {
    "frequencyPenalty": 0.2,
    "loopConfig": {
      "maxTurns": 10
    },
    "model": "gpt-4",
    "presencePenalty": 0.1,
    "seed": 123,
    "systemPrompt": "You are a helpful customer support agent",
    "temperature": 0.7,
    "topK": 40,
    "topP": 0.9
  },
  "description": "An AI agent for customer support"
}
```

**Response**

```json
{
  "agentType": "string",
  "capabilities": [
    {
      "displayOrder": 1,
      "enabled": true,
      "flowId": "string",
      "id": "string",
      "subAgentId": "string",
      "toolDescription": "string",
      "toolId": "string",
      "toolName": "string",
      "agentId": "string",
      "createdAt": "string"
    }
  ],
  "claudeManagedConfig": {},
  "config": {},
  "configHash": "string",
  "createdAt": "string",
  "description": "string",
  "draftVersionId": "string",
  "externalConfig": {},
  "healthStatus": "string",
  "icon": "string",
  "id": "string",
  "lastHealthCheckAt": "string",
  "lastModifiedSource": "string",
  "name": "string",
  "organizationId": "string",
  "publishedVersionId": "string",
  "status": "string",
  "updatedAt": "string",
  "userId": "string",
  "_warnings": [
    "string"
  ],
  "dashboardUrl": "string",
  "sandboxCapabilityIssues": [
    {
      "code": "unsupported_sandbox_capability",
      "message": "string",
      "path": "string",
      "requested": "string",
      "supported": [
        "string"
      ]
    }
  ]
}
```

**SDK Code**

```python Create Agent
import requests

url = "https://api.runtype.com/v1/agents"

payload = {
    "name": "My New Agent",
    "agentType": "runtype",
    "config": {
        "frequencyPenalty": 0.2,
        "loopConfig": { "maxTurns": 10 },
        "model": "gpt-4",
        "presencePenalty": 0.1,
        "seed": 123,
        "systemPrompt": "You are a helpful customer support agent",
        "temperature": 0.7,
        "topK": 40,
        "topP": 0.9
    },
    "description": "An AI agent for customer support"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript Create Agent
const url = 'https://api.runtype.com/v1/agents';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"name":"My New Agent","agentType":"runtype","config":{"frequencyPenalty":0.2,"loopConfig":{"maxTurns":10},"model":"gpt-4","presencePenalty":0.1,"seed":123,"systemPrompt":"You are a helpful customer support agent","temperature":0.7,"topK":40,"topP":0.9},"description":"An AI agent for customer support"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go Create Agent
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.runtype.com/v1/agents"

	payload := strings.NewReader("{\n  \"name\": \"My New Agent\",\n  \"agentType\": \"runtype\",\n  \"config\": {\n    \"frequencyPenalty\": 0.2,\n    \"loopConfig\": {\n      \"maxTurns\": 10\n    },\n    \"model\": \"gpt-4\",\n    \"presencePenalty\": 0.1,\n    \"seed\": 123,\n    \"systemPrompt\": \"You are a helpful customer support agent\",\n    \"temperature\": 0.7,\n    \"topK\": 40,\n    \"topP\": 0.9\n  },\n  \"description\": \"An AI agent for customer support\"\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby Create Agent
require 'uri'
require 'net/http'

url = URI("https://api.runtype.com/v1/agents")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"My New Agent\",\n  \"agentType\": \"runtype\",\n  \"config\": {\n    \"frequencyPenalty\": 0.2,\n    \"loopConfig\": {\n      \"maxTurns\": 10\n    },\n    \"model\": \"gpt-4\",\n    \"presencePenalty\": 0.1,\n    \"seed\": 123,\n    \"systemPrompt\": \"You are a helpful customer support agent\",\n    \"temperature\": 0.7,\n    \"topK\": 40,\n    \"topP\": 0.9\n  },\n  \"description\": \"An AI agent for customer support\"\n}"

response = http.request(request)
puts response.read_body
```

```java Create Agent
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.runtype.com/v1/agents")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"My New Agent\",\n  \"agentType\": \"runtype\",\n  \"config\": {\n    \"frequencyPenalty\": 0.2,\n    \"loopConfig\": {\n      \"maxTurns\": 10\n    },\n    \"model\": \"gpt-4\",\n    \"presencePenalty\": 0.1,\n    \"seed\": 123,\n    \"systemPrompt\": \"You are a helpful customer support agent\",\n    \"temperature\": 0.7,\n    \"topK\": 40,\n    \"topP\": 0.9\n  },\n  \"description\": \"An AI agent for customer support\"\n}")
  .asString();
```

```php Create Agent
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.runtype.com/v1/agents', [
  'body' => '{
  "name": "My New Agent",
  "agentType": "runtype",
  "config": {
    "frequencyPenalty": 0.2,
    "loopConfig": {
      "maxTurns": 10
    },
    "model": "gpt-4",
    "presencePenalty": 0.1,
    "seed": 123,
    "systemPrompt": "You are a helpful customer support agent",
    "temperature": 0.7,
    "topK": 40,
    "topP": 0.9
  },
  "description": "An AI agent for customer support"
}',
  'headers' => [
    'Authorization' => 'Bearer <token>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp Create Agent
using RestSharp;

var client = new RestClient("https://api.runtype.com/v1/agents");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <token>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"name\": \"My New Agent\",\n  \"agentType\": \"runtype\",\n  \"config\": {\n    \"frequencyPenalty\": 0.2,\n    \"loopConfig\": {\n      \"maxTurns\": 10\n    },\n    \"model\": \"gpt-4\",\n    \"presencePenalty\": 0.1,\n    \"seed\": 123,\n    \"systemPrompt\": \"You are a helpful customer support agent\",\n    \"temperature\": 0.7,\n    \"topK\": 40,\n    \"topP\": 0.9\n  },\n  \"description\": \"An AI agent for customer support\"\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift Create Agent
import Foundation

let headers = [
  "Authorization": "Bearer <token>",
  "Content-Type": "application/json"
]
let parameters = [
  "name": "My New Agent",
  "agentType": "runtype",
  "config": [
    "frequencyPenalty": 0.2,
    "loopConfig": ["maxTurns": 10],
    "model": "gpt-4",
    "presencePenalty": 0.1,
    "seed": 123,
    "systemPrompt": "You are a helpful customer support agent",
    "temperature": 0.7,
    "topK": 40,
    "topP": 0.9
  ],
  "description": "An AI agent for customer support"
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.runtype.com/v1/agents")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```