---
title: "Create a new agent"
method: POST
path: "/v1/workspaces/{workspaceId}/agents"
tags: ["AgentService", "Agents"]
---

# Create a new agent

`POST /v1/workspaces/{workspaceId}/agents`

Creates a new agent in the workspace

## Path parameters

- `workspaceId` string, required

## Request body

- CreateAgentRequest — Create agent request
  - `workspaceId` string — Workspace ID.
  - `metadata` CreateResourceMetadata, required — CreateResourceMetadata contains the user-provided fields for creating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.
    - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
    - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
    - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"}
  - `spec` AgentSpec, required — Agent specification (user-provided configuration)
    - `description` string — Description of the agent's purpose
    - `webhookEventsUrl` string — The URL that Cadenya will send events for any objective assigned to the agent.
    - `variationSelectionMode` 'VARIATION_SELECTION_MODE_UNSPECIFIED' | 'VARIATION_SELECTION_MODE_RANDOM' | 'VARIATION_SELECTION_MODE_WEIGHTED', enum, required — Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified
    - `systemPromptDataSchema` object — SystemPromptDataSchema enforces the shape of system_prompt_data when objectives are created. This is valuable when using liquid formatting in agent variation system prompt templates. The schema is also used when the agent is attached as a sub-agent, as it becomes the tool's input parameter schema. If omitted, the sub-agent schema will be loaded with a simple "prompt" free text string as its schema.
    - `outputDefinition` object — Optional output definition for objectives created for this agent. When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here. Use this option when you want structured data to be created by your objectives.
    - `enableEpisodicMemory` boolean — Enable episodic memory for objectives created for this agent. When true, objective creation requires an episodic_memory key and the system finds or creates a memory layer for that (agent, key) pair, letting the agent store and retrieve memories across objectives that share the key. Memory is agent-level so all variations of the agent share the same layers.
    - `episodicMemoryTtl` integer — How long episodic memories should be retained. Each new objective slides the layer's expiry forward by this duration, and stored entries expire this long after they are written. If not set, episodic memories are retained indefinitely.
  - `defaultVariation` CreateAgentVariationRequest — Create agent variation request
    - `workspaceId` string — Workspace ID.
    - `agentId` string — Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.
    - `metadata` CreateResourceMetadata, required — CreateResourceMetadata contains the user-provided fields for creating a workspace-scoped resource. Read-only fields (id, account_id, workspace_id, profile_id, created_at) are excluded since they are set by the server.
      - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
      - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"}
    - `spec` AgentVariationSpec, required — AgentVariationSpec defines the operational configuration for a variation
      - `systemPromptTemplate` string — Liquid template for the system prompt of objectives using this variation. Rendered with CreateObjectiveRequest.system_prompt_data into Objective.system_prompt.
      - `progressiveDiscovery` AgentVariationSpecProgressiveDiscovery — ProgressiveDiscovery is used to indicate that the agent should automatically discover tools that are not explicitly assigned to it. Max tools is the maximum number of tools that can be discovered per search. Hints are optional hints for tool search. These are used in conjunction with the context-aware tool search and can help select the best tools for the task.
        - `maxTools` integer — The most tool names tool_search will load in a single call. Requesting more than this returns an error telling the model to retry in smaller batches -- it is a per-call batch limit, not a ceiling on how many tools an objective may end up with.
        - `hints` string[] — Free-text guidance appended to the discoverable-tools appendix in the system prompt. Hints steer the model's choice of tool names; they do not filter or rank anything, because tool_search matches names exactly rather than searching.
      - `constraints` AgentVariationSpecConstraints
        - `maxToolCalls` integer — The maximum number of tool calls that can be made. 0 means no limit.
        - `maxSubObjectives` integer — The maximum number of sub-objectives that can be created. 0 means no limit.
        - `inactivityTimeout` string — How long an objective may sit with no activity (no user messages, no LLM calls) before it is finalized as timed out. Between 1 minute and 24 hours, expressed as a duration string in seconds (e.g. "7200s"). When not set, objectives are still swept at the system-wide 24 hour maximum — every objective eventually reaches a terminal state. Note: no gnostic integer hint here on purpose. The Envoy gRPC-JSON transcoder only accepts the canonical protobuf JSON form for Durations — a "<seconds>s" string — so the SDKs must type this as a string (like AgentScheduleSpec.every), not an integer.
      - `description` string — Human-readable description of what this variation does or when it should be used
      - `modelConfig` AgentVariationSpecModelConfig — ModelConfig defines the model configuration for a variation
        - `modelId` string — The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")
        - `temperature` number, float — Sampling temperature for model inference (0.0 to 1.0) Lower values produce more deterministic outputs, higher values increase randomness
      - `compactionConfig` AgentVariationSpecCompactionConfig — CompactionConfig defines how context window compaction behaves for objectives using this variation.
        - `triggerThreshold` number, float — Trigger threshold as a percentage of the model's context window (0.0 to 1.0). When input tokens reach this percentage of the model's limit, compaction triggers. Default: 0.75 (75%)
        - `summarization` CompactionConfigSummarizationStrategy — SummarizationStrategy configures LLM-powered summarization of older conversation turns.
          - `instructions` string — Custom instructions that guide what the summarizer preserves. Replaces the default summarization prompt entirely. Example: "Preserve all code snippets, variable names, and technical decisions."
        - `toolResultClearing` CompactionConfigToolResultClearingStrategy — ToolResultClearingStrategy configures clearing of older tool result content.
          - `preserveRecentResults` integer — Number of most recent tool call results to keep intact. Older tool results have their content replaced with "[result cleared]" while preserving the assistant tool call message (function name, arguments). Default: 2
      - `firstUserMessageTemplate` string — Liquid template for the first user message of objectives using this variation. Rendered with CreateObjectiveRequest.first_user_message_data into Objective.first_user_message, the first user message in the LLM chat history. CreateObjectiveRequest.first_user_message, when set, overrides the rendered result. If neither this template nor first_user_message is present, objective creation is rejected with InvalidArgument.

