Objectives
List objectives
Create a new objective
Get an objective by ID
List objective events
Continue an objective
Cancel an objective
Compact an objective
List objective context windows
ModelsExpand Collapse
type AssistantMessage struct{…}
CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).
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
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
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 AssistantToolCall struct{…}
CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).
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
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
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 CallableTool struct{…}
CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).
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
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
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 ContextWindowCompacted struct{…}
The new context window created by this compaction
CompletionTokens int64Optional
A calculated value for how many completion tokens (output tokens) have been used in this context window
PreviousWindowContinueInstructions stringOptional
The instructions for this window to continue from a previous window’s chat history.
type MemoryRead struct{…}
MemoryRead is emitted each time the agent resolves a key against the memory stack and loads an entry. Lookups that miss (key not found in any layer) do not emit this event.
type MemoryReference struct{…}
MemoryReference identifies a memory layer or a specific entry within one, for composition into a memory stack. Used on objectives (where entry pinning is permitted).
memory_layer_id accepts both the canonical form (memlyr_…) and the external-id form (external_id:my-custom-id). The same applies to memory_entry_id when set.
type Objective struct{…}
Data ObjectiveData
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
Data unknownOptional
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
InitialMessage stringOptional
The initial message sent to the agent. This becomes the first user message in the LLM chat history.
Memory layers/entries to push onto this objective’s memory stack on top of the baseline stack inherited from the selected variation.
Array order is push order: the first element sits lower in the objective’s contribution to the stack; the LAST element ends up on top of the effective stack. Entries pinned via memory_entry_id behave as single-entry layers at their position.
System-managed layers (e.g., episodic) cannot be referenced here; they attach themselves automatically based on episodic_key.
Stack size cap: the TOTAL effective stack (variation’s memory layers
- this field) must not exceed 10 entries. A request that would produce an effective stack larger than 10 is rejected with InvalidArgument.
Output map[string, unknown]Optional
The output of the objective, populated when the objective completes. Will match the schema of output_json_schema or output_json_inferred.
OutputDefinition map[string, unknown]Optional
Snapshot of the agent spec’s output_definition at objective creation time. When present, the objective will run an extraction step after the LLM finishes.
ParentObjectiveID stringOptional
A parent objective means the objective was spawned off using a separate agent to complete an objective
SourceScheduleID stringOptional
ID of the AgentSchedule that produced this objective, when applicable. Populated when the objective is created from a schedule fire; empty when the objective was created via CreateObjective directly.
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
Metadata OperationMetadata
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
Status ObjectiveStatus
ObjectiveInfo provides read-only aggregated statistics about an objective’s execution
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
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
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
The effective memory stack at objective creation time, flattened from the variation’s baseline plus ObjectiveData.memory_stack. Order is push order (last = top). Returned on reads so clients can see exactly what stack the objective is using without having to re-join variation state.
TotalContextWindows int64Optional
Total number of context windows that this objective has generated
TotalEvents int64Optional
Total number of events generated during this objective’s execution
TotalInputTokens int64Optional
Total input tokens consumed across all LLM completions across all context windows
Read-only list of the last five windows of execution for this objective, ordered by most recent first. Is only included in singular RPC calls (GetObjective, for example).
CompletionTokens int64Optional
A calculated value for how many completion tokens (output tokens) have been used in this context window
PreviousWindowContinueInstructions stringOptional
The instructions for this window to continue from a previous window’s chat history.
Metadata OperationMetadata
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
Info ObjectiveContextWindowInfoOptional
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
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
type ObjectiveContextWindow struct{…}
ObjectiveContextWindow is a window of chat completions that is grouped together to prevent context-window overflows. Context windows also allow agents to compact their windows and carry on into a new one.
CompletionTokens int64Optional
A calculated value for how many completion tokens (output tokens) have been used in this context window
PreviousWindowContinueInstructions stringOptional
The instructions for this window to continue from a previous window’s chat history.
Metadata OperationMetadata
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
Info ObjectiveContextWindowInfoOptional
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
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
type ObjectiveContextWindowData struct{…}
CompletionTokens int64Optional
A calculated value for how many completion tokens (output tokens) have been used in this context window
PreviousWindowContinueInstructions stringOptional
The instructions for this window to continue from a previous window’s chat history.
type ObjectiveData 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
Data unknownOptional
Represents a dynamically typed value which can be either null, a number, a string, a boolean, a recursive struct value, or a list of values.
InitialMessage stringOptional
The initial message sent to the agent. This becomes the first user message in the LLM chat history.
Memory layers/entries to push onto this objective’s memory stack on top of the baseline stack inherited from the selected variation.
Array order is push order: the first element sits lower in the objective’s contribution to the stack; the LAST element ends up on top of the effective stack. Entries pinned via memory_entry_id behave as single-entry layers at their position.
System-managed layers (e.g., episodic) cannot be referenced here; they attach themselves automatically based on episodic_key.
Stack size cap: the TOTAL effective stack (variation’s memory layers
- this field) must not exceed 10 entries. A request that would produce an effective stack larger than 10 is rejected with InvalidArgument.
Output map[string, unknown]Optional
The output of the objective, populated when the objective completes. Will match the schema of output_json_schema or output_json_inferred.
OutputDefinition map[string, unknown]Optional
Snapshot of the agent spec’s output_definition at objective creation time. When present, the objective will run an extraction step after the LLM finishes.
ParentObjectiveID stringOptional
A parent objective means the objective was spawned off using a separate agent to complete an objective
SourceScheduleID stringOptional
ID of the AgentSchedule that produced this objective, when applicable. Populated when the objective is created from a schedule fire; empty when the objective was created via CreateObjective directly.
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 ObjectiveEventData struct{…}
CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).
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
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
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
Cancelled ObjectiveEventDataCancelledOptional
ObjectiveCancelled is the terminal event written when an objective is cancelled. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted.
The new context window created by this compaction
CompletionTokens int64Optional
A calculated value for how many completion tokens (output tokens) have been used in this context window
PreviousWindowContinueInstructions stringOptional
The instructions for this window to continue from a previous window’s chat history.
Finalized ObjectiveEventDataFinalizedOptional
ObjectiveFinalized is the terminal event written when an objective is finalized. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted.
MemoryRead is emitted each time the agent resolves a key against the memory stack and loads an entry. Lookups that miss (key not found in any layer) do not emit this event.
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
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
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 ObjectiveEventInfo struct{…}
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
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
type ObjectiveEventWebhookData struct{…}
The envelope for an objective event webhook delivery. Contains timestamp, event type, and the webhook data payload.
Data ObjectiveEventWebhookDataData
The webhook data payload with flat top-level keys for agent, variation, objective, and event.
Agent 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
AgentVariation 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
Objective OperationMetadata
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
ObjectiveEvent ObjectiveEventWebhookDataDataObjectiveEvent
Data ObjectiveEventData
CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).
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
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
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
Cancelled ObjectiveEventDataCancelledOptional
ObjectiveCancelled is the terminal event written when an objective is cancelled. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted.
The new context window created by this compaction
CompletionTokens int64Optional
A calculated value for how many completion tokens (output tokens) have been used in this context window
PreviousWindowContinueInstructions stringOptional
The instructions for this window to continue from a previous window’s chat history.
Finalized ObjectiveEventDataFinalizedOptional
ObjectiveFinalized is the terminal event written when an objective is finalized. After this event, the objective is super-terminal: no further iterations, compaction, or continuation are permitted.
MemoryRead is emitted each time the agent resolves a key against the memory stack and loads an entry. Lookups that miss (key not found in any layer) do not emit this event.
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
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
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.
Metadata OperationMetadata
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
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
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
type ObjectiveInfo struct{…}
ObjectiveInfo provides read-only aggregated statistics about an objective’s execution
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
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
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
The effective memory stack at objective creation time, flattened from the variation’s baseline plus ObjectiveData.memory_stack. Order is push order (last = top). Returned on reads so clients can see exactly what stack the objective is using without having to re-join variation state.
TotalContextWindows int64Optional
Total number of context windows that this objective has generated
TotalEvents int64Optional
Total number of events generated during this objective’s execution
TotalInputTokens int64Optional
Total input tokens consumed across all LLM completions across all context windows
type SubAgentSpawned struct{…}
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
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
type SubAgentUpdated struct{…}
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.
ObjectivesTools
List objective tools
ModelsExpand Collapse
type ObjectiveTool struct{…}
ObjectiveTool represents a tool that was assigned to an objective.
Metadata BareMetadata
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.
Snapshot of the tool at the time it was assigned to the objective. Because tools can change over time, snapshots are used to ensure tools don’t change unexpectedly during an objective’s lifecycle.
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 ToolSpec
Config ToolSpecConfig
Config defines the adapter to use for the tool. This is used to determine how the tool is called. For example, if the tool is an HTTP tool, the adapter will be Http. If the tool is an inline tool, the adapter will be Inline.
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
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
ObjectivesTool Calls
List objective tool calls
Approve a tool call
Deny a tool call
ModelsExpand Collapse
type ObjectiveToolCall struct{…}
ObjectiveToolCall is a record of a tool call made during an objective’s execution. Tool calls are mutable — their status changes as they are approved, denied, or executed.
Callable CallableTool
CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).
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
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
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
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
Metadata OperationMetadata
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
Status ObjectiveToolCallStatus
Current status of the tool call
ExecutionStatus ObjectiveToolCallExecutionStatusOptional
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
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
type ObjectiveToolCallData struct{…}
Callable CallableTool
CallableTool is a union that represents a tool that can be called by an agent. In Cadenya, a tool that is used within an agent objective might be a user-defined tool (IE: MCP, HTTP), another Agent (useful to separate context), or a Cadenya Tool (one Cadenya provides).
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
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
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
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 ObjectiveToolCallInfo struct{…}
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
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
ObjectivesTasks
List objective tasks
Get an objective task by ID
ModelsExpand Collapse
type ObjectiveTask struct{…}
ObjectiveTask represents a task within an objective, typically created and managed by an AI agent to track progress toward completing the objective.
Data ObjectiveTaskData
Metadata BareMetadata
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.
ObjectivesFeedback
Submit feedback for an objective
List feedback for an objective
ModelsExpand Collapse
type ObjectiveFeedback struct{…}
ObjectiveFeedback represents feedback submitted for an objective’s execution. Feedback is used to score agent variations and improve agent performance over time.
Metadata OperationMetadata
Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)
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
type ObjectiveFeedbackInfo struct{…}
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.