# Agents

## List agents

`agents.list(workspace_id, **kwargs) -> CursorPagination<Agent>`

**get** `/v1/workspaces/{workspaceId}/agents`

Lists all agents in the workspace

### Parameters

- `workspace_id: String`

- `bundle_key: String`

  Filter by bundle_key — return only resources owned by this bundle.

- `cursor: String`

  Pagination cursor from previous response

- `include_info: bool`

  When true, the `info` field on each returned agent is populated. Requests
  with this flag count more against your rate limit.

- `limit: Integer`

  Maximum number of results to return

- `prefix: String`

  Filter expression (query param: prefix)

- `query: String`

  Free-form search query

- `sort_order: String`

  Sort order for results (asc or desc by creation time)

- `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

  Filter by agent publication status

  - `:AGENT_STATUS_UNSPECIFIED`

  - `:AGENT_STATUS_DRAFT`

  - `:AGENT_STATUS_PUBLISHED`

  - `:AGENT_STATUS_ARCHIVED`

- `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

  Filter by variation selection mode

  - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

  - `:VARIATION_SELECTION_MODE_RANDOM`

  - `:VARIATION_SELECTION_MODE_WEIGHTED`

### Returns

- `class Agent`

  Agent resource

  - `metadata: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentSpec`

    Agent specification (user-provided configuration)

    - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

      Status of the agent

      - `:AGENT_STATUS_UNSPECIFIED`

      - `:AGENT_STATUS_DRAFT`

      - `:AGENT_STATUS_PUBLISHED`

      - `:AGENT_STATUS_ARCHIVED`

    - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

      Controls how variations are automatically selected when creating objectives
      Defaults to RANDOM when unspecified

      - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

      - `:VARIATION_SELECTION_MODE_RANDOM`

      - `:VARIATION_SELECTION_MODE_WEIGHTED`

    - `description: String`

      Description of the agent's purpose

    - `input_data_schema: Hash[Symbol, untyped]`

      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.

    - `output_definition: Hash[Symbol, untyped]`

      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.

    - `webhook_events_url: String`

      The URL that Cadenya will send events for any objective assigned to the agent.

  - `info: AgentInfo`

    AgentInfo contains simple information about an agent for display or quick reference

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `variation_count: Integer`

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

page = cadenya.agents.list("workspaceId")

puts(page)
```

#### Response

```json
{
  "items": [
    {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "status": "AGENT_STATUS_UNSPECIFIED",
        "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED",
        "description": "description",
        "inputDataSchema": {
          "foo": "bar"
        },
        "outputDefinition": {
          "foo": "bar"
        },
        "webhookEventsUrl": "webhookEventsUrl"
      },
      "info": {
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "variationCount": 0
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

## Create a new agent

`agents.create(workspace_id, **kwargs) -> Agent`

**post** `/v1/workspaces/{workspaceId}/agents`

Creates a new agent in the workspace

### Parameters

- `workspace_id: String`

- `metadata: CreateResourceMetadata`

  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`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")

  - `bundle_key: String`

    Optional bundle ownership key. See ResourceMetadata.bundle_key.

  - `external_id: String`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}

- `spec: AgentSpec`

  Agent specification (user-provided configuration)

  - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

    Status of the agent

    - `:AGENT_STATUS_UNSPECIFIED`

    - `:AGENT_STATUS_DRAFT`

    - `:AGENT_STATUS_PUBLISHED`

    - `:AGENT_STATUS_ARCHIVED`

  - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

    Controls how variations are automatically selected when creating objectives
    Defaults to RANDOM when unspecified

    - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

    - `:VARIATION_SELECTION_MODE_RANDOM`

    - `:VARIATION_SELECTION_MODE_WEIGHTED`

  - `description: String`

    Description of the agent's purpose

  - `input_data_schema: Hash[Symbol, untyped]`

    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.

  - `output_definition: Hash[Symbol, untyped]`

    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.

  - `webhook_events_url: String`

    The URL that Cadenya will send events for any objective assigned to the agent.

- `default_variation: DefaultVariation{ metadata, spec, agent_id, workspace_id}`

  Create agent variation request

  - `metadata: CreateResourceMetadata`

    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.

  - `spec: AgentVariationSpec`

    AgentVariationSpec defines the operational configuration for a variation

    - `compaction_config: AgentVariationSpecCompactionConfig`

      CompactionConfig defines how context window compaction behaves for objectives using this variation.

      - `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."

      - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

        ToolResultClearingStrategy configures clearing of older tool result content.

        - `preserve_recent_results: 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

      - `trigger_threshold: 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%)

    - `constraints: AgentVariationSpecConstraints`

      Execution constraints

      - `max_sub_objectives: Integer`

        The maximum number of sub-objectives that can be created. 0 means no limit.

      - `max_tool_calls: Integer`

        The maximum number of tool calls that can be made. 0 means no limit.

    - `description: String`

      Human-readable description of what this variation does or when it should be used

    - `enable_episodic_memory: bool`

      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.

    - `episodic_memory_ttl: Integer`

      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.

    - `model_config: AgentVariationSpecModelConfig`

      ModelConfig defines the model configuration for a variation

      - `model_id: String`

        The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

      - `temperature: Float`

        Sampling temperature for model inference (0.0 to 1.0)
        Lower values produce more deterministic outputs, higher values increase randomness

    - `progressive_discovery: 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.

      - `hints: Array[String]`

      - `max_tools: Integer`

      - `rerank_threshold: Float`

        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.

    - `prompt: String`

      The system prompt for this variation

    - `weight: Integer`

      Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
      Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

  - `agent_id: String`

    Agent ID. Accepts the canonical `agent_…` form or the `external_id:<value>` form.

  - `workspace_id: String`

    Workspace ID.

### Returns

- `class Agent`

  Agent resource

  - `metadata: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentSpec`

    Agent specification (user-provided configuration)

    - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

      Status of the agent

      - `:AGENT_STATUS_UNSPECIFIED`

      - `:AGENT_STATUS_DRAFT`

      - `:AGENT_STATUS_PUBLISHED`

      - `:AGENT_STATUS_ARCHIVED`

    - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

      Controls how variations are automatically selected when creating objectives
      Defaults to RANDOM when unspecified

      - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

      - `:VARIATION_SELECTION_MODE_RANDOM`

      - `:VARIATION_SELECTION_MODE_WEIGHTED`

    - `description: String`

      Description of the agent's purpose

    - `input_data_schema: Hash[Symbol, untyped]`

      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.

    - `output_definition: Hash[Symbol, untyped]`

      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.

    - `webhook_events_url: String`

      The URL that Cadenya will send events for any objective assigned to the agent.

  - `info: AgentInfo`

    AgentInfo contains simple information about an agent for display or quick reference

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `variation_count: Integer`

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

agent = cadenya.agents.create(
  "workspaceId",
  metadata: {name: "name"},
  spec: {status: :AGENT_STATUS_UNSPECIFIED, variationSelectionMode: :VARIATION_SELECTION_MODE_UNSPECIFIED}
)

puts(agent)
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "status": "AGENT_STATUS_UNSPECIFIED",
    "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED",
    "description": "description",
    "inputDataSchema": {
      "foo": "bar"
    },
    "outputDefinition": {
      "foo": "bar"
    },
    "webhookEventsUrl": "webhookEventsUrl"
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "variationCount": 0
  }
}
```

## Get an agent by ID

`agents.retrieve(id, **kwargs) -> Agent`

**get** `/v1/workspaces/{workspaceId}/agents/{id}`

Retrieves an agent by ID from the workspace

### Parameters

- `workspace_id: String`

- `id: String`

### Returns

- `class Agent`

  Agent resource

  - `metadata: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentSpec`

    Agent specification (user-provided configuration)

    - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

      Status of the agent

      - `:AGENT_STATUS_UNSPECIFIED`

      - `:AGENT_STATUS_DRAFT`

      - `:AGENT_STATUS_PUBLISHED`

      - `:AGENT_STATUS_ARCHIVED`

    - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

      Controls how variations are automatically selected when creating objectives
      Defaults to RANDOM when unspecified

      - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

      - `:VARIATION_SELECTION_MODE_RANDOM`

      - `:VARIATION_SELECTION_MODE_WEIGHTED`

    - `description: String`

      Description of the agent's purpose

    - `input_data_schema: Hash[Symbol, untyped]`

      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.

    - `output_definition: Hash[Symbol, untyped]`

      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.

    - `webhook_events_url: String`

      The URL that Cadenya will send events for any objective assigned to the agent.

  - `info: AgentInfo`

    AgentInfo contains simple information about an agent for display or quick reference

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `variation_count: Integer`

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

agent = cadenya.agents.retrieve("id", workspace_id: "workspaceId")

puts(agent)
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "status": "AGENT_STATUS_UNSPECIFIED",
    "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED",
    "description": "description",
    "inputDataSchema": {
      "foo": "bar"
    },
    "outputDefinition": {
      "foo": "bar"
    },
    "webhookEventsUrl": "webhookEventsUrl"
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "variationCount": 0
  }
}
```

## Delete an agent

`agents.delete(id, **kwargs) -> void`

**delete** `/v1/workspaces/{workspaceId}/agents/{id}`

Deletes an agent from the workspace

### Parameters

- `workspace_id: String`

- `id: String`

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

result = cadenya.agents.delete("id", workspace_id: "workspaceId")

puts(result)
```

## Update an agent

`agents.update(id, **kwargs) -> Agent`

**patch** `/v1/workspaces/{workspaceId}/agents/{id}`

Updates an agent in the workspace

### Parameters

- `workspace_id: String`

- `id: String`

- `metadata: UpdateResourceMetadata`

  UpdateResourceMetadata contains the user-provided fields for updating
  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`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")

  - `bundle_key: String`

    Optional bundle ownership key. See ResourceMetadata.bundle_key.

  - `external_id: String`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}

- `spec: AgentSpec`

  Agent specification (user-provided configuration)

  - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

    Status of the agent

    - `:AGENT_STATUS_UNSPECIFIED`

    - `:AGENT_STATUS_DRAFT`

    - `:AGENT_STATUS_PUBLISHED`

    - `:AGENT_STATUS_ARCHIVED`

  - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

    Controls how variations are automatically selected when creating objectives
    Defaults to RANDOM when unspecified

    - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

    - `:VARIATION_SELECTION_MODE_RANDOM`

    - `:VARIATION_SELECTION_MODE_WEIGHTED`

  - `description: String`

    Description of the agent's purpose

  - `input_data_schema: Hash[Symbol, untyped]`

    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.

  - `output_definition: Hash[Symbol, untyped]`

    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.

  - `webhook_events_url: String`

    The URL that Cadenya will send events for any objective assigned to the agent.

- `update_mask: String`

  Fields to update

### Returns

- `class Agent`

  Agent resource

  - `metadata: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentSpec`

    Agent specification (user-provided configuration)

    - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

      Status of the agent

      - `:AGENT_STATUS_UNSPECIFIED`

      - `:AGENT_STATUS_DRAFT`

      - `:AGENT_STATUS_PUBLISHED`

      - `:AGENT_STATUS_ARCHIVED`

    - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

      Controls how variations are automatically selected when creating objectives
      Defaults to RANDOM when unspecified

      - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

      - `:VARIATION_SELECTION_MODE_RANDOM`

      - `:VARIATION_SELECTION_MODE_WEIGHTED`

    - `description: String`

      Description of the agent's purpose

    - `input_data_schema: Hash[Symbol, untyped]`

      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.

    - `output_definition: Hash[Symbol, untyped]`

      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.

    - `webhook_events_url: String`

      The URL that Cadenya will send events for any objective assigned to the agent.

  - `info: AgentInfo`

    AgentInfo contains simple information about an agent for display or quick reference

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `variation_count: Integer`

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

agent = cadenya.agents.update("id", workspace_id: "workspaceId")

puts(agent)
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "status": "AGENT_STATUS_UNSPECIFIED",
    "variationSelectionMode": "VARIATION_SELECTION_MODE_UNSPECIFIED",
    "description": "description",
    "inputDataSchema": {
      "foo": "bar"
    },
    "outputDefinition": {
      "foo": "bar"
    },
    "webhookEventsUrl": "webhookEventsUrl"
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "variationCount": 0
  }
}
```

## Domain Types

### Agent

- `class Agent`

  Agent resource

  - `metadata: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentSpec`

    Agent specification (user-provided configuration)

    - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

      Status of the agent

      - `:AGENT_STATUS_UNSPECIFIED`

      - `:AGENT_STATUS_DRAFT`

      - `:AGENT_STATUS_PUBLISHED`

      - `:AGENT_STATUS_ARCHIVED`

    - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

      Controls how variations are automatically selected when creating objectives
      Defaults to RANDOM when unspecified

      - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

      - `:VARIATION_SELECTION_MODE_RANDOM`

      - `:VARIATION_SELECTION_MODE_WEIGHTED`

    - `description: String`

      Description of the agent's purpose

    - `input_data_schema: Hash[Symbol, untyped]`

      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.

    - `output_definition: Hash[Symbol, untyped]`

      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.

    - `webhook_events_url: String`

      The URL that Cadenya will send events for any objective assigned to the agent.

  - `info: AgentInfo`

    AgentInfo contains simple information about an agent for display or quick reference

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `variation_count: Integer`