## Response `200`

OK

- Agent — Agent resource
  - `metadata` ResourceMetadata, required — Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
    - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")
    - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID)
    - `workspaceId` string, required — Workspace this resource belongs to for organizational grouping (prefixed ULID)
    - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly
    - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
    - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"}
    - `profileId` string, required — ID of the actor (user or service account) that created this resource
    - `createdAt` string, date-time, required — Timestamp when this resource was created
    - `updatedAt` string, date-time — Timestamp when this resource was last updated
  - `spec` AgentSpec, required — Agent specification (user-provided configuration)
    - `description` string — Description of the agent's purpose
    - `webhookEventsUrl` string — The URL that Cadenya will send events for any objective assigned to the agent.
    - `variationSelectionMode` 'VARIATION_SELECTION_MODE_UNSPECIFIED' | 'VARIATION_SELECTION_MODE_RANDOM' | 'VARIATION_SELECTION_MODE_WEIGHTED', enum, required — Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified
    - `systemPromptDataSchema` object — SystemPromptDataSchema enforces the shape of system_prompt_data when objectives are created. This is valuable when using liquid formatting in agent variation system prompt templates. The schema is also used when the agent is attached as a sub-agent, as it becomes the tool's input parameter schema. If omitted, the sub-agent schema will be loaded with a simple "prompt" free text string as its schema.
    - `outputDefinition` object — Optional output definition for objectives created for this agent. When provided, Cadenya will append a tool to that will be called by the LLM in use by the variant to extract information in the format provided here. Use this option when you want structured data to be created by your objectives.
    - `enableEpisodicMemory` boolean — Enable episodic memory for objectives created for this agent. When true, objective creation requires an episodic_memory key and the system finds or creates a memory layer for that (agent, key) pair, letting the agent store and retrieve memories across objectives that share the key. Memory is agent-level so all variations of the agent share the same layers.
    - `episodicMemoryTtl` integer — How long episodic memories should be retained. Each new objective slides the layer's expiry forward by this duration, and stored entries expire this long after they are written. If not set, episodic memories are retained indefinitely.
  - `info` AgentInfo — AgentInfo contains simple information about an agent for display or quick reference
    - `variationCount` integer
    - `createdBy` Profile — A profile identifies a user or non-human principal (such as an API key) at the account level. Profiles are account-scoped and can be granted access to multiple workspaces.
      - `metadata` AccountResourceMetadata, required — AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.
        - `id` string, required — Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")
        - `accountId` string, required — Account this resource belongs to for multi-tenant isolation (prefixed ULID)
        - `name` string, required — Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool") Required for resources that users interact with directly
        - `externalId` string — External ID for the resource (e.g., a workflow ID from an external system)
        - `labels` object — Key-value pairs for categorization and filtering. Values are 0-63 alphanumeric characters with "-", "_", or "." allowed between; keys follow the same shape and additionally accept an optional DNS-subdomain prefix (e.g. "cadenya.com/") of at most 253 characters. Examples: {"environment": "production", "team": "platform", "version": "v2"}
        - `profileId` string, required
        - `createdAt` string, date-time
      - `spec` ProfileSpec, required — Configuration for a profile.
        - `email` string — Email address of the profile. Required and unique within an account for user profiles.
        - `name` string — Display name (e.g., "Bobby Tables").
        - `type` 'PROFILE_TYPE_UNSPECIFIED' | 'PROFILE_TYPE_USER' | 'PROFILE_TYPE_API_KEY' | 'PROFILE_TYPE_SYSTEM', enum, required — Whether this profile represents a human user, an API key, or a system principal.
  - `state` 'STATE_UNSPECIFIED' | 'STATE_DRAFT' | 'STATE_PUBLISHED' | 'STATE_ARCHIVED', enum, required — The current lifecycle state of the agent. Output only. Agents are created in STATE_DRAFT; use the :publish, :unpublish, :archive, and :unarchive actions to transition between states.

## Other responses

- `default` — Default error response

---

[API](https://skmtc.net/cadenya/apis/cadenya-api.md) · [All operations](https://skmtc.net/cadenya/apis/cadenya-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/cadenya/cadenya-api/versions/ac1a7f084068/schema)