CumulusDocs
Open Studio
On this page

Create an agent

Create an agent from a template. The response includes its first draft; publish a version before running it.

Operation ID: agents.create.

Request

POST /api/v1/agents

  • TypeScript SDK: client.agents.create (path arguments use path).
  • MCP tool: sdk_client_call with operationId: "agents.create" (path arguments use input.path). Legacy alias: agents_create. Connect to your authenticated /mcp endpoint with an API key for the same environment.
  • Minimum API key role: member.
  • Idempotency: Required. Send Idempotency-Key (TypeScript SDK: idempotencyKey) and keep it for retries.

Read resource IDs from earlier responses and use a key for the same environment.

Request example

Creates an editable draft. Publish it before starting a run.

Set CUMULUS_BASE_URL to your workspace API URL and CUMULUS_API_KEY to a key for that environment. Set IDEMPOTENCY_KEY to a new UUID for this action and keep it for retries. Example values are synthetic.

cURL

curl
curl --fail-with-body -sS -X POST "${CUMULUS_BASE_URL%/}/api/v1/agents" \
  -H "Authorization: Bearer $CUMULUS_API_KEY" \
  -H "Idempotency-Key: $IDEMPOTENCY_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "name": "Ticket triage",
  "template": "cloud_task",
  "channels": [
    "cloud"
  ],
  "languages": [
    "en"
  ]
}'

TypeScript

typescript
import { Cumulus } from "@cumulus/sdk";

const baseUrl = process.env.CUMULUS_BASE_URL;
const apiKey = process.env.CUMULUS_API_KEY;
if (!baseUrl || !apiKey) throw new Error("Set CUMULUS_BASE_URL and CUMULUS_API_KEY");
const client = new Cumulus({ baseUrl, apiKey });

const idempotencyKey = process.env.IDEMPOTENCY_KEY;
if (!idempotencyKey) throw new Error("Set IDEMPOTENCY_KEY for this request");

const response = await client.agents.create({
  "body": {
    "name": "Ticket triage",
    "template": "cloud_task",
    "channels": [
      "cloud"
    ],
    "languages": [
      "en"
    ]
  },
  idempotencyKey,
});

Integration notes

Choose phone_outbound for outgoing calls, cloud_task for a task, cloud_chat for a chat or blank for an empty flow.

Read the agent ID from ref.id and the first draft’s ID and revision from draft. Edit with drafts_edit, then check the result with drafts_validate.

Input schema

Path, query and header parameters

Idempotency-Key

header parameter · Required.

Type: string. minLength: 8. maxLength: 255. pattern: ^[!-~]{8,255}$.

JSON request body

FieldType or valuesRequiredDescription and limits
namestringRequiredminLength: 1. maxLength: 256.
template"blank" · "cloud_task" · "cloud_chat" · "phone_outbound"Required—
channelsarray of "cloud" · "phone"RequiredminItems: 1.
languagesarray of "en" · "es"OptionalDefault: ["en"]. minItems: 1.
Complete OpenAPI schema
OpenAPI JSON
{
  "parameters": [
    {
      "name": "Idempotency-Key",
      "in": "header",
      "required": true,
      "schema": {
        "type": "string",
        "minLength": 8,
        "maxLength": 255,
        "pattern": "^[!-~]{8,255}$"
      }
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AgentsCreateRequest"
        }
      }
    }
  }
}

Responses

HTTP 200

Create an agent from a template (201; an idempotent replay returns 200)

application/json

FieldType or valuesRequiredDescription and limits
refobjectRequired—
ref.tenant_idstring (uuid)Requiredpattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
ref.kind"agent"Required—
ref.idstringRequiredminLength: 1. maxLength: 256. pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$.
namestringRequiredminLength: 1. maxLength: 256.
headobject or nullRequired—
head.versionintegerRequired in a non-null parentAt least 0. At most 2147483647.
head.digeststringRequired in a non-null parentpattern: ^sha256:[a-f0-9]{64}$.
head.channelsarray of "cloud" · "phone"Required in a non-null parentminItems: 1.
head.languagesarray of "en" · "es"Required in a non-null parentminItems: 1.
head.published_atstring (date-time)Required in a non-null parentpattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
draftobject or nullRequired—
draft.draft_idstring (uuid)Required in a non-null parentIdentifier of the editable draft. Read it from the agent or draft response. pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
draft.revisionintegerRequired in a non-null parentGreater than 0. At most 9007199254740991.
draft.base_versioninteger or nullRequired in a non-null parentAt least 0. At most 2147483647.
draft.published_revisioninteger or nullRequired in a non-null parentGreater than 0. At most 9007199254740991.
created_atstring (date-time)Requiredpattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
updated_atstring (date-time)RequiredThe head's publish time, else created_at: the key of the updated_desc agents.list order pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
last_runobject or nullRequiredThe most recent non-test run of any version; null when the agent never ran outside Studio tests
last_run.run_idstring (uuid)Required in a non-null parentRun identifier returned when the run was admitted. pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
last_run.created_atstring (date-time)Required in a non-null parentpattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
last_run.state"admitted" · "running" · "ending" · "completed" · "failed" · "cancelled" · "rejected" · "expired"Required in a non-null parent—
last_run.dispositionstring or nullRequired in a non-null parent—