### Agent Info

- `class AgentInfo`

  AgentInfo contains simple information about an agent for display or quick reference

  - `created_by: 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`

      AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: ProfileSpec`

      Configuration for a profile.

      - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

        Whether this profile represents a human user, an API key, or a system
        principal.

        - `:PROFILE_TYPE_UNSPECIFIED`

        - `:PROFILE_TYPE_USER`

        - `:PROFILE_TYPE_API_KEY`

        - `:PROFILE_TYPE_SYSTEM`

      - `email: String`

        Email address of the profile. Required and unique within an account for
        user profiles.

      - `name: String`

        Display name (e.g., "Bobby Tables").

  - `variation_count: Integer`

### Agent Spec

- `class AgentSpec`

  Agent specification (user-provided configuration)

  - `status: :AGENT_STATUS_UNSPECIFIED | :AGENT_STATUS_DRAFT | :AGENT_STATUS_PUBLISHED | :AGENT_STATUS_ARCHIVED`

    Status of the agent

    - `:AGENT_STATUS_UNSPECIFIED`

    - `:AGENT_STATUS_DRAFT`

    - `:AGENT_STATUS_PUBLISHED`

    - `:AGENT_STATUS_ARCHIVED`

  - `variation_selection_mode: :VARIATION_SELECTION_MODE_UNSPECIFIED | :VARIATION_SELECTION_MODE_RANDOM | :VARIATION_SELECTION_MODE_WEIGHTED`

    Controls how variations are automatically selected when creating objectives
    Defaults to RANDOM when unspecified

    - `:VARIATION_SELECTION_MODE_UNSPECIFIED`

    - `:VARIATION_SELECTION_MODE_RANDOM`

    - `:VARIATION_SELECTION_MODE_WEIGHTED`

  - `description: String`

    Description of the agent's purpose

  - `input_data_schema: Hash[Symbol, untyped]`

    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.

  - `output_definition: Hash[Symbol, untyped]`

    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.

  - `webhook_events_url: String`

    The URL that Cadenya will send events for any objective assigned to the agent.

### Page

- `class Page`

  - `next_cursor: String`

  - `total: Integer`

# Feedback

## List feedback for an agent

`agents.feedback.list(agent_id, **kwargs) -> CursorPagination<ObjectiveFeedback>`

**get** `/v1/workspaces/{workspaceId}/agents/{agentId}/feedback`

Lists feedback submitted across all objectives belonging to an agent. Supports search by comment, sentiment filter, agent variation filter, and creation date range. Results are ordered by creation time, newest first.

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `agent_variation_id: String`

  Optional filter to limit results to feedback on objectives run by a single
  agent variation. Supports "external_id:" prefix for external IDs.

- `created_after: Time`

  Inclusive lower bound on feedback creation time.

- `created_before: Time`

  Exclusive upper bound on feedback creation time.

- `cursor: String`

  Pagination cursor from previous response.

- `include_info: bool`

  When set to true you may use more of your alloted API rate-limit

- `limit: Integer`

  Maximum number of results to return.

- `query: String`

  Free-text search applied to the feedback comment. Case-insensitive substring match.

- `sentiment: :FEEDBACK_SENTIMENT_UNSPECIFIED | :FEEDBACK_SENTIMENT_POSITIVE | :FEEDBACK_SENTIMENT_NEGATIVE`

  Filter by sentiment. UNSPECIFIED returns feedback regardless of score.

  - `:FEEDBACK_SENTIMENT_UNSPECIFIED`

  - `:FEEDBACK_SENTIMENT_POSITIVE`

  - `:FEEDBACK_SENTIMENT_NEGATIVE`

### Returns

- `class ObjectiveFeedback`

  ObjectiveFeedback represents feedback submitted for an objective's execution.
  Feedback is used to score agent variations and improve agent performance over time.

  - `data: ObjectiveFeedbackData`

    - `comment: String`

      Optional human-readable comment explaining the feedback

    - `score: Float`

      A score between -1.0 and 1.0 representing the quality of the objective's execution.
      -1.0 is the worst possible score, 0.0 is neutral, and 1.0 is the best.

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

  - `info: ObjectiveFeedbackInfo`

    - `agent_variation: 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.

      - `id: String`

      - `name: String`

        Human-readable name of the referenced resource, populated by the server
        on reads for convenience. Absent on references to resources that do not
        have a name (e.g., objective tasks).

    - `objective: 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.

    - `submitted_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

page = cadenya.agents.feedback.list("agentId", workspace_id: "workspaceId")

