## Add an assignment to a variation

`$ cadenya agents:variations add-assignment`

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

  Workspace ID.

- `--agent-id: string`

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

- `--variation-id: string`

  Variation ID. Accepts the canonical `av_…` form or the `external_id:<value>` form.

- `--sub-agent-id: optional string`

- `--tool-id: optional string`

- `--tool-set-id: optional string`

### Returns

- `variation_assignment: object { id, agent, tool, toolSet }`

  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: optional string`

  - `agent: optional object { 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: optional string`

    - `name: optional 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: optional object { 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: optional string`

    - `name: optional 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).

  - `toolSet: optional object { 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: optional string`

    - `name: optional 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).

### Example

```cli
cadenya agents:variations add-assignment \
  --api-key 'My API Key' \
  --workspace-id workspaceId \
  --agent-id agentId \
  --variation-id variationId
```

#### Response

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