> ## Documentation Index
> Fetch the complete documentation index at: https://docs.mosaic.so/llms.txt
> Use this file to discover all available pages before exploring further.

# Update Agent

> Update agent metadata and/or mutate graph structure.

Updates an existing agent.

Graph mutation is action-based: send ordered `operations` (`create_node`, `update_node`, `delete_node`, `create_connection`, `delete_connection`).

Node positions are always backend-managed (auto-layout).

## Request

```bash theme={null}
curl -X POST "https://api.mosaic.so/agent/123e4567-e89b-12d3-a456-789012345678/update" \
  -H "Authorization: Bearer mk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "operations": [
      {
        "op": "create_node",
        "temp_ref_id": "video_input_1",
        "node_type_id": "9451e6ff-ac7f-4317-9055-a2f35f641b29"
      },
      {
        "op": "create_node",
        "temp_ref_id": "captions_1",
        "node_type_id": "cdccb204-168e-4aec-aa72-480b11e74324",
        "params_used": {
          "caption_style": "colored"
        }
      },
      {
        "op": "create_connection",
        "source_temp_ref_id": "video_input_1",
        "target_temp_ref_id": "captions_1"
      }
    ]
  }'
```

You can also call the same operation with `PATCH /agent/{agent_id}/update`.

## Body Parameters

| Field          | Type   | Required | Description                                             |
| -------------- | ------ | -------- | ------------------------------------------------------- |
| `name`         | string | No       | Agent name (`1-120` chars).                             |
| `description`  | string | No       | Agent description (`<=5000` chars).                     |
| `visibility`   | string | No       | `public` or `private`.                                  |
| `operations[]` | array  | No       | Ordered graph operations for node/connection mutations. |

At least one of `name`, `description`, `visibility`, or `operations` is required.

## Operation Types (Detailed)

### `create_node`

| Field          | Type          | Required | Description                                                                                                                      |
| -------------- | ------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `op`           | string        | Yes      | Must be `"create_node"`.                                                                                                         |
| `node_type_id` | string (UUID) | Yes      | Node type to instantiate.                                                                                                        |
| `temp_ref_id`  | string        | No       | Request-scoped temporary reference for this newly created node. Use this in later operations in the same request. Not persisted. |
| `params_used`  | object        | No       | Initial node parameters.                                                                                                         |

Backend behavior: creates a new node, assigns a persisted `agent_node_id`, and returns mapping details in `created_nodes`. You cannot supply `agent_node_id` in `create_node`; use returned IDs for later operations.

`temp_ref_id` is only valid within the current update request. It is never saved and cannot be reused in future update calls.

### `update_node`

| Field           | Type          | Required | Description                                             |
| --------------- | ------------- | -------- | ------------------------------------------------------- |
| `op`            | string        | Yes      | Must be `"update_node"`.                                |
| `agent_node_id` | string (UUID) | Yes      | Existing persisted node to update.                      |
| `params_used`   | object        | Yes      | Parameter patch object merged into current node params. |

### `delete_node`

| Field           | Type          | Required | Description                        |
| --------------- | ------------- | -------- | ---------------------------------- |
| `op`            | string        | Yes      | Must be `"delete_node"`.           |
| `agent_node_id` | string (UUID) | Yes      | Existing persisted node to delete. |

Backend behavior: also removes connections where this node is source or target.

### `create_connection`

| Field                  | Type          | Required    | Description                                                                                                           |
| ---------------------- | ------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `op`                   | string        | Yes         | Must be `"create_connection"`.                                                                                        |
| `source_agent_node_id` | string (UUID) | Conditional | Source existing node ID. Provide this **or** `source_temp_ref_id`.                                                    |
| `source_temp_ref_id`   | string        | Conditional | Source temp ref from earlier `create_node` operation in the same request. Provide this **or** `source_agent_node_id`. |
| `target_agent_node_id` | string (UUID) | Conditional | Target existing node ID. Provide this **or** `target_temp_ref_id`.                                                    |
| `target_temp_ref_id`   | string        | Conditional | Target temp ref from earlier `create_node` operation in the same request. Provide this **or** `target_agent_node_id`. |

Rules:

* Provide exactly one source reference (`source_agent_node_id` or `source_temp_ref_id`).
* Provide exactly one target reference (`target_agent_node_id` or `target_temp_ref_id`).
* `source_temp_ref_id` and `target_temp_ref_id` must reference a `temp_ref_id` created by an **earlier** `create_node` operation in the same request.

Mutation execution is atomic: if any operation fails validation or persistence, no graph changes are saved.
Error messages include the operation step (for example, `Operation 3: ...`) to make retries deterministic.

### `delete_connection`

| Field                  | Type          | Required    | Description                                                                                                           |
| ---------------------- | ------------- | ----------- | --------------------------------------------------------------------------------------------------------------------- |
| `op`                   | string        | Yes         | Must be `"delete_connection"`.                                                                                        |
| `source_agent_node_id` | string (UUID) | Conditional | Source existing node ID. Provide this **or** `source_temp_ref_id`.                                                    |
| `source_temp_ref_id`   | string        | Conditional | Source temp ref from earlier `create_node` operation in the same request. Provide this **or** `source_agent_node_id`. |
| `target_agent_node_id` | string (UUID) | Conditional | Target existing node ID. Provide this **or** `target_temp_ref_id`.                                                    |
| `target_temp_ref_id`   | string        | Conditional | Target temp ref from earlier `create_node` operation in the same request. Provide this **or** `target_agent_node_id`. |

To **rewire** a connection, send `delete_connection` then `create_connection` in the same `operations` array; execution order is preserved and applied atomically.

## Response

```json theme={null}
{
  "success": true,
  "agent_id": "123e4567-e89b-12d3-a456-789012345678",
  "operations_applied": 3,
  "created_nodes": [
    {
      "temp_ref_id": "video_input_1",
      "agent_node_id": "11111111-1111-1111-1111-111111111111"
    },
    {
      "temp_ref_id": "captions_1",
      "agent_node_id": "22222222-2222-2222-2222-222222222222"
    }
  ]
}
```

## Validation Error Response

When parameter validation fails, the API returns all detected issues in one response:

```json theme={null}
{
  "detail": "Invalid node parameters: Node 11111111-1111-1111-1111-111111111111: unknown parameter 'bad_key'; Node 22222222-2222-2222-2222-222222222222: Required parameter 'prompt' is missing",
  "issues": [
    {
      "code": "unknown_parameter",
      "message": "unknown parameter 'bad_key'",
      "node_id": "11111111-1111-1111-1111-111111111111",
      "node_type_id": "9451e6ff-ac7f-4317-9055-a2f35f641b29",
      "param_name": "bad_key",
      "operation_step": 1
    },
    {
      "code": "invalid_parameter",
      "message": "Required parameter 'prompt' is missing",
      "node_id": "22222222-2222-2222-2222-222222222222",
      "node_type_id": "cdccb204-168e-4aec-aa72-480b11e74324",
      "param_name": "prompt",
      "operation_step": 2
    }
  ]
}
```