puts(page)
```

#### Response

```json
{
  "items": [
    {
      "data": {
        "comment": "comment",
        "score": 0
      },
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "info": {
        "agentVariation": {
          "id": "id",
          "name": "name"
        },
        "objective": {
          "id": "id",
          "name": "name"
        },
        "submittedBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

# Webhook Deliveries

## List webhook deliveries

`agents.webhook_deliveries.list(agent_id, **kwargs) -> CursorPagination<WebhookDelivery>`

**get** `/v1/workspaces/{workspaceId}/agents/{agentId}/webhook_deliveries`

Lists all webhook deliveries for an agent

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `cursor: String`

  Pagination cursor from previous response

- `event_type: :OBJECTIVE_EVENT_TYPE_UNSPECIFIED | :OBJECTIVE_EVENT_TYPE_USER_MESSAGE | :OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED | 13 more`

  Optional filter by event type

  - `:OBJECTIVE_EVENT_TYPE_UNSPECIFIED`

  - `:OBJECTIVE_EVENT_TYPE_USER_MESSAGE`

  - `:OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED`

  - `:OBJECTIVE_EVENT_TYPE_TOOL_APPROVED`

  - `:OBJECTIVE_EVENT_TYPE_TOOL_DENIED`

  - `:OBJECTIVE_EVENT_TYPE_TOOL_CALLED`

  - `:OBJECTIVE_EVENT_TYPE_ERROR`

  - `:OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE`

  - `:OBJECTIVE_EVENT_TYPE_TOOL_RESULT`

  - `:OBJECTIVE_EVENT_TYPE_TOOL_ERROR`

  - `:OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED`

  - `:OBJECTIVE_EVENT_TYPE_MEMORY_READ`

  - `:OBJECTIVE_EVENT_TYPE_CANCELLED`

  - `:OBJECTIVE_EVENT_TYPE_SUB_AGENT_SPAWNED`

  - `:OBJECTIVE_EVENT_TYPE_SUB_AGENT_UPDATED`

  - `:OBJECTIVE_EVENT_TYPE_FINALIZED`

- `limit: Integer`

  Maximum number of results to return

- `objective_id: String`

  Optional filter by objective ID

### Returns

- `class WebhookDelivery`

  - `data: WebhookDeliveryData`

    Webhook delivery details.

    - `agent_id: String`

      Related resources

    - `attempt_count: Integer`

    - `event_type: :OBJECTIVE_EVENT_TYPE_UNSPECIFIED | :OBJECTIVE_EVENT_TYPE_USER_MESSAGE | :OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED | 13 more`

      The type of objective event that triggered this webhook delivery

      - `:OBJECTIVE_EVENT_TYPE_UNSPECIFIED`

      - `:OBJECTIVE_EVENT_TYPE_USER_MESSAGE`

      - `:OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED`

      - `:OBJECTIVE_EVENT_TYPE_TOOL_APPROVED`

      - `:OBJECTIVE_EVENT_TYPE_TOOL_DENIED`

      - `:OBJECTIVE_EVENT_TYPE_TOOL_CALLED`

      - `:OBJECTIVE_EVENT_TYPE_ERROR`

      - `:OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE`

      - `:OBJECTIVE_EVENT_TYPE_TOOL_RESULT`

      - `:OBJECTIVE_EVENT_TYPE_TOOL_ERROR`

      - `:OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED`

      - `:OBJECTIVE_EVENT_TYPE_MEMORY_READ`

      - `:OBJECTIVE_EVENT_TYPE_CANCELLED`

      - `:OBJECTIVE_EVENT_TYPE_SUB_AGENT_SPAWNED`

      - `:OBJECTIVE_EVENT_TYPE_SUB_AGENT_UPDATED`

      - `:OBJECTIVE_EVENT_TYPE_FINALIZED`

    - `http_status_code: Integer`

      Response details. The response body is not retained.

    - `last_attempt_at: Time`

    - `latency_ms: Integer`

    - `objective_event_id: String`

    - `objective_id: String`

    - `response_content_length: String`

      Content length of the response body in bytes

    - `status: :WEBHOOK_DELIVERY_STATUS_UNSPECIFIED | :WEBHOOK_DELIVERY_STATUS_PENDING | :WEBHOOK_DELIVERY_STATUS_COMPLETED | 2 more`

      - `:WEBHOOK_DELIVERY_STATUS_UNSPECIFIED`

      - `:WEBHOOK_DELIVERY_STATUS_PENDING`

      - `:WEBHOOK_DELIVERY_STATUS_COMPLETED`

      - `:WEBHOOK_DELIVERY_STATUS_FAILED`

      - `:WEBHOOK_DELIVERY_STATUS_DISABLED`

    - `webhook_id: String`

    - `webhook_url: String`

      Webhook delivery details

    - `error_message: String`

    - `response_headers: Hash[Symbol, String]`

      Response headers received from the webhook endpoint

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

page = cadenya.agents.webhook_deliveries.list("agentId", workspace_id: "workspaceId")

puts(page)
```

#### Response

```json
{
  "items": [
    {
      "data": {
        "agentId": "agentId",
        "attemptCount": 0,
        "eventType": "OBJECTIVE_EVENT_TYPE_UNSPECIFIED",
        "httpStatusCode": 0,
        "lastAttemptAt": "2019-12-27T18:11:19.117Z",
        "latencyMs": 0,
        "objectiveEventId": "objectiveEventId",
        "objectiveId": "objectiveId",
        "responseContentLength": "responseContentLength",
        "status": "WEBHOOK_DELIVERY_STATUS_UNSPECIFIED",
        "webhookId": "webhookId",
        "webhookUrl": "webhookUrl",
        "errorMessage": "errorMessage",
        "responseHeaders": {
          "foo": "string"
        }
      },
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

## Domain Types

### Webhook Delivery

- `class WebhookDelivery`

  - `data: WebhookDeliveryData`

    Webhook delivery details.

    - `agent_id: String`

      Related resources

    - `attempt_count: Integer`

    - `event_type: :OBJECTIVE_EVENT_TYPE_UNSPECIFIED | :OBJECTIVE_EVENT_TYPE_USER_MESSAGE | :OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED | 13 more`

      The type of objective event that triggered this webhook delivery

      - `:OBJECTIVE_EVENT_TYPE_UNSPECIFIED`

      - `:OBJECTIVE_EVENT_TYPE_USER_MESSAGE`

      - `:OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED`

      - `:OBJECTIVE_EVENT_TYPE_TOOL_APPROVED`

      - `:OBJECTIVE_EVENT_TYPE_TOOL_DENIED`

      - `:OBJECTIVE_EVENT_TYPE_TOOL_CALLED`

      - `:OBJECTIVE_EVENT_TYPE_ERROR`

      - `:OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE`

      - `:OBJECTIVE_EVENT_TYPE_TOOL_RESULT`

      - `:OBJECTIVE_EVENT_TYPE_TOOL_ERROR`

      - `:OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED`

      - `:OBJECTIVE_EVENT_TYPE_MEMORY_READ`

      - `:OBJECTIVE_EVENT_TYPE_CANCELLED`

      - `:OBJECTIVE_EVENT_TYPE_SUB_AGENT_SPAWNED`

      - `:OBJECTIVE_EVENT_TYPE_SUB_AGENT_UPDATED`

      - `:OBJECTIVE_EVENT_TYPE_FINALIZED`

    - `http_status_code: Integer`

      Response details. The response body is not retained.

    - `last_attempt_at: Time`

    - `latency_ms: Integer`

    - `objective_event_id: String`

    - `objective_id: String`

    - `response_content_length: String`

      Content length of the response body in bytes

    - `status: :WEBHOOK_DELIVERY_STATUS_UNSPECIFIED | :WEBHOOK_DELIVERY_STATUS_PENDING | :WEBHOOK_DELIVERY_STATUS_COMPLETED | 2 more`

      - `:WEBHOOK_DELIVERY_STATUS_UNSPECIFIED`

      - `:WEBHOOK_DELIVERY_STATUS_PENDING`

      - `:WEBHOOK_DELIVERY_STATUS_COMPLETED`

      - `:WEBHOOK_DELIVERY_STATUS_FAILED`

      - `:WEBHOOK_DELIVERY_STATUS_DISABLED`

    - `webhook_id: String`

    - `webhook_url: String`

      Webhook delivery details

    - `error_message: String`

    - `response_headers: Hash[Symbol, String]`

      Response headers received from the webhook endpoint

  - `metadata: OperationMetadata`

    Metadata for ephemeral operations and activities (e.g., objectives, executions, runs)

    - `id: String`

      Unique identifier for the operation (prefixed ULID, e.g., "obj_01HXK...")

    - `account_id: String`

      Account this operation belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this operation was created
      ULID includes timestamp information, but this explicit field enables easier querying

    - `profile_id: String`

      ID of the actor (user or service account) that created this operation

    - `workspace_id: String`

      Workspace this operation belongs to for organizational grouping (prefixed ULID)

    - `external_id: String`

      External ID for the operation (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"priority": "high", "source": "api", "workflow": "onboarding"}

### Webhook Delivery Data

- `class WebhookDeliveryData`

  - `agent_id: String`

    Related resources

  - `attempt_count: Integer`

  - `event_type: :OBJECTIVE_EVENT_TYPE_UNSPECIFIED | :OBJECTIVE_EVENT_TYPE_USER_MESSAGE | :OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED | 13 more`

    The type of objective event that triggered this webhook delivery

    - `:OBJECTIVE_EVENT_TYPE_UNSPECIFIED`

    - `:OBJECTIVE_EVENT_TYPE_USER_MESSAGE`

    - `:OBJECTIVE_EVENT_TYPE_TOOL_APPROVAL_REQUESTED`

    - `:OBJECTIVE_EVENT_TYPE_TOOL_APPROVED`

    - `:OBJECTIVE_EVENT_TYPE_TOOL_DENIED`

    - `:OBJECTIVE_EVENT_TYPE_TOOL_CALLED`

    - `:OBJECTIVE_EVENT_TYPE_ERROR`

    - `:OBJECTIVE_EVENT_TYPE_ASSISTANT_MESSAGE`

    - `:OBJECTIVE_EVENT_TYPE_TOOL_RESULT`

    - `:OBJECTIVE_EVENT_TYPE_TOOL_ERROR`

    - `:OBJECTIVE_EVENT_TYPE_CONTEXT_WINDOW_COMPACTED`

    - `:OBJECTIVE_EVENT_TYPE_MEMORY_READ`

    - `:OBJECTIVE_EVENT_TYPE_CANCELLED`

    - `:OBJECTIVE_EVENT_TYPE_SUB_AGENT_SPAWNED`

    - `:OBJECTIVE_EVENT_TYPE_SUB_AGENT_UPDATED`

    - `:OBJECTIVE_EVENT_TYPE_FINALIZED`

  - `http_status_code: Integer`

    Response details. The response body is not retained.

  - `last_attempt_at: Time`

  - `latency_ms: Integer`

  - `objective_event_id: String`

  - `objective_id: String`

  - `response_content_length: String`

    Content length of the response body in bytes

  - `status: :WEBHOOK_DELIVERY_STATUS_UNSPECIFIED | :WEBHOOK_DELIVERY_STATUS_PENDING | :WEBHOOK_DELIVERY_STATUS_COMPLETED | 2 more`

    - `:WEBHOOK_DELIVERY_STATUS_UNSPECIFIED`

    - `:WEBHOOK_DELIVERY_STATUS_PENDING`

    - `:WEBHOOK_DELIVERY_STATUS_COMPLETED`

    - `:WEBHOOK_DELIVERY_STATUS_FAILED`

    - `:WEBHOOK_DELIVERY_STATUS_DISABLED`

  - `webhook_id: String`

  - `webhook_url: String`

    Webhook delivery details

  - `error_message: String`

  - `response_headers: Hash[Symbol, String]`

    Response headers received from the webhook endpoint

# Variations

## List variations

`agents.variations.list(agent_id, **kwargs) -> CursorPagination<AgentVariation>`

**get** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations`

Lists all variations for an agent

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `bundle_key: String`

  Filter by bundle_key — return only resources owned by this bundle.

- `cursor: String`

  Pagination cursor from previous response

- `include_info: bool`

  When true, the `info` field on each returned variation is populated.
  Requests with this flag count more against your rate limit.

- `limit: Integer`

  Maximum number of results to return

- `sort_order: String`

  Sort order for results (asc or desc by creation time)

### Returns

- `class AgentVariation`

  AgentVariation resource

  - `metadata: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentVariationSpec`

    AgentVariationSpec defines the operational configuration for a variation

    - `compaction_config: AgentVariationSpecCompactionConfig`

      CompactionConfig defines how context window compaction behaves for objectives using this variation.

      - `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."

      - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

        ToolResultClearingStrategy configures clearing of older tool result content.

        - `preserve_recent_results: 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

      - `trigger_threshold: 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%)

    - `constraints: AgentVariationSpecConstraints`

      Execution constraints

      - `max_sub_objectives: Integer`

        The maximum number of sub-objectives that can be created. 0 means no limit.

      - `max_tool_calls: Integer`

        The maximum number of tool calls that can be made. 0 means no limit.

    - `description: String`

      Human-readable description of what this variation does or when it should be used

    - `enable_episodic_memory: bool`

      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.

    - `episodic_memory_ttl: Integer`

      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.

    - `model_config: AgentVariationSpecModelConfig`

      ModelConfig defines the model configuration for a variation

      - `model_id: String`

        The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

      - `temperature: Float`

        Sampling temperature for model inference (0.0 to 1.0)
        Lower values produce more deterministic outputs, higher values increase randomness

    - `progressive_discovery: 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.

      - `hints: Array[String]`

      - `max_tools: Integer`

      - `rerank_threshold: Float`

        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.

    - `prompt: String`

      The system prompt for this variation

    - `weight: Integer`

      Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
      Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

  - `info: AgentVariationInfo`

    AgentVariationInfo provides read-only summary information about a variation

    - `assignments: Array[VariationAssignment]`

      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.

      - `id: String`

      - `agent: 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.

        - `id: String`

        - `name: String`

          Human-readable name of the referenced resource, populated by the server
          on reads for convenience. Absent on references to resources that do not
          have a name (e.g., objective tasks).

      - `tool: 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.

      - `tool_set: 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.

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `feedback_count: Integer`

      Total number of objective feedbacks received for this variation

    - `memory_layer_assignments: Array[VariationMemoryLayerAssignment]`

      Read-only list of memory layer assignments for this variation,
      returned in ascending `position` (bottom → top). Capped at 10 entries.

      - `id: String`

        Assignment row id — handle for removing the assignment. Distinct
        from the referenced memory layer's id.

      - `memory_layer: 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.

      - `position: Integer`

        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.

    - `memory_layer_count: Integer`

      Count of memory layer assignments.

    - `model: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `score: Float`

      Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
      Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

    - `sub_agent_count: Integer`

      Number of sub-agents assigned to this variation

    - `tool_count: Integer`

      Number of individual tools assigned to this variation

    - `tool_set_count: Integer`

      Number of tool sets assigned to this variation

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

page = cadenya.agents.variations.list("agentId", workspace_id: "workspaceId")

puts(page)
```

#### Response

```json
{
  "items": [
    {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "compactionConfig": {
          "summarization": {
            "instructions": "instructions"
          },
          "toolResultClearing": {
            "preserveRecentResults": 0
          },
          "triggerThreshold": 0
        },
        "constraints": {
          "maxSubObjectives": 0,
          "maxToolCalls": 0
        },
        "description": "description",
        "enableEpisodicMemory": true,
        "episodicMemoryTtl": 0,
        "modelConfig": {
          "modelId": "modelId",
          "temperature": 0
        },
        "progressiveDiscovery": {
          "hints": [
            "string"
          ],
          "maxTools": 0,
          "rerankThreshold": 0
        },
        "prompt": "prompt",
        "weight": 0
      },
      "info": {
        "assignments": [
          {
            "id": "id",
            "agent": {
              "id": "id",
              "name": "name"
            },
            "tool": {
              "id": "id",
              "name": "name"
            },
            "toolSet": {
              "id": "id",
              "name": "name"
            }
          }
        ],
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "feedbackCount": 0,
        "memoryLayerAssignments": [
          {
            "id": "id",
            "memoryLayer": {
              "id": "id",
              "name": "name"
            },
            "position": 0
          }
        ],
        "memoryLayerCount": 0,
        "model": {
          "id": "id",
          "accountId": "accountId",
          "createdAt": "2019-12-27T18:11:19.117Z",
          "name": "name",
          "profileId": "profileId",
          "workspaceId": "workspaceId",
          "bundleKey": "bundleKey",
          "externalId": "externalId",
          "labels": {
            "foo": "string"
          }
        },
        "score": 0,
        "subAgentCount": 0,
        "toolCount": 0,
        "toolSetCount": 0
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

## Create a new variation

`agents.variations.create(agent_id, **kwargs) -> AgentVariation`

**post** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations`

Creates a new variation for an agent

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `metadata: CreateResourceMetadata`

  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`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")

  - `bundle_key: String`

    Optional bundle ownership key. See ResourceMetadata.bundle_key.

  - `external_id: String`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}

- `spec: AgentVariationSpec`

  AgentVariationSpec defines the operational configuration for a variation

  - `compaction_config: AgentVariationSpecCompactionConfig`

    CompactionConfig defines how context window compaction behaves for objectives using this variation.

    - `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."

    - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

      ToolResultClearingStrategy configures clearing of older tool result content.

      - `preserve_recent_results: 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

    - `trigger_threshold: 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%)

  - `constraints: AgentVariationSpecConstraints`

    Execution constraints

    - `max_sub_objectives: Integer`

      The maximum number of sub-objectives that can be created. 0 means no limit.

    - `max_tool_calls: Integer`

      The maximum number of tool calls that can be made. 0 means no limit.

  - `description: String`

    Human-readable description of what this variation does or when it should be used

  - `enable_episodic_memory: bool`

    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.

  - `episodic_memory_ttl: Integer`

    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.

  - `model_config: AgentVariationSpecModelConfig`

    ModelConfig defines the model configuration for a variation

    - `model_id: String`

      The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

    - `temperature: Float`

      Sampling temperature for model inference (0.0 to 1.0)
      Lower values produce more deterministic outputs, higher values increase randomness

  - `progressive_discovery: 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.

    - `hints: Array[String]`

    - `max_tools: Integer`

    - `rerank_threshold: Float`

      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.

  - `prompt: String`

    The system prompt for this variation

  - `weight: Integer`

    Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
    Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

### Returns

- `class AgentVariation`

  AgentVariation resource

  - `metadata: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentVariationSpec`

    AgentVariationSpec defines the operational configuration for a variation

    - `compaction_config: AgentVariationSpecCompactionConfig`

      CompactionConfig defines how context window compaction behaves for objectives using this variation.

      - `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."

      - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

        ToolResultClearingStrategy configures clearing of older tool result content.

        - `preserve_recent_results: 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

      - `trigger_threshold: 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%)

    - `constraints: AgentVariationSpecConstraints`

      Execution constraints

      - `max_sub_objectives: Integer`

        The maximum number of sub-objectives that can be created. 0 means no limit.

      - `max_tool_calls: Integer`

        The maximum number of tool calls that can be made. 0 means no limit.

    - `description: String`

      Human-readable description of what this variation does or when it should be used

    - `enable_episodic_memory: bool`

      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.

    - `episodic_memory_ttl: Integer`

      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.

    - `model_config: AgentVariationSpecModelConfig`

      ModelConfig defines the model configuration for a variation

      - `model_id: String`

        The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

      - `temperature: Float`

        Sampling temperature for model inference (0.0 to 1.0)
        Lower values produce more deterministic outputs, higher values increase randomness

    - `progressive_discovery: 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.

      - `hints: Array[String]`

      - `max_tools: Integer`

      - `rerank_threshold: Float`

        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.

    - `prompt: String`

      The system prompt for this variation

    - `weight: Integer`

      Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
      Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

  - `info: AgentVariationInfo`

    AgentVariationInfo provides read-only summary information about a variation

    - `assignments: Array[VariationAssignment]`

      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.

      - `id: String`

      - `agent: 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.

        - `id: String`

        - `name: String`

          Human-readable name of the referenced resource, populated by the server
          on reads for convenience. Absent on references to resources that do not
          have a name (e.g., objective tasks).

      - `tool: 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.

      - `tool_set: 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.

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `feedback_count: Integer`

      Total number of objective feedbacks received for this variation

    - `memory_layer_assignments: Array[VariationMemoryLayerAssignment]`

      Read-only list of memory layer assignments for this variation,
      returned in ascending `position` (bottom → top). Capped at 10 entries.

      - `id: String`

        Assignment row id — handle for removing the assignment. Distinct
        from the referenced memory layer's id.

      - `memory_layer: 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.

      - `position: Integer`

        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.

    - `memory_layer_count: Integer`

      Count of memory layer assignments.

    - `model: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `score: Float`

      Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
      Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

    - `sub_agent_count: Integer`

      Number of sub-agents assigned to this variation

    - `tool_count: Integer`

      Number of individual tools assigned to this variation

    - `tool_set_count: Integer`

      Number of tool sets assigned to this variation

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

agent_variation = cadenya.agents.variations.create(
  "agentId",
  workspace_id: "workspaceId",
  metadata: {name: "name"},
  spec: {}
)

puts(agent_variation)
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "compactionConfig": {
      "summarization": {
        "instructions": "instructions"
      },
      "toolResultClearing": {
        "preserveRecentResults": 0
      },
      "triggerThreshold": 0
    },
    "constraints": {
      "maxSubObjectives": 0,
      "maxToolCalls": 0
    },
    "description": "description",
    "enableEpisodicMemory": true,
    "episodicMemoryTtl": 0,
    "modelConfig": {
      "modelId": "modelId",
      "temperature": 0
    },
    "progressiveDiscovery": {
      "hints": [
        "string"
      ],
      "maxTools": 0,
      "rerankThreshold": 0
    },
    "prompt": "prompt",
    "weight": 0
  },
  "info": {
    "assignments": [
      {
        "id": "id",
        "agent": {
          "id": "id",
          "name": "name"
        },
        "tool": {
          "id": "id",
          "name": "name"
        },
        "toolSet": {
          "id": "id",
          "name": "name"
        }
      }
    ],
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "feedbackCount": 0,
    "memoryLayerAssignments": [
      {
        "id": "id",
        "memoryLayer": {
          "id": "id",
          "name": "name"
        },
        "position": 0
      }
    ],
    "memoryLayerCount": 0,
    "model": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "bundleKey": "bundleKey",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    },
    "score": 0,
    "subAgentCount": 0,
    "toolCount": 0,
    "toolSetCount": 0
  }
}
```

## Get a variation by ID

`agents.variations.retrieve(id, **kwargs) -> AgentVariation`

**get** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}`

Retrieves a variation by ID from an agent

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `id: String`

### Returns

- `class AgentVariation`

  AgentVariation resource

  - `metadata: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentVariationSpec`

    AgentVariationSpec defines the operational configuration for a variation

    - `compaction_config: AgentVariationSpecCompactionConfig`

      CompactionConfig defines how context window compaction behaves for objectives using this variation.

      - `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."

      - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

        ToolResultClearingStrategy configures clearing of older tool result content.

        - `preserve_recent_results: 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

      - `trigger_threshold: 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%)

    - `constraints: AgentVariationSpecConstraints`

      Execution constraints

      - `max_sub_objectives: Integer`

        The maximum number of sub-objectives that can be created. 0 means no limit.

      - `max_tool_calls: Integer`

        The maximum number of tool calls that can be made. 0 means no limit.

    - `description: String`

      Human-readable description of what this variation does or when it should be used

    - `enable_episodic_memory: bool`

      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.

    - `episodic_memory_ttl: Integer`

      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.

    - `model_config: AgentVariationSpecModelConfig`

      ModelConfig defines the model configuration for a variation

      - `model_id: String`

        The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

      - `temperature: Float`

        Sampling temperature for model inference (0.0 to 1.0)
        Lower values produce more deterministic outputs, higher values increase randomness

    - `progressive_discovery: 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.

      - `hints: Array[String]`

      - `max_tools: Integer`

      - `rerank_threshold: Float`

        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.

    - `prompt: String`

      The system prompt for this variation

    - `weight: Integer`

      Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
      Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

  - `info: AgentVariationInfo`

    AgentVariationInfo provides read-only summary information about a variation

    - `assignments: Array[VariationAssignment]`

      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.

      - `id: String`

      - `agent: 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.

        - `id: String`

        - `name: String`

          Human-readable name of the referenced resource, populated by the server
          on reads for convenience. Absent on references to resources that do not
          have a name (e.g., objective tasks).

      - `tool: 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.

      - `tool_set: 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.

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `feedback_count: Integer`

      Total number of objective feedbacks received for this variation

    - `memory_layer_assignments: Array[VariationMemoryLayerAssignment]`

      Read-only list of memory layer assignments for this variation,
      returned in ascending `position` (bottom → top). Capped at 10 entries.

      - `id: String`

        Assignment row id — handle for removing the assignment. Distinct
        from the referenced memory layer's id.

      - `memory_layer: 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.

      - `position: Integer`

        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.

    - `memory_layer_count: Integer`

      Count of memory layer assignments.

    - `model: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `score: Float`

      Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
      Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

    - `sub_agent_count: Integer`

      Number of sub-agents assigned to this variation

    - `tool_count: Integer`

      Number of individual tools assigned to this variation

    - `tool_set_count: Integer`

      Number of tool sets assigned to this variation

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

agent_variation = cadenya.agents.variations.retrieve("id", workspace_id: "workspaceId", agent_id: "agentId")

puts(agent_variation)
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "compactionConfig": {
      "summarization": {
        "instructions": "instructions"
      },
      "toolResultClearing": {
        "preserveRecentResults": 0
      },
      "triggerThreshold": 0
    },
    "constraints": {
      "maxSubObjectives": 0,
      "maxToolCalls": 0
    },
    "description": "description",
    "enableEpisodicMemory": true,
    "episodicMemoryTtl": 0,
    "modelConfig": {
      "modelId": "modelId",
      "temperature": 0
    },
    "progressiveDiscovery": {
      "hints": [
        "string"
      ],
      "maxTools": 0,
      "rerankThreshold": 0
    },
    "prompt": "prompt",
    "weight": 0
  },
  "info": {
    "assignments": [
      {
        "id": "id",
        "agent": {
          "id": "id",
          "name": "name"
        },
        "tool": {
          "id": "id",
          "name": "name"
        },
        "toolSet": {
          "id": "id",
          "name": "name"
        }
      }
    ],
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "feedbackCount": 0,
    "memoryLayerAssignments": [
      {
        "id": "id",
        "memoryLayer": {
          "id": "id",
          "name": "name"
        },
        "position": 0
      }
    ],
    "memoryLayerCount": 0,
    "model": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "bundleKey": "bundleKey",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    },
    "score": 0,
    "subAgentCount": 0,
    "toolCount": 0,
    "toolSetCount": 0
  }
}
```

## Delete a variation

`agents.variations.delete(id, **kwargs) -> void`

**delete** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}`

Deletes a variation from an agent

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `id: String`

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

result = cadenya.agents.variations.delete("id", workspace_id: "workspaceId", agent_id: "agentId")

puts(result)
```

## Update a variation

`agents.variations.update(id, **kwargs) -> AgentVariation`

**patch** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{id}`

Updates a variation for an agent

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `id: String`

- `metadata: UpdateResourceMetadata`

  UpdateResourceMetadata contains the user-provided fields for updating
  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`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")

  - `bundle_key: String`

    Optional bundle ownership key. See ResourceMetadata.bundle_key.

  - `external_id: String`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}

- `spec: AgentVariationSpec`

  AgentVariationSpec defines the operational configuration for a variation

  - `compaction_config: AgentVariationSpecCompactionConfig`

    CompactionConfig defines how context window compaction behaves for objectives using this variation.

    - `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."

    - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

      ToolResultClearingStrategy configures clearing of older tool result content.

      - `preserve_recent_results: 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

    - `trigger_threshold: 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%)

  - `constraints: AgentVariationSpecConstraints`

    Execution constraints

    - `max_sub_objectives: Integer`

      The maximum number of sub-objectives that can be created. 0 means no limit.

    - `max_tool_calls: Integer`

      The maximum number of tool calls that can be made. 0 means no limit.

  - `description: String`

    Human-readable description of what this variation does or when it should be used

  - `enable_episodic_memory: bool`

    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.

  - `episodic_memory_ttl: Integer`

    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.

  - `model_config: AgentVariationSpecModelConfig`

    ModelConfig defines the model configuration for a variation

    - `model_id: String`

      The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

    - `temperature: Float`

      Sampling temperature for model inference (0.0 to 1.0)
      Lower values produce more deterministic outputs, higher values increase randomness

  - `progressive_discovery: 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.

    - `hints: Array[String]`

    - `max_tools: Integer`

    - `rerank_threshold: Float`

      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.

  - `prompt: String`

    The system prompt for this variation

  - `weight: Integer`

    Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
    Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

- `update_mask: String`

  Fields to update

### Returns

- `class AgentVariation`

  AgentVariation resource

  - `metadata: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentVariationSpec`

    AgentVariationSpec defines the operational configuration for a variation

    - `compaction_config: AgentVariationSpecCompactionConfig`

      CompactionConfig defines how context window compaction behaves for objectives using this variation.

      - `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."

      - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

        ToolResultClearingStrategy configures clearing of older tool result content.

        - `preserve_recent_results: 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

      - `trigger_threshold: 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%)

    - `constraints: AgentVariationSpecConstraints`

      Execution constraints

      - `max_sub_objectives: Integer`

        The maximum number of sub-objectives that can be created. 0 means no limit.

      - `max_tool_calls: Integer`

        The maximum number of tool calls that can be made. 0 means no limit.

    - `description: String`

      Human-readable description of what this variation does or when it should be used

    - `enable_episodic_memory: bool`

      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.

    - `episodic_memory_ttl: Integer`

      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.

    - `model_config: AgentVariationSpecModelConfig`

      ModelConfig defines the model configuration for a variation

      - `model_id: String`

        The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

      - `temperature: Float`

        Sampling temperature for model inference (0.0 to 1.0)
        Lower values produce more deterministic outputs, higher values increase randomness

    - `progressive_discovery: 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.

      - `hints: Array[String]`

      - `max_tools: Integer`

      - `rerank_threshold: Float`

        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.

    - `prompt: String`

      The system prompt for this variation

    - `weight: Integer`

      Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
      Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

  - `info: AgentVariationInfo`

    AgentVariationInfo provides read-only summary information about a variation

    - `assignments: Array[VariationAssignment]`

      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.

      - `id: String`

      - `agent: 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.

        - `id: String`

        - `name: String`

          Human-readable name of the referenced resource, populated by the server
          on reads for convenience. Absent on references to resources that do not
          have a name (e.g., objective tasks).

      - `tool: 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.

      - `tool_set: 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.

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `feedback_count: Integer`

      Total number of objective feedbacks received for this variation

    - `memory_layer_assignments: Array[VariationMemoryLayerAssignment]`

      Read-only list of memory layer assignments for this variation,
      returned in ascending `position` (bottom → top). Capped at 10 entries.

      - `id: String`

        Assignment row id — handle for removing the assignment. Distinct
        from the referenced memory layer's id.

      - `memory_layer: 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.

      - `position: Integer`

        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.

    - `memory_layer_count: Integer`

      Count of memory layer assignments.

    - `model: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `score: Float`

      Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
      Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

    - `sub_agent_count: Integer`

      Number of sub-agents assigned to this variation

    - `tool_count: Integer`

      Number of individual tools assigned to this variation

    - `tool_set_count: Integer`

      Number of tool sets assigned to this variation

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

agent_variation = cadenya.agents.variations.update("id", workspace_id: "workspaceId", agent_id: "agentId")

puts(agent_variation)
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "compactionConfig": {
      "summarization": {
        "instructions": "instructions"
      },
      "toolResultClearing": {
        "preserveRecentResults": 0
      },
      "triggerThreshold": 0
    },
    "constraints": {
      "maxSubObjectives": 0,
      "maxToolCalls": 0
    },
    "description": "description",
    "enableEpisodicMemory": true,
    "episodicMemoryTtl": 0,
    "modelConfig": {
      "modelId": "modelId",
      "temperature": 0
    },
    "progressiveDiscovery": {
      "hints": [
        "string"
      ],
      "maxTools": 0,
      "rerankThreshold": 0
    },
    "prompt": "prompt",
    "weight": 0
  },
  "info": {
    "assignments": [
      {
        "id": "id",
        "agent": {
          "id": "id",
          "name": "name"
        },
        "tool": {
          "id": "id",
          "name": "name"
        },
        "toolSet": {
          "id": "id",
          "name": "name"
        }
      }
    ],
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "feedbackCount": 0,
    "memoryLayerAssignments": [
      {
        "id": "id",
        "memoryLayer": {
          "id": "id",
          "name": "name"
        },
        "position": 0
      }
    ],
    "memoryLayerCount": 0,
    "model": {
      "id": "id",
      "accountId": "accountId",
      "createdAt": "2019-12-27T18:11:19.117Z",
      "name": "name",
      "profileId": "profileId",
      "workspaceId": "workspaceId",
      "bundleKey": "bundleKey",
      "externalId": "externalId",
      "labels": {
        "foo": "string"
      }
    },
    "score": 0,
    "subAgentCount": 0,
    "toolCount": 0,
    "toolSetCount": 0
  }
}
```

## Add an assignment to a variation

`agents.variations.add_assignment(variation_id, **kwargs) -> VariationAssignment`

**post** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/assignments`

