## Add an assignment to a variation

`$ cadenya agent-variations add-assignment`

**post** `/v1/agent_variations/{agentVariationId}/assignments`

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

### Parameters

- `--agent-variation-id: string`

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

- `--tool-id: optional string`

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

### Returns

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

  VariationAssignment is a read-only reference to a single tool, tool set, or
  sub-agent attached to a variation. Clients read the full set of assignments
  via `AgentVariationInfo.assignments`; mutations go through the dedicated
  add/remove assignment endpoints under /v1/agent_variations/{id}/assignments.

  The `id` identifies the assignment row 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 agent-variations add-assignment \
  --api-key 'My API Key' \
  --agent-variation-id agentVariationId
```

#### Response

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