API Reference

Agents

Variations

Copy Markdown

Open in Claude

Open in ChatGPT

Open in Cursor

---

Copy Markdown

View as Markdown

Add an assignment to a variation

agents.variations.add_assignment(variation_id, **kwargs) -> VariationAssignment { id, agent, tool, tool_set }

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.

ParametersExpand Collapse

workspace_id: String

agent_id: String

variation_id: String

sub_agent_id: String

tool_id: String

tool_set_id: String

ReturnsExpand Collapse

class VariationAssignment { id, agent, tool, tool_set }

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 { id, name }

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 { id, name }

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_set: BareMetadata { id, name }

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

Add an assignment to a variation

Ruby

HTTP

TypeScript

Go

Ruby

CLI Tool

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)

200 example

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

Returns Examples

200 example

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