Assigns a tool, tool set, or sub-agent to a variation. Exactly one target ID must be set.

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `variation_id: String`

- `sub_agent_id: String`

- `tool_id: String`

- `tool_set_id: String`

### Returns

- `class VariationAssignment`

  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`.

  - `id: String`

  - `agent: 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.

    - `id: String`

    - `name: String`

      Human-readable name of the referenced resource, populated by the server
      on reads for convenience. Absent on references to resources that do not
      have a name (e.g., objective tasks).

  - `tool: 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.

  - `tool_set: 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.

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

variation_assignment = cadenya.agents.variations.add_assignment("variationId", workspace_id: "workspaceId", agent_id: "agentId")

puts(variation_assignment)
```

#### Response

```json
{
  "id": "id",
  "agent": {
    "id": "id",
    "name": "name"
  },
  "tool": {
    "id": "id",
    "name": "name"
  },
  "toolSet": {
    "id": "id",
    "name": "name"
  }
}
```

## Remove an assignment from a variation

`agents.variations.remove_assignment(id, **kwargs) -> void`

**delete** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/assignments/{id}`

Detaches an assignment from a variation, identified by the assignment ID returned when it was added.

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `variation_id: String`

- `id: String`

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

result = cadenya.agents.variations.remove_assignment(
  "id",
  workspace_id: "workspaceId",
  agent_id: "agentId",
  variation_id: "variationId"
)

