# agent_save

Create or Update Agent

## Beschreibung

Linear-style upsert for AI agent personas. Pass `id` (prefix
`agnt_…`) to update, omit to create.

On create:
- `name` is required. The agent belongs to `account_id` and
  is visible to every member of that account.
- `creator_id` is set to the current user.
- `creator_role` is snapshotted from your role at this
  moment ("admin" or "employer"). The snapshot is frozen —
  a later role change can't reach back and unlock (or
  lock) this row.

On update:
- Only fields you pass are changed.
- `creator_role` is immutable.

`tools` is a free-form JSON array — list whichever tool
names the runner expects (e.g. `["chat_send_message",
"task_save"]`).

## Zugriff

Zugriffsprofil: `gated`. Module: `none`.
Die Freigabe im Profil ersetzt keine Account-, Workspace- oder Rollenberechtigung.

## Parameter

| Name | Typ | Pflicht | Beschreibung |
| --- | --- | --- | --- |
| `account_id` | string | Ja |  |
| `id` | string | Nein | Agent prefix id (agnt_…). Omit to create. |
| `name` | string | Nein | Required on create. ≤ 120 chars. |
| `system_prompt` | string / null | Nein |  |
| `model` | string / null | Nein | Model identifier the runner should use (e.g. 'claude-sonnet-4-6'). |
| `tools` | array | Nein | Tool names the runner should expose to this agent. |
| `active` | boolean | Nein | false to retire without deleting (scheduler skips inactive agents). |

## Eingabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "account_id": {
      "type": "string"
    },
    "id": {
      "type": "string",
      "description": "Agent prefix id (agnt_…). Omit to create."
    },
    "name": {
      "type": "string",
      "description": "Required on create. ≤ 120 chars."
    },
    "system_prompt": {
      "type": [
        "string",
        "null"
      ]
    },
    "model": {
      "type": [
        "string",
        "null"
      ],
      "description": "Model identifier the runner should use (e.g. 'claude-sonnet-4-6')."
    },
    "tools": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Tool names the runner should expose to this agent."
    },
    "active": {
      "type": "boolean",
      "description": "false to retire without deleting (scheduler skips inactive agents)."
    }
  },
  "required": [
    "account_id"
  ],
  "type": "object"
}
```

## Ausgabeschema

```json
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "agent": {
      "type": "object",
      "properties": {
        "id": {
          "type": "string"
        },
        "name": {
          "type": "string"
        },
        "system_prompt": {
          "type": [
            "string",
            "null"
          ]
        },
        "model": {
          "type": [
            "string",
            "null"
          ]
        },
        "tools": {
          "type": "array",
          "items": {
            "type": [
              "string",
              "object"
            ]
          }
        },
        "active": {
          "type": "boolean"
        },
        "creator_role": {
          "type": "string"
        },
        "creator": {
          "type": [
            "object",
            "null"
          ]
        },
        "account_id": {
          "type": [
            "string",
            "null"
          ]
        },
        "created_at": {
          "type": "string"
        },
        "updated_at": {
          "type": "string"
        }
      },
      "required": [
        "id",
        "name",
        "active",
        "creator_role",
        "created_at"
      ]
    }
  },
  "required": [
    "agent"
  ],
  "type": "object"
}
```