HTTP 201

Create an agent from a template (201; an idempotent replay returns 200)

application/json

FieldType or valuesRequiredDescription and limits
refobjectRequired—
ref.tenant_idstring (uuid)Requiredpattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
ref.kind"agent"Required—
ref.idstringRequiredminLength: 1. maxLength: 256. pattern: ^[A-Za-z0-9][A-Za-z0-9_.:-]*$.
namestringRequiredminLength: 1. maxLength: 256.
headobject or nullRequired—
head.versionintegerRequired in a non-null parentAt least 0. At most 2147483647.
head.digeststringRequired in a non-null parentpattern: ^sha256:[a-f0-9]{64}$.
head.channelsarray of "cloud" · "phone"Required in a non-null parentminItems: 1.
head.languagesarray of "en" · "es"Required in a non-null parentminItems: 1.
head.published_atstring (date-time)Required in a non-null parentpattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
draftobject or nullRequired—
draft.draft_idstring (uuid)Required in a non-null parentIdentifier of the editable draft. Read it from the agent or draft response. pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
draft.revisionintegerRequired in a non-null parentGreater than 0. At most 9007199254740991.
draft.base_versioninteger or nullRequired in a non-null parentAt least 0. At most 2147483647.
draft.published_revisioninteger or nullRequired in a non-null parentGreater than 0. At most 9007199254740991.
created_atstring (date-time)Requiredpattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
updated_atstring (date-time)RequiredThe head's publish time, else created_at: the key of the updated_desc agents.list order pattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
last_runobject or nullRequiredThe most recent non-test run of any version; null when the agent never ran outside Studio tests
last_run.run_idstring (uuid)Required in a non-null parentRun identifier returned when the run was admitted. pattern: ^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$.
last_run.created_atstring (date-time)Required in a non-null parentpattern: ^(?:(?:\d\d[2468][048]|\d\d[13579][26]|\d\d0[48]|[02468][048]00|[13579][26]00)-02-29|\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\d|30)|(?:02)-(?:0[1-9]|1\d|2[0-8])))T(?:(?:[01]\d|2[0-3]):[0-5]\d:[0-5]\d(?:.\d+)?(?:Z))$.
last_run.state"admitted" · "running" · "ending" · "completed" · "failed" · "cancelled" · "rejected" · "expired"Required in a non-null parent—
last_run.dispositionstring or nullRequired in a non-null parent—

Error responses

HTTPDescription
4XXTyped error (ApiError)
5XXTyped error (ApiError)

Errors use the shared error envelope. Inspect error.code, retryable, outcome and details before retrying.

Complete OpenAPI schema
OpenAPI JSON
{
  "200": {
    "description": "Create an agent from a template (201; an idempotent replay returns 200)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AgentSummary"
        }
      }
    }
  },
  "201": {
    "description": "Create an agent from a template (201; an idempotent replay returns 200)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/AgentSummary"
        }
      }
    }
  },
  "4XX": {
    "description": "Typed error (ApiError)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  },
  "5XX": {
    "description": "Typed error (ApiError)",
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/ApiError"
        }
      }
    }
  }
}

Referenced schemas

Expand the complete OpenAPI definitions for integrations that generate their own clients.