puts(result)
```

## Attach a memory layer to a variation

`agents.variations.add_memory_layer(variation_id, **kwargs) -> VariationMemoryLayerAssignment`

**post** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments`

Attaches a memory layer to a variation at a given position in the variation's baseline memory stack.

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `variation_id: String`

- `memory_layer_id: String`

  Layer to attach. Accepts the canonical `memlyr_…` form or the `external_id:<value>` form.

- `position: Integer`

  Position in the stack. If omitted, server appends
  (max existing position + 1).

### Returns

- `class VariationMemoryLayerAssignment`

  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: String`

    Assignment row id — handle for removing the assignment. Distinct
    from the referenced memory layer's id.

  - `memory_layer: 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.

    - `id: String`

    - `name: String`

      Human-readable name of the referenced resource, populated by the server
      on reads for convenience. Absent on references to resources that do not
      have a name (e.g., objective tasks).

  - `position: Integer`

    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.

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

variation_memory_layer_assignment = cadenya.agents.variations.add_memory_layer(
  "variationId",
  workspace_id: "workspaceId",
  agent_id: "agentId"
)

puts(variation_memory_layer_assignment)
```

#### Response

```json
{
  "id": "id",
  "memoryLayer": {
    "id": "id",
    "name": "name"
  },
  "position": 0
}
```

## Update a variation's memory layer assignment

`agents.variations.update_memory_layer(id, **kwargs) -> VariationMemoryLayerAssignment`

**patch** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments/{id}`

Updates the position of a memory layer assignment on a variation.

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `variation_id: String`

- `id: String`

- `position: Integer`

  New position. Only field currently updatable on an assignment.

### Returns

- `class VariationMemoryLayerAssignment`

  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: String`

    Assignment row id — handle for removing the assignment. Distinct
    from the referenced memory layer's id.

  - `memory_layer: 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.

    - `id: String`

    - `name: String`

      Human-readable name of the referenced resource, populated by the server
      on reads for convenience. Absent on references to resources that do not
      have a name (e.g., objective tasks).

  - `position: Integer`

    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.

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

variation_memory_layer_assignment = cadenya.agents.variations.update_memory_layer(
  "id",
  workspace_id: "workspaceId",
  agent_id: "agentId",
  variation_id: "variationId"
)

puts(variation_memory_layer_assignment)
```

#### Response

```json
{
  "id": "id",
  "memoryLayer": {
    "id": "id",
    "name": "name"
  },
  "position": 0
}
```

## Remove a memory layer assignment from a variation

`agents.variations.remove_memory_layer(id, **kwargs) -> void`

**delete** `/v1/workspaces/{workspaceId}/agents/{agentId}/variations/{variationId}/memory_layer_assignments/{id}`

Detaches a memory layer assignment from a variation, identified by the assignment id.

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `variation_id: String`

- `id: String`

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

result = cadenya.agents.variations.remove_memory_layer(
  "id",
  workspace_id: "workspaceId",
  agent_id: "agentId",
  variation_id: "variationId"
)

puts(result)
```

## Domain Types

### Agent Variation

- `class AgentVariation`

  AgentVariation resource

  - `metadata: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentVariationSpec`

    AgentVariationSpec defines the operational configuration for a variation

    - `compaction_config: AgentVariationSpecCompactionConfig`

      CompactionConfig defines how context window compaction behaves for objectives using this variation.

      - `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."

      - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

        ToolResultClearingStrategy configures clearing of older tool result content.

        - `preserve_recent_results: 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

      - `trigger_threshold: 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%)

    - `constraints: AgentVariationSpecConstraints`

      Execution constraints

      - `max_sub_objectives: Integer`

        The maximum number of sub-objectives that can be created. 0 means no limit.

      - `max_tool_calls: Integer`

        The maximum number of tool calls that can be made. 0 means no limit.

    - `description: String`

      Human-readable description of what this variation does or when it should be used

    - `enable_episodic_memory: bool`

      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.

    - `episodic_memory_ttl: Integer`

      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.

    - `model_config: AgentVariationSpecModelConfig`

      ModelConfig defines the model configuration for a variation

      - `model_id: String`

        The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

      - `temperature: Float`

        Sampling temperature for model inference (0.0 to 1.0)
        Lower values produce more deterministic outputs, higher values increase randomness

    - `progressive_discovery: 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.

      - `hints: Array[String]`

      - `max_tools: Integer`

      - `rerank_threshold: Float`

        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.

    - `prompt: String`

      The system prompt for this variation

    - `weight: Integer`

      Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
      Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

  - `info: AgentVariationInfo`

    AgentVariationInfo provides read-only summary information about a variation

    - `assignments: Array[VariationAssignment]`

      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.

      - `id: String`

      - `agent: 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.

        - `id: String`

        - `name: String`

          Human-readable name of the referenced resource, populated by the server
          on reads for convenience. Absent on references to resources that do not
          have a name (e.g., objective tasks).

      - `tool: 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.

      - `tool_set: 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.

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `feedback_count: Integer`

      Total number of objective feedbacks received for this variation

    - `memory_layer_assignments: Array[VariationMemoryLayerAssignment]`

      Read-only list of memory layer assignments for this variation,
      returned in ascending `position` (bottom → top). Capped at 10 entries.

      - `id: String`

        Assignment row id — handle for removing the assignment. Distinct
        from the referenced memory layer's id.

      - `memory_layer: 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.

      - `position: Integer`

        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.

    - `memory_layer_count: Integer`

      Count of memory layer assignments.

    - `model: ResourceMetadata`

      Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `score: Float`

      Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
      Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

    - `sub_agent_count: Integer`

      Number of sub-agents assigned to this variation

    - `tool_count: Integer`

      Number of individual tools assigned to this variation

    - `tool_set_count: Integer`

      Number of tool sets assigned to this variation

### Agent Variation Info

- `class AgentVariationInfo`

  AgentVariationInfo provides read-only summary information about a variation

  - `assignments: Array[VariationAssignment]`

    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.

    - `id: String`

    - `agent: 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.

      - `id: String`

      - `name: String`

        Human-readable name of the referenced resource, populated by the server
        on reads for convenience. Absent on references to resources that do not
        have a name (e.g., objective tasks).

    - `tool: 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.

    - `tool_set: 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.

  - `created_by: 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`

      AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: ProfileSpec`

      Configuration for a profile.

      - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

        Whether this profile represents a human user, an API key, or a system
        principal.

        - `:PROFILE_TYPE_UNSPECIFIED`

        - `:PROFILE_TYPE_USER`

        - `:PROFILE_TYPE_API_KEY`

        - `:PROFILE_TYPE_SYSTEM`

      - `email: String`

        Email address of the profile. Required and unique within an account for
        user profiles.

      - `name: String`

        Display name (e.g., "Bobby Tables").

  - `feedback_count: Integer`

    Total number of objective feedbacks received for this variation

  - `memory_layer_assignments: Array[VariationMemoryLayerAssignment]`

    Read-only list of memory layer assignments for this variation,
    returned in ascending `position` (bottom → top). Capped at 10 entries.

    - `id: String`

      Assignment row id — handle for removing the assignment. Distinct
      from the referenced memory layer's id.

    - `memory_layer: 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.

    - `position: Integer`

      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.

  - `memory_layer_count: Integer`

    Count of memory layer assignments.

  - `model: ResourceMetadata`

    Standard metadata for persistent, named resources (e.g., agents, tools, prompts)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `score: Float`

    Thompson Sampling score: posterior mean of Beta(ts_alpha, ts_beta).
    Range [0, 1] where 0.5 = neutral, >0.5 = positive, <0.5 = negative.

  - `sub_agent_count: Integer`

    Number of sub-agents assigned to this variation

  - `tool_count: Integer`

    Number of individual tools assigned to this variation

  - `tool_set_count: Integer`

    Number of tool sets assigned to this variation

### Agent Variation Spec

- `class AgentVariationSpec`

  AgentVariationSpec defines the operational configuration for a variation

  - `compaction_config: AgentVariationSpecCompactionConfig`

    CompactionConfig defines how context window compaction behaves for objectives using this variation.

    - `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."

    - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

      ToolResultClearingStrategy configures clearing of older tool result content.

      - `preserve_recent_results: 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

    - `trigger_threshold: 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%)

  - `constraints: AgentVariationSpecConstraints`

    Execution constraints

    - `max_sub_objectives: Integer`

      The maximum number of sub-objectives that can be created. 0 means no limit.

    - `max_tool_calls: Integer`

      The maximum number of tool calls that can be made. 0 means no limit.

  - `description: String`

    Human-readable description of what this variation does or when it should be used

  - `enable_episodic_memory: bool`

    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.

  - `episodic_memory_ttl: Integer`

    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.

  - `model_config: AgentVariationSpecModelConfig`

    ModelConfig defines the model configuration for a variation

    - `model_id: String`

      The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

    - `temperature: Float`

      Sampling temperature for model inference (0.0 to 1.0)
      Lower values produce more deterministic outputs, higher values increase randomness

  - `progressive_discovery: 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.

    - `hints: Array[String]`

    - `max_tools: Integer`

    - `rerank_threshold: Float`

      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.

  - `prompt: String`

    The system prompt for this variation

  - `weight: Integer`

    Weight for weighted random selection (>= 0). P(v) = v.weight / sum(all_weights).
    Only used when the agent's variation_selection_mode is WEIGHTED. A weight of 0 means never auto-selected, but can still be chosen explicitly via variation_id on CreateObjectiveRequest.

### Agent Variation Spec Compaction Config

- `class AgentVariationSpecCompactionConfig`

  CompactionConfig defines how context window compaction behaves for objectives using this variation.

  - `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."

  - `tool_result_clearing: CompactionConfigToolResultClearingStrategy`

    ToolResultClearingStrategy configures clearing of older tool result content.

    - `preserve_recent_results: 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

  - `trigger_threshold: 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%)

### Agent Variation Spec Constraints

- `class AgentVariationSpecConstraints`

  - `max_sub_objectives: Integer`

    The maximum number of sub-objectives that can be created. 0 means no limit.

  - `max_tool_calls: Integer`

    The maximum number of tool calls that can be made. 0 means no limit.

### Agent Variation Spec Model Config

- `class AgentVariationSpecModelConfig`

  ModelConfig defines the model configuration for a variation

  - `model_id: String`

    The model identifier in family/model format (e.g., "claude/opus-4.6", "claude/sonnet-4.5")

  - `temperature: Float`

    Sampling temperature for model inference (0.0 to 1.0)
    Lower values produce more deterministic outputs, higher values increase randomness

### Agent Variation Spec Progressive Discovery

- `class 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.

  - `hints: Array[String]`

  - `max_tools: Integer`

  - `rerank_threshold: Float`

    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.

### Compaction Config Summarization Strategy

- `class 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."

### Compaction Config Tool Result Clearing Strategy

