Agents
Manage AI agents within a workspace. Agents define AI behavior and tool access.
List agents
Create a new agent
Get an agent by ID
Delete an agent
Update an agent
ModelsExpand Collapse
type Agent struct{…}
Agent resource
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec AgentSpec
Agent specification (user-provided configuration)
VariationSelectionMode AgentSpecVariationSelectionMode
Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified
InputDataSchema map[string, unknown]Optional
InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as 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 map[string, unknown]Optional
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.
AgentInfo contains simple information about an agent for display or quick reference
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
Spec ProfileSpec
type AgentInfo struct{…}
AgentInfo contains simple information about an agent for display or quick reference
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
Spec ProfileSpec
type AgentSpec struct{…}
Agent specification (user-provided configuration)
VariationSelectionMode AgentSpecVariationSelectionMode
Controls how variations are automatically selected when creating objectives Defaults to RANDOM when unspecified
InputDataSchema map[string, unknown]Optional
InputDataSchema is used for enforcing a data input when objectives are created. This is valuable when using liquid formatting in agent variation prompts. Input data schema is also valuable when using an agent as a sub-agent, as the schema is used as 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 map[string, unknown]Optional
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.
AgentsFeedback
Manage AI agents within a workspace. Agents define AI behavior and tool access.
List feedback for an agent
AgentsWebhook Deliveries
Manage AI agents within a workspace. Agents define AI behavior and tool access.
List webhook deliveries
ModelsExpand Collapse
type WebhookDelivery struct{…}
Data WebhookDeliveryData
Webhook delivery details.
EventType WebhookDeliveryDataEventType
The type of objective event that triggered this webhook delivery
Status WebhookDeliveryDataStatus
Metadata OperationMetadata
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
type WebhookDeliveryData struct{…}
EventType WebhookDeliveryDataEventType
The type of objective event that triggered this webhook delivery
Status WebhookDeliveryDataStatus
AgentsVariations
Manage variations of an agent and their tool, sub-agent, and memory layer assignments.
List variations
Create a new variation
Get a variation by ID
Delete a variation
Update a variation
Add an assignment to a variation
Remove an assignment from a variation
Attach a memory layer to a variation
Update a variation's memory layer assignment
Remove a memory layer assignment from a variation
ModelsExpand Collapse
type AgentVariation struct{…}
AgentVariation resource
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec AgentVariationSpec
AgentVariationSpec defines the operational configuration for a variation
Description stringOptional
Human-readable description of what this variation does or when it should be used
EnableEpisodicMemory boolOptional
Enable episodic memory for objectives using this variation. When true, the system automatically creates a document namespace for each objective using the objective’s episodic_key as the external_id, allowing the agent to store and retrieve documents specific to that episode.
EpisodicMemoryTtl int64Optional
How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely.
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.
RerankThreshold float64Optional
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
AgentVariationInfo provides read-only summary information about a variation
All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation’s full assignment list without calling the add/remove endpoints just to enumerate.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
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
Spec ProfileSpec
FeedbackCount int64Optional
Total number of objective feedbacks received for this variation
Read-only list of memory layer assignments for this variation,
returned in ascending position (bottom → top). Capped at 10 entries.
ID stringOptional
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
Position int64Optional
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
type AgentVariationInfo struct{…}
AgentVariationInfo provides read-only summary information about a variation
All tools, tool sets, and sub-agents assigned to this variation. Populated on reads so clients can render a variation’s full assignment list without calling the add/remove endpoints just to enumerate.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
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
Spec ProfileSpec
FeedbackCount int64Optional
Total number of objective feedbacks received for this variation
Read-only list of memory layer assignments for this variation,
returned in ascending position (bottom → top). Capped at 10 entries.
ID stringOptional
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
Position int64Optional
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
type AgentVariationSpec struct{…}
AgentVariationSpec defines the operational configuration for a variation
Description stringOptional
Human-readable description of what this variation does or when it should be used
EnableEpisodicMemory boolOptional
Enable episodic memory for objectives using this variation. When true, the system automatically creates a document namespace for each objective using the objective’s episodic_key as the external_id, allowing the agent to store and retrieve documents specific to that episode.
EpisodicMemoryTtl int64Optional
How long episodic memories should be retained. After this duration, episodic document namespaces can be automatically cleaned up. If not set, episodic memories are retained indefinitely.
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.
RerankThreshold float64Optional
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
type AgentVariationSpecCompactionConfig struct{…}
type AgentVariationSpecProgressiveDiscovery struct{…}
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.
RerankThreshold float64Optional
Rerank Threshold is an optional value that instructs whether or not to run a search result through a embedding/reranker process which can improve performance and reduce context bloat when tools reach the configured threshold. If a tool match must exceed 0.8, for example, the tool very closely match the query the tool search performed.
type VariationAssignment struct{…}
A read-only reference to a single tool, tool set, or sub-agent attached to
a variation. Read the full set of assignments via AgentVariationInfo.assignments;
mutations go through the dedicated add/remove assignment endpoints.
The id identifies the assignment itself (not the referenced resource) and
is the handle used to remove the assignment. It is returned by the add
endpoint and present on every entry in AgentVariationInfo.assignments.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
type VariationMemoryLayerAssignment struct{…}
VariationMemoryLayerAssignment attaches a single MemoryLayer to a variation at a given position in the variation’s baseline memory stack. A variation has at most one assignment per memory_layer_id.
Variations only support whole-layer attachments — entry pinning is an objective-level capability.
ID stringOptional
Assignment row id — handle for removing the assignment. Distinct from the referenced memory layer’s id.
BareMetadata contains the minimal metadata for a resource: the ID and an optional human-readable name. These are used for reference fields where the full metadata (account scoping, timestamps, labels, external IDs) is not needed — e.g., the tool references inside an agent variation spec or the tools assigned to an objective. Both fields are server-populated; clients provide IDs through sibling fields rather than by constructing a BareMetadata themselves.
Position int64Optional
Position in the variation’s baseline stack. Lower values sit lower; the highest-position assignment is on top of the variation’s baseline. Gaps are fine — only relative position matters. Positions must be unique within a variation; a request that would collide with an existing assignment’s position is rejected with InvalidArgument.
AgentsSchedules
Manage recurring schedules attached to agents. Schedules trigger objectives on a cadence defined by AgentScheduleSpec.Schedule.
List schedules
Create a new schedule
Get a schedule by ID
Delete a schedule
Update a schedule
ModelsExpand Collapse
type AgentSchedule struct{…}
AgentSchedule resource — a recurring trigger attached to an agent that creates objectives on its cadence.
Metadata ResourceMetadata
Standard metadata for persistent, named resources (e.g., agents, tools, prompts)
Name string
Human-readable name for the resource (e.g., “Customer Support Agent”, “Email Tool”) Required for resources that users interact with directly
Spec AgentScheduleSpec
AgentScheduleSpec is the user-provided configuration for a schedule.
InitialMessage string
The initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history.
Schedule AgentScheduleSpecSchedule
Data unknownOptional
Optional input data passed to the objective. If the agent has an input_data_schema, this must satisfy it.
OverlapPolicy AgentScheduleSpecOverlapPolicyOptional
What to do when the previous run is still in flight. Defaults to SKIP.
Status AgentScheduleSpecStatusOptional
Lifecycle. Defaults to ACTIVE on create when unspecified.
AgentScheduleInfo provides read-only runtime data about a schedule.
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
Spec ProfileSpec
LastFireAt TimeOptional
When the schedule last fired (regardless of objective outcome).
LastSkippedAt TimeOptional
When the schedule most recently skipped a fire (SKIP policy + prior in flight).
LastSkipReason stringOptional
Reason for the most recent skip (e.g. “previous objective still running”).
type AgentScheduleInfo struct{…}
AgentScheduleInfo provides read-only runtime data about a schedule.
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
Spec ProfileSpec
LastFireAt TimeOptional
When the schedule last fired (regardless of objective outcome).
LastSkippedAt TimeOptional
When the schedule most recently skipped a fire (SKIP policy + prior in flight).
LastSkipReason stringOptional
Reason for the most recent skip (e.g. “previous objective still running”).
type AgentScheduleSpec struct{…}
AgentScheduleSpec is the user-provided configuration for a schedule.
InitialMessage string
The initial message passed to CreateObjective on each fire. Becomes the first user message in the objective’s chat history.
Schedule AgentScheduleSpecSchedule
Data unknownOptional
Optional input data passed to the objective. If the agent has an input_data_schema, this must satisfy it.
OverlapPolicy AgentScheduleSpecOverlapPolicyOptional
What to do when the previous run is still in flight. Defaults to SKIP.
Status AgentScheduleSpecStatusOptional
Lifecycle. Defaults to ACTIVE on create when unspecified.