Complete OpenAPI schema
OpenAPI JSON
{
  "components": {
    "schemas": {
      "AgentsCreateRequest": {
        "type": "object",
        "properties": {
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "template": {
            "type": "string",
            "enum": [
              "blank",
              "cloud_task",
              "cloud_chat",
              "phone_outbound"
            ]
          },
          "channels": {
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "cloud",
                "phone"
              ]
            }
          },
          "languages": {
            "default": [
              "en"
            ],
            "minItems": 1,
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "en",
                "es"
              ]
            }
          }
        },
        "required": [
          "name",
          "template",
          "channels"
        ],
        "additionalProperties": false
      },
      "AgentSummary": {
        "type": "object",
        "properties": {
          "ref": {
            "type": "object",
            "properties": {
              "tenant_id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
              },
              "kind": {
                "type": "string",
                "enum": [
                  "agent"
                ]
              },
              "id": {
                "type": "string",
                "minLength": 1,
                "maxLength": 256,
                "pattern": "^[A-Za-z0-9][A-Za-z0-9_.:-]*$"
              }
            },
            "required": [
              "tenant_id",
              "kind",
              "id"
            ],
            "additionalProperties": false
          },
          "name": {
            "type": "string",
            "minLength": 1,
            "maxLength": 256
          },
          "head": {
            "nullable": true,
            "type": "object",
            "properties": {
              "version": {
                "type": "integer",
                "minimum": 0,
                "maximum": 2147483647
              },
              "digest": {
                "type": "string",
                "pattern": "^sha256:[a-f0-9]{64}$"
              },
              "channels": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "cloud",
                    "phone"
                  ]
                }
              },
              "languages": {
                "minItems": 1,
                "type": "array",
                "items": {
                  "type": "string",
                  "enum": [
                    "en",
                    "es"
                  ]
                }
              },
              "published_at": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
              }
            },
            "required": [
              "version",
              "digest",
              "channels",
              "languages",
              "published_at"
            ],
            "additionalProperties": false
          },
          "draft": {
            "nullable": true,
            "type": "object",
            "properties": {
              "draft_id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
              },
              "revision": {
                "type": "integer",
                "minimum": 0,
                "exclusiveMinimum": true,
                "maximum": 9007199254740991
              },
              "base_version": {
                "nullable": true,
                "type": "integer",
                "minimum": 0,
                "maximum": 2147483647
              },
              "published_revision": {
                "nullable": true,
                "type": "integer",
                "minimum": 0,
                "exclusiveMinimum": true,
                "maximum": 9007199254740991
              }
            },
            "required": [
              "draft_id",
              "revision",
              "base_version",
              "published_revision"
            ],
            "additionalProperties": false
          },
          "created_at": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
          },
          "updated_at": {
            "type": "string",
            "format": "date-time",
            "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$",
            "description": "The head's publish time, else created_at: the key of the updated_desc agents.list order"
          },
          "last_run": {
            "nullable": true,
            "description": "The most recent non-test run of any version; null when the agent never ran outside Studio tests",
            "type": "object",
            "properties": {
              "run_id": {
                "type": "string",
                "format": "uuid",
                "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12})$"
              },
              "created_at": {
                "type": "string",
                "format": "date-time",
                "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"
              },
              "state": {
                "type": "string",
                "enum": [
                  "admitted",
                  "running",
                  "ending",
                  "completed",
                  "failed",
                  "cancelled",
                  "rejected",
                  "expired"
                ]
              },
              "disposition": {
                "nullable": true,
                "type": "string"
              }
            },
            "required": [
              "run_id",
              "created_at",
              "state",
              "disposition"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "ref",
          "name",
          "head",
          "draft",
          "created_at",
          "updated_at",
          "last_run"
        ],
        "additionalProperties": false
      },
      "ApiError": {
        "type": "object",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "enum": [
                  "unauthenticated",
                  "forbidden",
                  "not_found",
                  "conflict",
                  "invalid_request",
                  "idempotency_conflict",
                  "policy_denied",
                  "capability_unavailable",
                  "provider_unavailable",
                  "knowledge_unavailable",
                  "publication_invalid",
                  "run_not_active",
                  "rate_limited",
                  "outcome_unknown",
                  "internal"
                ]
              },
              "message": {
                "type": "string"
              },
              "retryable": {
                "type": "boolean"
              },
              "outcome": {
                "type": "string",
                "enum": [
                  "none",
                  "unknown"
                ]
              },
              "details": {
                "type": "object",
                "additionalProperties": {}
              }
            },
            "required": [
              "code",
              "message",
              "retryable",
              "outcome"
            ],
            "additionalProperties": false
          }
        },
        "required": [
          "error"
        ],
        "additionalProperties": false
      }
    }
  }
}

Errors and recovery

See API error handling and Troubleshooting.

Content version 7edd8807Customer SDKMarkdown source
Create an agent · Cumulus developer docs