- `class CompactionConfigToolResultClearingStrategy`

  ToolResultClearingStrategy configures clearing of older tool result content.

  - `preserve_recent_results: 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

### Variation Assignment

- `class VariationAssignment`

  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`.

  - `id: String`

  - `agent: 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.

    - `id: String`

    - `name: String`

      Human-readable name of the referenced resource, populated by the server
      on reads for convenience. Absent on references to resources that do not
      have a name (e.g., objective tasks).

  - `tool: 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.

  - `tool_set: 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.

### Variation Memory Layer Assignment

- `class VariationMemoryLayerAssignment`

  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: String`

    Assignment row id — handle for removing the assignment. Distinct
    from the referenced memory layer's id.

  - `memory_layer: 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.

    - `id: String`

    - `name: String`

      Human-readable name of the referenced resource, populated by the server
      on reads for convenience. Absent on references to resources that do not
      have a name (e.g., objective tasks).

  - `position: Integer`

    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.

# Schedules

## List schedules

`agents.schedules.list(agent_id, **kwargs) -> CursorPagination<AgentSchedule>`

**get** `/v1/workspaces/{workspaceId}/agents/{agentId}/schedules`

Lists all schedules for an agent

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `bundle_key: String`

  Filter by bundle_key — return only resources owned by this bundle.

- `cursor: String`

  Pagination cursor from previous response.

- `include_info: bool`

  When true, the `info` field on each returned schedule is populated.
  Requests with this flag count more against your rate limit.

- `limit: Integer`

  Maximum number of results to return.

- `prefix: String`

  Filter expression (query param: prefix).

- `query: String`

  Free-form search query.

- `sort_order: String`

  Sort order for results (asc or desc by creation time).

### Returns

- `class AgentSchedule`

  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)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentScheduleSpec`

    AgentScheduleSpec is the user-provided configuration for a schedule.

    - `initial_message: String`

      The initial message passed to CreateObjective on each fire. Becomes the
      first user message in the objective's chat history.

    - `schedule: AgentScheduleSpecSchedule`

      Schedule defines WHEN the schedule fires. Temporal-style structured form:
      a list of calendar rules (wall-clock) and/or interval rules (duration),
      OR'd together. At least one rule is required.

      - `calendars: Array[ScheduleCalendar]`

        Wall-clock rules. May be empty if `intervals` is non-empty.

        - `comment: String`

        - `day_of_month: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `day_of_week: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `hour: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `minute: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `month: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `second: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

      - `intervals: Array[ScheduleInterval]`

        Duration-based rules. May be empty if `calendars` is non-empty.

        - `every: String`

        - `offset: String`

          Phase shift within `every`. Must be < `every` (enforced at runtime).

      - `timezone: String`

        IANA tz name (e.g. "America/New_York"). Required. Applies to calendars;
        intervals fire on wall-clock cadence anchored in this zone.

    - `data: untyped`

      Optional input data passed to the objective. If the agent has an
      input_data_schema, this must satisfy it.

    - `overlap_policy: :OVERLAP_POLICY_UNSPECIFIED | :OVERLAP_POLICY_ALLOW | :OVERLAP_POLICY_SKIP`

      What to do when the previous run is still in flight. Defaults to SKIP.

      - `:OVERLAP_POLICY_UNSPECIFIED`

      - `:OVERLAP_POLICY_ALLOW`

      - `:OVERLAP_POLICY_SKIP`

    - `status: :AGENT_SCHEDULE_STATUS_UNSPECIFIED | :AGENT_SCHEDULE_STATUS_ACTIVE | :AGENT_SCHEDULE_STATUS_PAUSED | :AGENT_SCHEDULE_STATUS_ARCHIVED`

      Lifecycle. Defaults to ACTIVE on create when unspecified.

      - `:AGENT_SCHEDULE_STATUS_UNSPECIFIED`

      - `:AGENT_SCHEDULE_STATUS_ACTIVE`

      - `:AGENT_SCHEDULE_STATUS_PAUSED`

      - `:AGENT_SCHEDULE_STATUS_ARCHIVED`

    - `variation_id: String`

      Optional explicit variation. When unset, the agent's variation_selection_mode
      chooses per fire.

  - `info: AgentScheduleInfo`

    AgentScheduleInfo provides read-only runtime data about a schedule.

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `last_fire_at: Time`

      When the schedule last fired (regardless of objective outcome).

    - `last_objective_id: String`

      ID of the most recent objective the schedule created.

    - `last_skipped_at: Time`

      When the schedule most recently skipped a fire (SKIP policy + prior in flight).

    - `last_skip_reason: String`

      Reason for the most recent skip (e.g. "previous objective still running").

    - `next_fire_at: Time`

      When the schedule will next fire. Computed from the spec; absent when
      the schedule is PAUSED/ARCHIVED or has no future fire times.

    - `total_fires: Integer`

      Lifetime count of objectives created by this schedule.

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

page = cadenya.agents.schedules.list("agentId", workspace_id: "workspaceId")

puts(page)
```

#### Response

```json
{
  "items": [
    {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "createdAt": "2019-12-27T18:11:19.117Z",
        "name": "name",
        "profileId": "profileId",
        "workspaceId": "workspaceId",
        "bundleKey": "bundleKey",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "initialMessage": "initialMessage",
        "schedule": {
          "calendars": [
            {
              "comment": "comment",
              "dayOfMonth": [
                {
                  "end": 0,
                  "start": 0,
                  "step": 0
                }
              ],
              "dayOfWeek": [
                {
                  "end": 0,
                  "start": 0,
                  "step": 0
                }
              ],
              "hour": [
                {
                  "end": 0,
                  "start": 0,
                  "step": 0
                }
              ],
              "minute": [
                {
                  "end": 0,
                  "start": 0,
                  "step": 0
                }
              ],
              "month": [
                {
                  "end": 0,
                  "start": 0,
                  "step": 0
                }
              ],
              "second": [
                {
                  "end": 0,
                  "start": 0,
                  "step": 0
                }
              ]
            }
          ],
          "intervals": [
            {
              "every": "-160513s",
              "offset": "-160513s"
            }
          ],
          "timezone": "timezone"
        },
        "data": {},
        "overlapPolicy": "OVERLAP_POLICY_UNSPECIFIED",
        "status": "AGENT_SCHEDULE_STATUS_UNSPECIFIED",
        "variationId": "variationId"
      },
      "info": {
        "createdBy": {
          "metadata": {
            "id": "id",
            "accountId": "accountId",
            "name": "name",
            "profileId": "profileId",
            "externalId": "externalId",
            "labels": {
              "foo": "string"
            }
          },
          "spec": {
            "type": "PROFILE_TYPE_UNSPECIFIED",
            "email": "email",
            "name": "name"
          }
        },
        "lastFireAt": "2019-12-27T18:11:19.117Z",
        "lastObjectiveId": "lastObjectiveId",
        "lastSkippedAt": "2019-12-27T18:11:19.117Z",
        "lastSkipReason": "lastSkipReason",
        "nextFireAt": "2019-12-27T18:11:19.117Z",
        "totalFires": 0
      }
    }
  ],
  "pagination": {
    "nextCursor": "nextCursor",
    "total": 0
  }
}
```

## Create a new schedule

`agents.schedules.create(agent_id, **kwargs) -> AgentSchedule`

**post** `/v1/workspaces/{workspaceId}/agents/{agentId}/schedules`

Creates a new schedule for an agent

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `metadata: CreateResourceMetadata`

  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`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")

  - `bundle_key: String`

    Optional bundle ownership key. See ResourceMetadata.bundle_key.

  - `external_id: String`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}

- `spec: AgentScheduleSpec`

  AgentScheduleSpec is the user-provided configuration for a schedule.

  - `initial_message: String`

    The initial message passed to CreateObjective on each fire. Becomes the
    first user message in the objective's chat history.

  - `schedule: AgentScheduleSpecSchedule`

    Schedule defines WHEN the schedule fires. Temporal-style structured form:
    a list of calendar rules (wall-clock) and/or interval rules (duration),
    OR'd together. At least one rule is required.

    - `calendars: Array[ScheduleCalendar]`

      Wall-clock rules. May be empty if `intervals` is non-empty.

      - `comment: String`

      - `day_of_month: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `day_of_week: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `hour: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `minute: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `month: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `second: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

    - `intervals: Array[ScheduleInterval]`

      Duration-based rules. May be empty if `calendars` is non-empty.

      - `every: String`

      - `offset: String`

        Phase shift within `every`. Must be < `every` (enforced at runtime).

    - `timezone: String`

      IANA tz name (e.g. "America/New_York"). Required. Applies to calendars;
      intervals fire on wall-clock cadence anchored in this zone.

  - `data: untyped`

    Optional input data passed to the objective. If the agent has an
    input_data_schema, this must satisfy it.

  - `overlap_policy: :OVERLAP_POLICY_UNSPECIFIED | :OVERLAP_POLICY_ALLOW | :OVERLAP_POLICY_SKIP`

    What to do when the previous run is still in flight. Defaults to SKIP.

    - `:OVERLAP_POLICY_UNSPECIFIED`

    - `:OVERLAP_POLICY_ALLOW`

    - `:OVERLAP_POLICY_SKIP`

  - `status: :AGENT_SCHEDULE_STATUS_UNSPECIFIED | :AGENT_SCHEDULE_STATUS_ACTIVE | :AGENT_SCHEDULE_STATUS_PAUSED | :AGENT_SCHEDULE_STATUS_ARCHIVED`

    Lifecycle. Defaults to ACTIVE on create when unspecified.

    - `:AGENT_SCHEDULE_STATUS_UNSPECIFIED`

    - `:AGENT_SCHEDULE_STATUS_ACTIVE`

    - `:AGENT_SCHEDULE_STATUS_PAUSED`

    - `:AGENT_SCHEDULE_STATUS_ARCHIVED`

  - `variation_id: String`

    Optional explicit variation. When unset, the agent's variation_selection_mode
    chooses per fire.

### Returns

- `class AgentSchedule`

  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)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentScheduleSpec`

    AgentScheduleSpec is the user-provided configuration for a schedule.

    - `initial_message: String`

      The initial message passed to CreateObjective on each fire. Becomes the
      first user message in the objective's chat history.

    - `schedule: AgentScheduleSpecSchedule`

      Schedule defines WHEN the schedule fires. Temporal-style structured form:
      a list of calendar rules (wall-clock) and/or interval rules (duration),
      OR'd together. At least one rule is required.

      - `calendars: Array[ScheduleCalendar]`

        Wall-clock rules. May be empty if `intervals` is non-empty.

        - `comment: String`

        - `day_of_month: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `day_of_week: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `hour: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `minute: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `month: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `second: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

      - `intervals: Array[ScheduleInterval]`

        Duration-based rules. May be empty if `calendars` is non-empty.

        - `every: String`

        - `offset: String`

          Phase shift within `every`. Must be < `every` (enforced at runtime).

      - `timezone: String`

        IANA tz name (e.g. "America/New_York"). Required. Applies to calendars;
        intervals fire on wall-clock cadence anchored in this zone.

    - `data: untyped`

      Optional input data passed to the objective. If the agent has an
      input_data_schema, this must satisfy it.

    - `overlap_policy: :OVERLAP_POLICY_UNSPECIFIED | :OVERLAP_POLICY_ALLOW | :OVERLAP_POLICY_SKIP`

      What to do when the previous run is still in flight. Defaults to SKIP.

      - `:OVERLAP_POLICY_UNSPECIFIED`

      - `:OVERLAP_POLICY_ALLOW`

      - `:OVERLAP_POLICY_SKIP`

    - `status: :AGENT_SCHEDULE_STATUS_UNSPECIFIED | :AGENT_SCHEDULE_STATUS_ACTIVE | :AGENT_SCHEDULE_STATUS_PAUSED | :AGENT_SCHEDULE_STATUS_ARCHIVED`

      Lifecycle. Defaults to ACTIVE on create when unspecified.

      - `:AGENT_SCHEDULE_STATUS_UNSPECIFIED`

      - `:AGENT_SCHEDULE_STATUS_ACTIVE`

      - `:AGENT_SCHEDULE_STATUS_PAUSED`

      - `:AGENT_SCHEDULE_STATUS_ARCHIVED`

    - `variation_id: String`

      Optional explicit variation. When unset, the agent's variation_selection_mode
      chooses per fire.

  - `info: AgentScheduleInfo`

    AgentScheduleInfo provides read-only runtime data about a schedule.

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `last_fire_at: Time`

      When the schedule last fired (regardless of objective outcome).

    - `last_objective_id: String`

      ID of the most recent objective the schedule created.

    - `last_skipped_at: Time`

      When the schedule most recently skipped a fire (SKIP policy + prior in flight).

    - `last_skip_reason: String`

      Reason for the most recent skip (e.g. "previous objective still running").

    - `next_fire_at: Time`

      When the schedule will next fire. Computed from the spec; absent when
      the schedule is PAUSED/ARCHIVED or has no future fire times.

    - `total_fires: Integer`

      Lifetime count of objectives created by this schedule.

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

agent_schedule = cadenya.agents.schedules.create(
  "agentId",
  workspace_id: "workspaceId",
  metadata: {name: "name"},
  spec: {initialMessage: "initialMessage", schedule: {}}
)

puts(agent_schedule)
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "initialMessage": "initialMessage",
    "schedule": {
      "calendars": [
        {
          "comment": "comment",
          "dayOfMonth": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "dayOfWeek": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "hour": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "minute": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "month": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "second": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ]
        }
      ],
      "intervals": [
        {
          "every": "-160513s",
          "offset": "-160513s"
        }
      ],
      "timezone": "timezone"
    },
    "data": {},
    "overlapPolicy": "OVERLAP_POLICY_UNSPECIFIED",
    "status": "AGENT_SCHEDULE_STATUS_UNSPECIFIED",
    "variationId": "variationId"
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "lastFireAt": "2019-12-27T18:11:19.117Z",
    "lastObjectiveId": "lastObjectiveId",
    "lastSkippedAt": "2019-12-27T18:11:19.117Z",
    "lastSkipReason": "lastSkipReason",
    "nextFireAt": "2019-12-27T18:11:19.117Z",
    "totalFires": 0
  }
}
```

## Get a schedule by ID

`agents.schedules.retrieve(id, **kwargs) -> AgentSchedule`

**get** `/v1/workspaces/{workspaceId}/agents/{agentId}/schedules/{id}`

Retrieves a schedule by ID from an agent

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `id: String`

### Returns

