skills/ai-agents-development/references/manifest-schema.md

# AI Manifest Schema — Field Reference

Complete field-by-field reference for `ai.agents` and `ai.knowledge_bases`, with the exact validation rules the CLI enforces. Use this when generating or repairing an `ai:` manifest block by hand.

All AI artifacts live under one top-level key:

```yaml
ai:
    agents: []            # omitted when empty
    knowledge_bases: []   # omitted when empty
```

The entire `ai:` block is omitted from the manifest when both lists are empty. There is **no `manifest_version` gate** — the CLI forces `manifest_version: "2023-05-09"` on every save regardless of what artifacts are present. Any other version string you write is silently overwritten.

## Agent fields

| Field | YAML key | Type | Required | CLI-settable | Notes |
|-------|----------|------|----------|--------------|-------|
| ID | `id` | string | auto | no | 32 hex chars, no dashes. Generated on create; regenerated by `update_ids`. Leave blank in hand-written entries — filled on next save. |
| Name | `name` | string | **yes** | `--name` | 5–100 chars, alphanumeric + `space ' [ ] ( ) . _ -`, starts alphanumeric. Unique among agents. |
| Description | `description` | string | no | `--description` | 3–500 chars when present. Omitted from YAML when empty. |
| Path | `path` | string | auto | no | Sanitized name; the on-disk directory under `agents/`. |
| Model | `model` | string | no | **no** | Written `""` on create. No client-side valid-value list, so a pinned ID validates locally and fails server-side. Leave empty for the platform default; write a user-supplied ID verbatim; never invent one. |
| Tools | `tools` | list of string | no | **no** | Dotted references; see below. Omitted when empty. |
| System prompt | `system_prompt` | string | **yes** | `--system-prompt` | Always the literal `system_prompt.txt`; the flag value supplies the file's *content* (path/URL read, else inline text). |
| Input format | `input_format` | string | **yes** | `--input-format` | `text` or `json`. Defaults to `text`. |
| Input schema | `input_schema` | string | conditional | `--input-schema` | Required when `input_format: json`. Must be `input_schema.json`, a file in the agent dir; the deploy backend reads only that name. CLIs newer than 2.1.1 reject any other value, or an inline schema, on every manifest load; 2.1.1 and earlier accept it and the deploy fails. |
| Output format | `output_format` | string | **yes** | `--output-format` | `text`, `json`, `json_with_schema`, `markdown`, `html`. Defaults to `text`. |
| Output schema | `output_schema` | string | conditional | `--output-schema` | Required **only** when `output_format: json_with_schema` (not for plain `json`). Must be `output_schema.json`, a file in the agent dir; the deploy backend reads only that name. CLIs newer than 2.1.1 reject any other value, or an inline schema, on every manifest load; 2.1.1 and earlier accept it and the deploy fails with `output schema is required when using JSON format`. |
| Knowledge bases | `knowledge_bases` | list of string | no | `--knowledge-bases` | KB **names** (not ids/paths). Each must exist in `ai.knowledge_bases`. |
| Exposure | `exposure` | object | no | `--expose-*` (3 flags) | Omitted entirely when nothing is exposed. See below. |

### Exact agent validation errors

- `agent name is required`
- `agent name "X" ...` — standard name rule (length, leading/trailing space, allowed chars)
- `agent "X" description must ...` — standard description rule
- `agent "X" system_prompt is required`
- `agent "X" system_prompt file references the file path "..." which does not exist`
- `agent "X" input_format is required`
- `agent "X" input_format "Y" is not valid; must be one of: text, json`
- `agent "X" output_format is required`
- `agent "X" output_format "Y" is not valid; must be one of: text, json, json_with_schema, markdown, html`
- `agent "X" input_schema is required when input_format is json`
- `agent "X" output_schema is required when output_format is json_with_schema`
- `agent "X" input_schema is required when exposure.agent_as_tool is true`
- `agent "X" input_schema file "f" ... does not exist` (and the output equivalent)
- `agent "X" input_schema must be "input_schema.json": rename agents/<path>/<file> to input_schema.json and set input_schema: input_schema.json in manifest.yml` (and the output equivalent; CLIs newer than 2.1.1)
- `agent "X" input_schema must be "input_schema.json": move the inline schema into agents/<path>/input_schema.json and set input_schema: input_schema.json in manifest.yml` (and the output equivalent; CLIs newer than 2.1.1)
- `duplicate agent name "X"`
- `agent "X" references knowledge base "K" which is not defined in the manifest`

### exposure object

```yaml
exposure:
    workflows:
        system_action: true   # agent as an app-scoped Fusion action
    charlotte_chat: true       # agent reachable from Charlotte chat
    agent_as_tool: false       # agent invocable as a tool by other agents
```

| Key | Flag on `agents create` |
|-----|-------------------------|
| `charlotte_chat` | `--expose-charlotte-chat` |
| `agent_as_tool` | `--expose-agent-as-tool` (requires `--input-schema`) |
| `workflows.system_action` | `--expose-workflow-system-action` |

