{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://docs.2kw.ai/schemas/agent.v1.json",
  "title": "2kw agent",
  "description": "Agent configuration applied with `2kw agents apply -f <file>`.",
  "type": "object",
  "additionalProperties": false,
  "required": [
    "name"
  ],
  "anyOf": [
    {
      "required": [
        "model"
      ]
    },
    {
      "required": [
        "models"
      ]
    }
  ],
  "properties": {
    "$schema": {
      "type": "string"
    },
    "name": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^[^#@]+$",
      "description": "Unique per organization; apply looks the agent up by this exact name. '#' and '@' are reserved."
    },
    "description": {
      "type": "string",
      "maxLength": 4000
    },
    "model": {
      "type": "string",
      "minLength": 1,
      "maxLength": 255,
      "pattern": "^(?:[^/#]+|[A-Za-z0-9-]+/[^#]+)$",
      "description": "provider/model, or a bare model name for the default provider. '#' is reserved. With `models`, must equal its first entry."
    },
    "models": {
      "type": "array",
      "minItems": 1,
      "maxItems": 10,
      "uniqueItems": true,
      "items": {
        "type": "string",
        "minLength": 1,
        "maxLength": 255,
        "pattern": "^(?:[^/#]+|[A-Za-z0-9-]+/[^#]+)$"
      },
      "description": "Ordered model list (#591): the first entry is the default, the others can be picked per request with <agent>#<model>. 1-10 unique entries."
    },
    "instructions": {
      "type": "string",
      "maxLength": 20000
    },
    "tools": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/tool"
      }
    },
    "hitlPolicy": {
      "$ref": "#/$defs/hitlPolicy"
    },
    "options": {
      "type": "object",
      "description": "Stored with the version; not read by the run engine."
    },
    "skills": {
      "type": "array",
      "maxItems": 20,
      "description": "Skill bindings (#639): each names an org skill and a label or version.",
      "items": {
        "type": "object",
        "additionalProperties": false,
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "type": "string",
            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*(:[a-z0-9]+(-[a-z0-9]+)*)?$",
            "maxLength": 201
          },
          "ref": {
            "type": "string",
            "pattern": "\\S",
            "description": "Label name or version number; default latest."
          }
        }
      }
    }
  },
  "$defs": {
    "annotations": {
      "type": "object",
      "required": [
        "readOnlyHint",
        "destructiveHint"
      ],
      "properties": {
        "readOnlyHint": {
          "type": "boolean"
        },
        "destructiveHint": {
          "type": "boolean"
        },
        "openWorldHint": {
          "type": "boolean"
        }
      }
    },
    "fileSearchTool": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "config"
      ],
      "properties": {
        "type": {
          "const": "file_search"
        },
        "requiresConfirmation": {
          "type": "boolean"
        },
        "config": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "knowledgeBaseIds"
          ],
          "properties": {
            "knowledgeBaseIds": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            }
          }
        }
      }
    },
    "extractionTool": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "config"
      ],
      "properties": {
        "type": {
          "const": "backbone.extraction"
        },
        "requiresConfirmation": {
          "type": "boolean"
        },
        "config": {
          "type": "object",
          "additionalProperties": false,
          "required": [
            "schemaIds"
          ],
          "properties": {
            "schemaIds": {
              "type": "array",
              "items": {
                "type": "string",
                "minLength": 1
              }
            },
            "model": {
              "type": "string",
              "minLength": 1
            }
          }
        }
      }
    },
    "documentConvertTool": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "const": "backbone.document_convert"
        },
        "requiresConfirmation": {
          "type": "boolean"
        },
        "config": {
          "type": "object"
        }
      }
    },
    "todoTool": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "const": "backbone.todo"
        },
        "requiresConfirmation": {
          "type": "boolean"
        }
      }
    },
    "skillTool": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "skills"
      ],
      "properties": {
        "type": {
          "const": "backbone.skill"
        },
        "requiresConfirmation": {
          "type": "boolean"
        },
        "skills": {
          "type": "array",
          "minItems": 1,
          "maxItems": 20,
          "uniqueItems": true,
          "items": {
            "type": "string",
            "pattern": "^[a-z0-9]+(-[a-z0-9]+)*(:[a-z0-9]+(-[a-z0-9]+)*)?(@[A-Za-z0-9._-]+)?$"
          }
        }
      }
    },
    "bashTool": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "const": "backbone.bash"
        },
        "approval": {
          "enum": [
            "sandbox",
            "pause"
          ]
        },
        "outputs": {
          "enum": [
            "immediate",
            "held"
          ]
        },
        "annotations": {
          "$ref": "#/$defs/annotations"
        }
      }
    },
    "functionTool": {
      "type": "object",
      "additionalProperties": false,
      "required": [
        "type",
        "name",
        "endpoint"
      ],
      "properties": {
        "type": {
          "const": "function"
        },
        "name": {
          "type": "string",
          "minLength": 1
        },
        "description": {
          "type": "string"
        },
        "parameters": {
          "type": "object"
        },
        "endpoint": {
          "type": "string",
          "pattern": "^https?://"
        },
        "secret": {
          "type": "string"
        },
        "annotations": {
          "$ref": "#/$defs/annotations"
        }
      }
    },
    "namedTool": {
      "type": "object",
      "required": [
        "name"
      ],
      "properties": {
        "type": {
          "type": "string"
        },
        "name": {
          "type": "string",
          "minLength": 1
        },
        "description": {
          "type": "string"
        },
        "parameters": {
          "type": "object"
        },
        "annotations": {
          "$ref": "#/$defs/annotations"
        }
      }
    },
    "tool": {
      "type": "object",
      "allOf": [
        {
          "if": {
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "const": "file_search"
              }
            }
          },
          "then": {
            "$ref": "#/$defs/fileSearchTool"
          }
        },
        {
          "if": {
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "const": "backbone.extraction"
              }
            }
          },
          "then": {
            "$ref": "#/$defs/extractionTool"
          }
        },
        {
          "if": {
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "const": "backbone.document_convert"
              }
            }
          },
          "then": {
            "$ref": "#/$defs/documentConvertTool"
          }
        },
        {
          "if": {
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "const": "backbone.todo"
              }
            }
          },
          "then": {
            "$ref": "#/$defs/todoTool"
          }
        },
        {
          "if": {
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "const": "backbone.skill"
              }
            }
          },
          "then": {
            "$ref": "#/$defs/skillTool"
          }
        },
        {
          "if": {
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "const": "backbone.bash"
              }
            }
          },
          "then": {
            "$ref": "#/$defs/bashTool"
          }
        },
        {
          "if": {
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "const": "function"
              }
            }
          },
          "then": {
            "$ref": "#/$defs/functionTool"
          }
        },
        {
          "if": {
            "required": [
              "type"
            ],
            "properties": {
              "type": {
                "enum": [
                  "backbone.tool_search",
                  "backbone.skill_read",
                  "backbone.skills_apply",
                  "backbone.deliver",
                  "backbone.view_image",
                  "web_search"
                ]
              }
            }
          },
          "then": {
            "properties": {
              "type": {
                "not": {}
              }
            }
          }
        },
        {
          "if": {
            "properties": {
              "type": {
                "enum": [
                  "file_search",
                  "backbone.extraction",
                  "backbone.document_convert",
                  "backbone.todo",
                  "backbone.skill",
                  "backbone.bash",
                  "function",
                  "backbone.tool_search",
                  "backbone.skill_read",
                  "backbone.skills_apply",
                  "backbone.deliver",
                  "backbone.view_image",
                  "web_search"
                ]
              }
            },
            "required": [
              "type"
            ]
          },
          "else": {
            "$ref": "#/$defs/namedTool"
          }
        }
      ]
    },
    "hitlPolicy": {
      "type": "object",
      "additionalProperties": false,
      "properties": {
        "version": {
          "const": 1
        },
        "default": {
          "type": "string",
          "enum": [
            "allow",
            "approve",
            "block",
            "deny"
          ]
        },
        "classes": {
          "type": "object",
          "additionalProperties": false,
          "properties": {
            "read": {
              "type": "string",
              "enum": [
                "allow",
                "auto",
                "approve",
                "block",
                "deny"
              ]
            },
            "write": {
              "type": "string",
              "enum": [
                "auto",
                "approve",
                "block",
                "deny"
              ]
            },
            "destructive": {
              "type": "string",
              "enum": [
                "block",
                "deny"
              ]
            }
          }
        },
        "tools": {
          "type": "object",
          "propertyNames": {
            "pattern": "\\S"
          },
          "additionalProperties": {
            "type": "string",
            "enum": [
              "read",
              "write",
              "destructive",
              "approve",
              "auto",
              "deny"
            ]
          }
        }
      }
    }
  }
}