- `class AgentSchedule`

  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)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentScheduleSpec`

    AgentScheduleSpec is the user-provided configuration for a schedule.

    - `initial_message: String`

      The initial message passed to CreateObjective on each fire. Becomes the
      first user message in the objective's chat history.

    - `schedule: AgentScheduleSpecSchedule`

      Schedule defines WHEN the schedule fires. Temporal-style structured form:
      a list of calendar rules (wall-clock) and/or interval rules (duration),
      OR'd together. At least one rule is required.

      - `calendars: Array[ScheduleCalendar]`

        Wall-clock rules. May be empty if `intervals` is non-empty.

        - `comment: String`

        - `day_of_month: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `day_of_week: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `hour: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `minute: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `month: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `second: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

      - `intervals: Array[ScheduleInterval]`

        Duration-based rules. May be empty if `calendars` is non-empty.

        - `every: String`

        - `offset: String`

          Phase shift within `every`. Must be < `every` (enforced at runtime).

      - `timezone: String`

        IANA tz name (e.g. "America/New_York"). Required. Applies to calendars;
        intervals fire on wall-clock cadence anchored in this zone.

    - `data: untyped`

      Optional input data passed to the objective. If the agent has an
      input_data_schema, this must satisfy it.

    - `overlap_policy: :OVERLAP_POLICY_UNSPECIFIED | :OVERLAP_POLICY_ALLOW | :OVERLAP_POLICY_SKIP`

      What to do when the previous run is still in flight. Defaults to SKIP.

      - `:OVERLAP_POLICY_UNSPECIFIED`

      - `:OVERLAP_POLICY_ALLOW`

      - `:OVERLAP_POLICY_SKIP`

    - `status: :AGENT_SCHEDULE_STATUS_UNSPECIFIED | :AGENT_SCHEDULE_STATUS_ACTIVE | :AGENT_SCHEDULE_STATUS_PAUSED | :AGENT_SCHEDULE_STATUS_ARCHIVED`

      Lifecycle. Defaults to ACTIVE on create when unspecified.

      - `:AGENT_SCHEDULE_STATUS_UNSPECIFIED`

      - `:AGENT_SCHEDULE_STATUS_ACTIVE`

      - `:AGENT_SCHEDULE_STATUS_PAUSED`

      - `:AGENT_SCHEDULE_STATUS_ARCHIVED`

    - `variation_id: String`

      Optional explicit variation. When unset, the agent's variation_selection_mode
      chooses per fire.

  - `info: AgentScheduleInfo`

    AgentScheduleInfo provides read-only runtime data about a schedule.

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `last_fire_at: Time`

      When the schedule last fired (regardless of objective outcome).

    - `last_objective_id: String`

      ID of the most recent objective the schedule created.

    - `last_skipped_at: Time`

      When the schedule most recently skipped a fire (SKIP policy + prior in flight).

    - `last_skip_reason: String`

      Reason for the most recent skip (e.g. "previous objective still running").

    - `next_fire_at: Time`

      When the schedule will next fire. Computed from the spec; absent when
      the schedule is PAUSED/ARCHIVED or has no future fire times.

    - `total_fires: Integer`

      Lifetime count of objectives created by this schedule.

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

agent_schedule = cadenya.agents.schedules.retrieve("id", workspace_id: "workspaceId", agent_id: "agentId")

puts(agent_schedule)
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "initialMessage": "initialMessage",
    "schedule": {
      "calendars": [
        {
          "comment": "comment",
          "dayOfMonth": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "dayOfWeek": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "hour": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "minute": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "month": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "second": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ]
        }
      ],
      "intervals": [
        {
          "every": "-160513s",
          "offset": "-160513s"
        }
      ],
      "timezone": "timezone"
    },
    "data": {},
    "overlapPolicy": "OVERLAP_POLICY_UNSPECIFIED",
    "status": "AGENT_SCHEDULE_STATUS_UNSPECIFIED",
    "variationId": "variationId"
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "lastFireAt": "2019-12-27T18:11:19.117Z",
    "lastObjectiveId": "lastObjectiveId",
    "lastSkippedAt": "2019-12-27T18:11:19.117Z",
    "lastSkipReason": "lastSkipReason",
    "nextFireAt": "2019-12-27T18:11:19.117Z",
    "totalFires": 0
  }
}
```

## Delete a schedule

`agents.schedules.delete(id, **kwargs) -> void`

**delete** `/v1/workspaces/{workspaceId}/agents/{agentId}/schedules/{id}`

Deletes a schedule from an agent

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `id: String`

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

result = cadenya.agents.schedules.delete("id", workspace_id: "workspaceId", agent_id: "agentId")

puts(result)
```

## Update a schedule

`agents.schedules.update(id, **kwargs) -> AgentSchedule`

**patch** `/v1/workspaces/{workspaceId}/agents/{agentId}/schedules/{id}`

Updates a schedule for an agent

### Parameters

- `workspace_id: String`

- `agent_id: String`

- `id: String`

- `metadata: UpdateResourceMetadata`

  UpdateResourceMetadata contains the user-provided fields for updating
  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`

    Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")

  - `bundle_key: String`

    Optional bundle ownership key. See ResourceMetadata.bundle_key.

  - `external_id: String`

    External ID for the resource (e.g., a workflow ID from an external system)

  - `labels: Hash[Symbol, String]`

    Arbitrary key-value pairs for categorization and filtering
    Examples: {"environment": "production", "team": "platform", "version": "v2"}

- `spec: AgentScheduleSpec`

  AgentScheduleSpec is the user-provided configuration for a schedule.

  - `initial_message: String`

    The initial message passed to CreateObjective on each fire. Becomes the
    first user message in the objective's chat history.

  - `schedule: AgentScheduleSpecSchedule`

    Schedule defines WHEN the schedule fires. Temporal-style structured form:
    a list of calendar rules (wall-clock) and/or interval rules (duration),
    OR'd together. At least one rule is required.

    - `calendars: Array[ScheduleCalendar]`

      Wall-clock rules. May be empty if `intervals` is non-empty.

      - `comment: String`

      - `day_of_month: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `day_of_week: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `hour: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `minute: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `month: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `second: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

    - `intervals: Array[ScheduleInterval]`

      Duration-based rules. May be empty if `calendars` is non-empty.

      - `every: String`

      - `offset: String`

        Phase shift within `every`. Must be < `every` (enforced at runtime).

    - `timezone: String`

      IANA tz name (e.g. "America/New_York"). Required. Applies to calendars;
      intervals fire on wall-clock cadence anchored in this zone.

  - `data: untyped`

    Optional input data passed to the objective. If the agent has an
    input_data_schema, this must satisfy it.

  - `overlap_policy: :OVERLAP_POLICY_UNSPECIFIED | :OVERLAP_POLICY_ALLOW | :OVERLAP_POLICY_SKIP`

    What to do when the previous run is still in flight. Defaults to SKIP.

    - `:OVERLAP_POLICY_UNSPECIFIED`

    - `:OVERLAP_POLICY_ALLOW`

    - `:OVERLAP_POLICY_SKIP`

  - `status: :AGENT_SCHEDULE_STATUS_UNSPECIFIED | :AGENT_SCHEDULE_STATUS_ACTIVE | :AGENT_SCHEDULE_STATUS_PAUSED | :AGENT_SCHEDULE_STATUS_ARCHIVED`

    Lifecycle. Defaults to ACTIVE on create when unspecified.

    - `:AGENT_SCHEDULE_STATUS_UNSPECIFIED`

    - `:AGENT_SCHEDULE_STATUS_ACTIVE`

    - `:AGENT_SCHEDULE_STATUS_PAUSED`

    - `:AGENT_SCHEDULE_STATUS_ARCHIVED`

  - `variation_id: String`

    Optional explicit variation. When unset, the agent's variation_selection_mode
    chooses per fire.

- `update_mask: String`

  Fields to update.

### Returns

- `class AgentSchedule`

  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)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentScheduleSpec`

    AgentScheduleSpec is the user-provided configuration for a schedule.

    - `initial_message: String`

      The initial message passed to CreateObjective on each fire. Becomes the
      first user message in the objective's chat history.

    - `schedule: AgentScheduleSpecSchedule`

      Schedule defines WHEN the schedule fires. Temporal-style structured form:
      a list of calendar rules (wall-clock) and/or interval rules (duration),
      OR'd together. At least one rule is required.

      - `calendars: Array[ScheduleCalendar]`

        Wall-clock rules. May be empty if `intervals` is non-empty.

        - `comment: String`

        - `day_of_month: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `day_of_week: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `hour: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `minute: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `month: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `second: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

      - `intervals: Array[ScheduleInterval]`

        Duration-based rules. May be empty if `calendars` is non-empty.

        - `every: String`

        - `offset: String`

          Phase shift within `every`. Must be < `every` (enforced at runtime).

      - `timezone: String`

        IANA tz name (e.g. "America/New_York"). Required. Applies to calendars;
        intervals fire on wall-clock cadence anchored in this zone.

    - `data: untyped`

      Optional input data passed to the objective. If the agent has an
      input_data_schema, this must satisfy it.

    - `overlap_policy: :OVERLAP_POLICY_UNSPECIFIED | :OVERLAP_POLICY_ALLOW | :OVERLAP_POLICY_SKIP`

      What to do when the previous run is still in flight. Defaults to SKIP.

      - `:OVERLAP_POLICY_UNSPECIFIED`

      - `:OVERLAP_POLICY_ALLOW`

      - `:OVERLAP_POLICY_SKIP`

    - `status: :AGENT_SCHEDULE_STATUS_UNSPECIFIED | :AGENT_SCHEDULE_STATUS_ACTIVE | :AGENT_SCHEDULE_STATUS_PAUSED | :AGENT_SCHEDULE_STATUS_ARCHIVED`

      Lifecycle. Defaults to ACTIVE on create when unspecified.

      - `:AGENT_SCHEDULE_STATUS_UNSPECIFIED`

      - `:AGENT_SCHEDULE_STATUS_ACTIVE`

      - `:AGENT_SCHEDULE_STATUS_PAUSED`

      - `:AGENT_SCHEDULE_STATUS_ARCHIVED`

    - `variation_id: String`

      Optional explicit variation. When unset, the agent's variation_selection_mode
      chooses per fire.

  - `info: AgentScheduleInfo`

    AgentScheduleInfo provides read-only runtime data about a schedule.

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `last_fire_at: Time`

      When the schedule last fired (regardless of objective outcome).

    - `last_objective_id: String`

      ID of the most recent objective the schedule created.

    - `last_skipped_at: Time`

      When the schedule most recently skipped a fire (SKIP policy + prior in flight).

    - `last_skip_reason: String`

      Reason for the most recent skip (e.g. "previous objective still running").

    - `next_fire_at: Time`

      When the schedule will next fire. Computed from the spec; absent when
      the schedule is PAUSED/ARCHIVED or has no future fire times.

    - `total_fires: Integer`

      Lifetime count of objectives created by this schedule.

### Example

```ruby
require "cadenya"

cadenya = Cadenya::Client.new(api_key: "My API Key")

agent_schedule = cadenya.agents.schedules.update("id", workspace_id: "workspaceId", agent_id: "agentId")

