Contact sales Log in Download Start free trial
Start free trial
/docs / agents

Employee Packages

An employee package describes a role a company can hire: what the employee is responsible for, how it works, which kinds of systems it needs, and what it does on its own. You write it as a folder with an AGENT.md and, when the role needs more than chat, an agent.json.

The package

support-coordinator/
├── AGENT.md        # required: who the employee is and how it works
├── agent.json      # optional: capabilities, inputs, workflows, memory
└── skills/         # optional: skills only this employee uses
    └── reply-drafting/
        └── SKILL.md
FileRequiredPurpose
AGENT.mdyesThe persona: who the employee is, how it works, and its rules. See Persona and Memory.
agent.jsonnoCapabilities it requires, questions for the owner, workflows, memory settings and approval ceilings. See agent.json Reference.
skills/noSkills in the standard SKILL.md format. Only this employee sees them.
manifest.jsonapps onlyIdentity with "type": "app". The marketplace writes its own manifest when it packages an employee.
ui/apps onlyThe app’s page. See Apps.

Write a package

Start with the persona. Frontmatter names the employee and gives a one-line description; the body is instructions in plain prose.

---
name: Support Coordinator
description: Answers every customer message the day it arrives and escalates what it cannot settle.
---

# Support Coordinator

You answer customer email for the company. Reply within the configured window,
in the company's voice, and keep every thread moving until the customer has an answer.

## How you work
- Read the whole thread before you reply.
- Use the reply-drafting skill for every customer reply.
- When a message is about money, draft a proposal for the owner instead of promising anything.

## Rules
- Never promise a refund, a discount or a date you cannot confirm.

Add agent.json when the role needs a system, a setting from the owner, or work it does without being asked. This one requires the mail capability, asks one question at hire, and answers each new message as it arrives.

{
  "requires": { "interfaces": ["mail"] },
  "inputs": [
    {
      "key": "reply_window_hours",
      "label": "Reply within (hours)",
      "type": "number",
      "id": "support.reply_window_hours",
      "scope": "company",
      "default": 24
    }
  ],
  "workflows": {
    "new-mail": {
      "trigger": { "type": "watch", "plugin": "mail", "event": "email.new" },
      "description": "Handle each customer message as it arrives.",
      "activities": [
        {
          "id": "reply",
          "intent": "Read the message in _watch_payload, draft a reply within reply_window_hours, and escalate anything about money to the owner."
        }
      ]
    }
  }
}

The watch names the capability mail, not a product. At run time it resolves to the plugin the owner connected for mail. See Workflows for triggers and activities.

Load it on a bot

Put the folder in <data>/user/agents/<name>/. Nebo watches AGENT.md, agent.json and manifest.json and reloads the employee about a second after a change. Removing the folder deactivates the employee but keeps its record.

Nebo loads employees from three sources, and later sources win: employees built into Nebo, sealed marketplace packages in <data>/nebo/agents/, and folders in <data>/user/agents/. An employee can also create or change a package for you with its create_employee and update_employee tools, which write the same folder.

What happens at hire

When an owner hires your employee from the marketplace or with an AGNT- code, Nebo:

  1. Reads the package's needs without asking a model: every capability in requires.interfaces, every plugin in requires.plugins, and every capability or plugin a watch trigger names.
  2. Shows the owner one consent sentence for those needs and, on hire, grants them to this employee as standing permissions. Operations that need approval stay that way. See Capabilities and Approvals.
  3. Installs dependencies: plugins in requires.plugins, marketplace skills named in skills and in activities, and the dependencies declared when the package was published.
  4. Asks the owner the inputs questions, and tells the owner through the Inbox about any capability with no connection yet.

A workflow whose capability has no connection is kept and marked degraded, with the reason. It starts working as soon as the owner connects a system.

What Nebo checks

Nebo reads agent.json leniently. Unknown keys are ignored. A workflow that does not match the schema is skipped, and the owner gets an Inbox notice that it will not run; the rest of the employee still loads. These problems reject the whole file:

  • An event trigger with an empty sources list.
  • Two activities with the same id in one workflow.
  • An input with a scope other than company or seat, or a money question with a default.
  • A ceiling value other than "approval".
  • A phone call tree without exactly one greeting and at least one named intent.

Some checks run when a workflow starts rather than when it loads, such as the parameters each activity type requires. See Activities.

Write responsibilities, not tools. An employee package names capabilities, such as ledger or mail, and never a specific product, company, or industry. The owner decides which system fills each capability, so one package serves every company that hires it.

Next