The field is a pointer with `omitempty`, so the whole block is **absent** from the manifest unless at least one switch is on — an agent created with no `--expose-*` flag has no `exposure` key. Absent is equivalent to all three `false`.

`agent_as_tool: true` is the only switch with a validation rule: the agent must also declare `input_schema`, checked both at create time (`--input-schema is required when --expose-agent-as-tool is set`) and on every manifest load. The other two are unvalidated client-side, so a misspelled key surfaces only at deploy.

## Knowledge base fields

| Field | YAML key | Type | Required | CLI-settable | Notes |
|-------|----------|------|----------|--------------|-------|
| ID | `id` | string | auto | no | 32 hex chars. Auto-filled on save. |
| Name | `name` | string | **yes** | `--name` | Manifest floor is **1** char (max 100); `kb create` enforces 5–100. Unique among KBs. |
| Description | `description` | string | no | `--description` | Not validated at the manifest level; `kb create` still enforces 3–500. Always emitted (may be empty). |
| Encrypt | `encrypt` | bool | no | `--encrypt` | Passthrough hint; CLI does nothing with it. Defaults `false`. |
| Path | `path` | string | auto | no | Sanitized name; directory under `knowledge-bases/`. |
| Files | `files` | list of string | **yes** | `--files` | ≥1 bare filename. Each must exist at `knowledge-bases/<path>/<file>`. |

Unlike the agent struct, **no KB field carries `omitempty`** — all six keys are always written.

The KB name and description validators are deliberately looser than the agent ones: the AI platform imposes no length restriction on a KB name, so the manifest validator does not invent one. The create command's flag validators were left at the shared 5/3-character floors, which is why `kb create --name "kb"` still fails while a manifest already containing that name validates cleanly.

### Exact KB validation errors

- `knowledge base name is required`
- `knowledge base name "X" ...` — name regex / max length
- `knowledge base "X" must have at least one file`
- `knowledge base "X" file "f" must be a filename only, not a path`
- `knowledge base "X" file "f" references the file path "..." which does not exist`
- `duplicate knowledge base name "X"`

There is no manifest-level KB description error — that check was removed.

### Delete-time errors

`agents delete` and `knowledge-bases delete` take `-n/--name` plus the standard `--no-prompt`.

- `flag --name is required when --no-prompt flag is used`
- `agent "X" not found` / `knowledge base "X" not found`
- `no agents to delete` / `no knowledge bases to delete` — the app has none
- `cannot delete knowledge base "X": still referenced by agent(s): A, B`
- `agent "X" was removed from the manifest but its directory <path> could not be deleted, remove it manually` — the manifest save happens first, so this leaves an orphaned directory rather than a dangling manifest entry

## Shared validators

| Name | Value |
|------|-------|
| Name length | min 5, max 100 (KB manifest floor: 1) |
| Description length | min 3, max 500 (not enforced on the KB manifest) |
| Name regex | starts alphanumeric; allows `alnum`, space, and `' [ ] ( ) . _ -` |
| Description regex | starts alphanumeric; allows `alnum`, whitespace, and `: ' [ ] ( ) , . / _ -` |
| ID | when present: 32 characters, parseable as a UUID (no dashes) |

Create-time flag failures report as `invalid value for --name: input must be at least 5 characters long`.

## Full worked example

```yaml
ai:
    agents:
        - id: cfa84addde80471fb2ffcb67460ca688
          name: Detection Triage Agent
          description: Triages detections against the runbooks
          path: Detection_Triage_Agent
          model: ""
          tools:
            - collections.triage_notes.CreateObject
            - collections.triage_notes.SearchObjects
            - collections.generic.ListObjects
            - api_integrations.VirusTotal.Get_a_file_report
          system_prompt: system_prompt.txt
          input_format: text
          output_format: json_with_schema
          output_schema: output_schema.json
          knowledge_bases:
            - Threat Intel Docs
          exposure:
            workflows:
                system_action: true
            charlotte_chat: true
            agent_as_tool: false
    knowledge_bases:
        - id: 328ff55985c24616ad895336b855c90d
          name: Threat Intel Docs
          description: Runbooks and IOC references
          encrypt: false
          path: Threat_Intel_Docs
          files:
            - runbook.md
            - iocs.csv
```

Required on disk for this to validate:

```
agents/Detection_Triage_Agent/system_prompt.txt
agents/Detection_Triage_Agent/output_schema.json
knowledge-bases/Threat_Intel_Docs/runbook.md
knowledge-bases/Threat_Intel_Docs/iocs.csv
```

And the referenced tools must be exposed on their own side: `collections.triage_notes` created with `--agent-tools-expose`, and the VirusTotal spec operation carrying `x-cs-operation-config.agent_tools.expose_to_agent: true`. `collections.generic.*` needs no exposure — it is the agent's runtime scratch collection.