puts(agent_schedule)
```

#### Response

```json
{
  "metadata": {
    "id": "id",
    "accountId": "accountId",
    "createdAt": "2019-12-27T18:11:19.117Z",
    "name": "name",
    "profileId": "profileId",
    "workspaceId": "workspaceId",
    "bundleKey": "bundleKey",
    "externalId": "externalId",
    "labels": {
      "foo": "string"
    }
  },
  "spec": {
    "initialMessage": "initialMessage",
    "schedule": {
      "calendars": [
        {
          "comment": "comment",
          "dayOfMonth": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "dayOfWeek": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "hour": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "minute": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "month": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ],
          "second": [
            {
              "end": 0,
              "start": 0,
              "step": 0
            }
          ]
        }
      ],
      "intervals": [
        {
          "every": "-160513s",
          "offset": "-160513s"
        }
      ],
      "timezone": "timezone"
    },
    "data": {},
    "overlapPolicy": "OVERLAP_POLICY_UNSPECIFIED",
    "status": "AGENT_SCHEDULE_STATUS_UNSPECIFIED",
    "variationId": "variationId"
  },
  "info": {
    "createdBy": {
      "metadata": {
        "id": "id",
        "accountId": "accountId",
        "name": "name",
        "profileId": "profileId",
        "externalId": "externalId",
        "labels": {
          "foo": "string"
        }
      },
      "spec": {
        "type": "PROFILE_TYPE_UNSPECIFIED",
        "email": "email",
        "name": "name"
      }
    },
    "lastFireAt": "2019-12-27T18:11:19.117Z",
    "lastObjectiveId": "lastObjectiveId",
    "lastSkippedAt": "2019-12-27T18:11:19.117Z",
    "lastSkipReason": "lastSkipReason",
    "nextFireAt": "2019-12-27T18:11:19.117Z",
    "totalFires": 0
  }
}
```

## Domain Types

### Agent Schedule

- `class AgentSchedule`

  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)

    - `id: String`

      Unique identifier for the resource (prefixed ULID, e.g., "agent_01HXK...")

    - `account_id: String`

      Account this resource belongs to for multi-tenant isolation (prefixed ULID)

    - `created_at: Time`

      Timestamp when this resource was created

    - `name: String`

      Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
      Required for resources that users interact with directly

    - `profile_id: String`

      ID of the actor (user or service account) that created this resource

    - `workspace_id: String`

      Workspace this resource belongs to for organizational grouping (prefixed ULID)

    - `bundle_key: String`

      Optional bundle ownership key. When set, indicates the resource is
      managed by a configuration bundle identified by this key. Used by
      BulkWorkspaceResources.Apply to track which resources belong to which
      bundle for reconciliation / soft-delete on re-apply.

    - `external_id: String`

      External ID for the resource (e.g., a workflow ID from an external system)

    - `labels: Hash[Symbol, String]`

      Arbitrary key-value pairs for categorization and filtering
      Examples: {"environment": "production", "team": "platform", "version": "v2"}

  - `spec: AgentScheduleSpec`

    AgentScheduleSpec is the user-provided configuration for a schedule.

    - `initial_message: String`

      The initial message passed to CreateObjective on each fire. Becomes the
      first user message in the objective's chat history.

    - `schedule: AgentScheduleSpecSchedule`

      Schedule defines WHEN the schedule fires. Temporal-style structured form:
      a list of calendar rules (wall-clock) and/or interval rules (duration),
      OR'd together. At least one rule is required.

      - `calendars: Array[ScheduleCalendar]`

        Wall-clock rules. May be empty if `intervals` is non-empty.

        - `comment: String`

        - `day_of_month: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `day_of_week: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `hour: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `minute: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `month: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

        - `second: Array[ScheduleRange]`

          - `end_: Integer`

          - `start: Integer`

          - `step: Integer`

      - `intervals: Array[ScheduleInterval]`

        Duration-based rules. May be empty if `calendars` is non-empty.

        - `every: String`

        - `offset: String`

          Phase shift within `every`. Must be < `every` (enforced at runtime).

      - `timezone: String`

        IANA tz name (e.g. "America/New_York"). Required. Applies to calendars;
        intervals fire on wall-clock cadence anchored in this zone.

    - `data: untyped`

      Optional input data passed to the objective. If the agent has an
      input_data_schema, this must satisfy it.

    - `overlap_policy: :OVERLAP_POLICY_UNSPECIFIED | :OVERLAP_POLICY_ALLOW | :OVERLAP_POLICY_SKIP`

      What to do when the previous run is still in flight. Defaults to SKIP.

      - `:OVERLAP_POLICY_UNSPECIFIED`

      - `:OVERLAP_POLICY_ALLOW`

      - `:OVERLAP_POLICY_SKIP`

    - `status: :AGENT_SCHEDULE_STATUS_UNSPECIFIED | :AGENT_SCHEDULE_STATUS_ACTIVE | :AGENT_SCHEDULE_STATUS_PAUSED | :AGENT_SCHEDULE_STATUS_ARCHIVED`

      Lifecycle. Defaults to ACTIVE on create when unspecified.

      - `:AGENT_SCHEDULE_STATUS_UNSPECIFIED`

      - `:AGENT_SCHEDULE_STATUS_ACTIVE`

      - `:AGENT_SCHEDULE_STATUS_PAUSED`

      - `:AGENT_SCHEDULE_STATUS_ARCHIVED`

    - `variation_id: String`

      Optional explicit variation. When unset, the agent's variation_selection_mode
      chooses per fire.

  - `info: AgentScheduleInfo`

    AgentScheduleInfo provides read-only runtime data about a schedule.

    - `created_by: 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`

        AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

        - `id: String`

          Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

        - `account_id: String`

          Account this resource belongs to for multi-tenant isolation (prefixed ULID)

        - `name: String`

          Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
          Required for resources that users interact with directly

        - `profile_id: String`

        - `external_id: String`

          External ID for the resource (e.g., a workflow ID from an external system)

        - `labels: Hash[Symbol, String]`

          Arbitrary key-value pairs for categorization and filtering
          Examples: {"environment": "production", "team": "platform", "version": "v2"}

      - `spec: ProfileSpec`

        Configuration for a profile.

        - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

          Whether this profile represents a human user, an API key, or a system
          principal.

          - `:PROFILE_TYPE_UNSPECIFIED`

          - `:PROFILE_TYPE_USER`

          - `:PROFILE_TYPE_API_KEY`

          - `:PROFILE_TYPE_SYSTEM`

        - `email: String`

          Email address of the profile. Required and unique within an account for
          user profiles.

        - `name: String`

          Display name (e.g., "Bobby Tables").

    - `last_fire_at: Time`

      When the schedule last fired (regardless of objective outcome).

    - `last_objective_id: String`

      ID of the most recent objective the schedule created.

    - `last_skipped_at: Time`

      When the schedule most recently skipped a fire (SKIP policy + prior in flight).

    - `last_skip_reason: String`

      Reason for the most recent skip (e.g. "previous objective still running").

    - `next_fire_at: Time`

      When the schedule will next fire. Computed from the spec; absent when
      the schedule is PAUSED/ARCHIVED or has no future fire times.

    - `total_fires: Integer`

      Lifetime count of objectives created by this schedule.

### Agent Schedule Info

- `class AgentScheduleInfo`

  AgentScheduleInfo provides read-only runtime data about a schedule.

  - `created_by: 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`

      AccountResourceMetadata is used to represent a resource that is associated to an account but not to a workspace.

      - `id: String`

        Unique identifier for the resource (prefixed ULID, e.g., "apikey_01HXK...")

      - `account_id: String`

        Account this resource belongs to for multi-tenant isolation (prefixed ULID)

      - `name: String`

        Human-readable name for the resource (e.g., "Customer Support Agent", "Email Tool")
        Required for resources that users interact with directly

      - `profile_id: String`

      - `external_id: String`

        External ID for the resource (e.g., a workflow ID from an external system)

      - `labels: Hash[Symbol, String]`

        Arbitrary key-value pairs for categorization and filtering
        Examples: {"environment": "production", "team": "platform", "version": "v2"}

    - `spec: ProfileSpec`

      Configuration for a profile.

      - `type: :PROFILE_TYPE_UNSPECIFIED | :PROFILE_TYPE_USER | :PROFILE_TYPE_API_KEY | :PROFILE_TYPE_SYSTEM`

        Whether this profile represents a human user, an API key, or a system
        principal.

        - `:PROFILE_TYPE_UNSPECIFIED`

        - `:PROFILE_TYPE_USER`

        - `:PROFILE_TYPE_API_KEY`

        - `:PROFILE_TYPE_SYSTEM`

      - `email: String`

        Email address of the profile. Required and unique within an account for
        user profiles.

      - `name: String`

        Display name (e.g., "Bobby Tables").

  - `last_fire_at: Time`

    When the schedule last fired (regardless of objective outcome).

  - `last_objective_id: String`

    ID of the most recent objective the schedule created.

  - `last_skipped_at: Time`

    When the schedule most recently skipped a fire (SKIP policy + prior in flight).

  - `last_skip_reason: String`

    Reason for the most recent skip (e.g. "previous objective still running").

  - `next_fire_at: Time`

    When the schedule will next fire. Computed from the spec; absent when
    the schedule is PAUSED/ARCHIVED or has no future fire times.

  - `total_fires: Integer`

    Lifetime count of objectives created by this schedule.

### Agent Schedule Spec

- `class AgentScheduleSpec`

  AgentScheduleSpec is the user-provided configuration for a schedule.

  - `initial_message: String`

    The initial message passed to CreateObjective on each fire. Becomes the
    first user message in the objective's chat history.

  - `schedule: AgentScheduleSpecSchedule`

    Schedule defines WHEN the schedule fires. Temporal-style structured form:
    a list of calendar rules (wall-clock) and/or interval rules (duration),
    OR'd together. At least one rule is required.

    - `calendars: Array[ScheduleCalendar]`

      Wall-clock rules. May be empty if `intervals` is non-empty.

      - `comment: String`

      - `day_of_month: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `day_of_week: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `hour: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `minute: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `month: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

      - `second: Array[ScheduleRange]`

        - `end_: Integer`

        - `start: Integer`

        - `step: Integer`

    - `intervals: Array[ScheduleInterval]`

      Duration-based rules. May be empty if `calendars` is non-empty.

      - `every: String`

      - `offset: String`

        Phase shift within `every`. Must be < `every` (enforced at runtime).

    - `timezone: String`

      IANA tz name (e.g. "America/New_York"). Required. Applies to calendars;
      intervals fire on wall-clock cadence anchored in this zone.

  - `data: untyped`

    Optional input data passed to the objective. If the agent has an
    input_data_schema, this must satisfy it.

  - `overlap_policy: :OVERLAP_POLICY_UNSPECIFIED | :OVERLAP_POLICY_ALLOW | :OVERLAP_POLICY_SKIP`

    What to do when the previous run is still in flight. Defaults to SKIP.

    - `:OVERLAP_POLICY_UNSPECIFIED`

    - `:OVERLAP_POLICY_ALLOW`

    - `:OVERLAP_POLICY_SKIP`

  - `status: :AGENT_SCHEDULE_STATUS_UNSPECIFIED | :AGENT_SCHEDULE_STATUS_ACTIVE | :AGENT_SCHEDULE_STATUS_PAUSED | :AGENT_SCHEDULE_STATUS_ARCHIVED`

    Lifecycle. Defaults to ACTIVE on create when unspecified.

    - `:AGENT_SCHEDULE_STATUS_UNSPECIFIED`

    - `:AGENT_SCHEDULE_STATUS_ACTIVE`

    - `:AGENT_SCHEDULE_STATUS_PAUSED`

    - `:AGENT_SCHEDULE_STATUS_ARCHIVED`

  - `variation_id: String`

    Optional explicit variation. When unset, the agent's variation_selection_mode
    chooses per fire.

### Agent Schedule Spec Schedule

- `class AgentScheduleSpecSchedule`

  Schedule defines WHEN the schedule fires. Temporal-style structured form:
  a list of calendar rules (wall-clock) and/or interval rules (duration),
  OR'd together. At least one rule is required.

  - `calendars: Array[ScheduleCalendar]`

    Wall-clock rules. May be empty if `intervals` is non-empty.

    - `comment: String`

    - `day_of_month: Array[ScheduleRange]`

      - `end_: Integer`

      - `start: Integer`

      - `step: Integer`

    - `day_of_week: Array[ScheduleRange]`

      - `end_: Integer`

      - `start: Integer`

      - `step: Integer`

    - `hour: Array[ScheduleRange]`

      - `end_: Integer`

      - `start: Integer`

      - `step: Integer`

    - `minute: Array[ScheduleRange]`

      - `end_: Integer`

      - `start: Integer`

      - `step: Integer`

    - `month: Array[ScheduleRange]`

      - `end_: Integer`

      - `start: Integer`

      - `step: Integer`

    - `second: Array[ScheduleRange]`

      - `end_: Integer`

      - `start: Integer`

      - `step: Integer`

  - `intervals: Array[ScheduleInterval]`

    Duration-based rules. May be empty if `calendars` is non-empty.

    - `every: String`

    - `offset: String`

      Phase shift within `every`. Must be < `every` (enforced at runtime).

  - `timezone: String`

    IANA tz name (e.g. "America/New_York"). Required. Applies to calendars;
    intervals fire on wall-clock cadence anchored in this zone.

### Schedule Calendar

- `class ScheduleCalendar`

  Calendar is a wall-clock rule. Empty field-list semantics:

  - second/minute/hour: empty means [{start: 0}] (top of the unit)
  - day_of_month/month/day_of_week: empty means "any value"
    Fire times = cartesian product across all fields.

  - `comment: String`

  - `day_of_month: Array[ScheduleRange]`

    - `end_: Integer`

    - `start: Integer`

    - `step: Integer`

  - `day_of_week: Array[ScheduleRange]`

    - `end_: Integer`

    - `start: Integer`

    - `step: Integer`

  - `hour: Array[ScheduleRange]`

    - `end_: Integer`

    - `start: Integer`

    - `step: Integer`

  - `minute: Array[ScheduleRange]`

    - `end_: Integer`

    - `start: Integer`

    - `step: Integer`

  - `month: Array[ScheduleRange]`

    - `end_: Integer`

    - `start: Integer`

    - `step: Integer`

  - `second: Array[ScheduleRange]`

    - `end_: Integer`

    - `start: Integer`

    - `step: Integer`

### Schedule Interval

- `class ScheduleInterval`

  Interval is a duration-based rule. Fires every `every` from a stable
  anchor (workspace epoch), optionally phase-shifted by `offset`.

  - `every: String`

  - `offset: String`

    Phase shift within `every`. Must be < `every` (enforced at runtime).

### Schedule Range

- `class ScheduleRange`

  Inclusive numeric range with optional step.
  {start: 9}                    → 9
  {start: 9, end: 17}           → 9..17
  {start: 0, end: 59, step: 15} → 0,15,30,45
  `end` defaults to `start`; `step` defaults to 1.

  - `end_: Integer`

  - `start: Integer`

  - `step: Integer`