agent.json Reference — Nebo Developer Documentation

agent.json holds everything about an employee that is not prose: the capabilities it requires, the questions it asks the owner, how its memory is kept, which operations always need approval, and the workflows it runs. Every field is optional.

Example

{
  "requires": {
    "interfaces": ["ledger", "mail"],
    "plugins": [],
    "tools": []
  },
  "skills": ["@example/skills/receipt-capture"],
  "inputs": [
    {
      "key": "invoice_mailbox",
      "label": "Mailbox that receives vendor invoices",
      "type": "text",
      "id": "finance.ap.invoice_mailbox",
      "scope": "company",
      "required": true,
      "missing": "Ask the owner which mailbox to watch before processing invoices."
    }
  ],
  "memory": {
    "mode": "separate",
    "topics": [
      { "slug": "vendor", "description": "A supplier: terms, usual amounts, contacts, open disputes" }
    ]
  },
  "subscribes": ["finance.ap.*"],
  "ceiling": { "ledger.bill.create": "approval" },
  "workflows": {
    "invoice-intake": {
      "trigger": { "type": "watch", "plugin": "mail", "event": "email.new" },
      "activities": [
        { "id": "record", "intent": "If the message in _watch_payload is a vendor invoice, record it as a bill." }
      ]
    }
  }
}

Fields

Field	Type	Meaning
`requires.interfaces`	list of strings	Capabilities the role needs, such as `mail` or `ledger`. Granted at hire; each approval-gated operation stays an approval item. See Capabilities and Approvals.
`requires.plugins`	list of strings	Plugins installed with the employee. Use only when the role truly depends on one plugin; prefer a capability.
`requires.tools`	list of strings	Tools loaded into the employee’s session from its first turn. This never bypasses approval.
`skills`	list of strings	Marketplace skills to install and use: `@org/skills/name`, optionally `@version`, or a `SKIL-` code. Skills in the package’s own `skills/` folder need no entry.
`inputs`	list	Questions the owner answers at hire. See Inputs.
`memory`	object	How conversations and memory are kept. See Persona and Memory.
`subscribes`	list of strings	Company fact areas the employee re-reads when they change, such as `finance.ar.*`.
`ceiling`	map	Operation to `"approval"`. That operation always asks the owner for this employee. No other value is accepted.
`workflows`	map	Workflow name to workflow. See Workflows.
`tools`	list	HTTP tools served by an app’s sidecar. See Sidecar tools.
`scopes`	map	Named groups of `tools`, `skills` and `plugins`. A scope’s `plugins` are described to the employee when that scope is active.

Inputs

An input is a question the owner answers when hiring. Answers appear to the employee under "Configured Inputs" and fill {{key}} placeholders in watch and folder triggers.

{
  "key": "close_day",
  "label": "Business day to finish the close",
  "type": "select",
  "options": [
    { "value": "3", "label": "Third business day" },
    { "value": "5", "label": "Fifth business day" }
  ],
  "default": "5",
  "scope": "company",
  "id": "finance.close.day"
}

Field	Default	Meaning
`key`	required	Name used in placeholders. `name` is accepted as a fallback.
`label`	from `key`	The question shown to the owner.
`type`	`text`	`text`, `textarea`, `number`, `select`, `checkbox` or `radio`.
`required`	`false`	Marks the question as one the owner must answer.
`default`	none	Pre-filled answer. Not allowed on a money question.
`placeholder`, `description`	none	Help text.
`options`	none	For `select` and `radio`: `{value, label}` objects or plain strings.
`id`	none	A stable, dotted name for the fact, such as `finance.ap.invoice_mailbox`, so other employees can share it.
`scope`	`company`	`company`: a shared company fact. `seat`: this hire only.
`missing`	none	What the employee does while the question is unanswered.
`money`	`false`	Marks a money amount. A money question cannot have a default.

Sidecar tools

An app with a sidecar exposes HTTP endpoints to its employee as tools. Nebo registers each entry as app__<app>__<name> and sends calls to the sidecar at method and path. See App Sidecar.

"tools": [
  {
    "name": "list_entries",
    "description": "List journal entries for a date range.",
    "method": "GET",
    "path": "/entries",
    "input_schema": { "type": "object", "properties": { "from": { "type": "string" } } }
  }
]

Workflows

Each key under workflows names one workflow; the name is its identifier. The full format is on Workflows, Triggers and Activities.