NocoBase AI Employee Management#

You are guiding the user to create and manage AI employees (chatbot assistants) in NocoBase.

Key Concepts#

AI Employee#

An AI employee is a chatbot assistant configured with:

• username (PK): Unique identifier, e.g. am-asset-keeper
• nickname: Display name shown to users
• about: System prompt defining role, data scope, and behavior
• skills: Tool bindings (query, count, form fill, workflow call)
• modelSettings: LLM configuration (service, model, temperature)

Page Integration#

AI employees appear on pages in two ways:

1. Floating Avatar ( AIEmployeeShortcutListModel + AIEmployeeShortcutModel): Circular avatar buttons in page top-right corner
2. Action Bar Button ( AIEmployeeButtonModel): AI button in table/form action bars

Workflow#

Phase 1: Create AI Employees#

text

nb_create_ai_employee("my-helper", "助手", "通用助手",
    "nocobase-015-male", "One-line description",
    "Full system prompt with role, data scope, behavior rules...",
    "Welcome message...",
    '[{"name":"dataSource-dataSourceQuery","autoCall":true}]')

Phase 2: Add Page Shortcuts (Floating Avatars)#

text

nb_ai_shortcut("tab_uid", '[
    {"username": "my-helper", "tasks": [
        {"title": "Quick Query", "message": {"user": "帮我查询数据"}, "autoSend": false}
    ]}
]')

Phase 3: Add Block Buttons#

text

nb_ai_button("table_uid", "my-helper", '[
    {"title": "Analyze Data", "message": {"user": "分析当前数据"}, "autoSend": false}
]')

Available Skills (Tool Bindings)#

Tool NameDescriptionautoCalldataModeling-getCollectionNamesDiscover table namestruedataModeling-getCollectionMetadataGet field definitionstruedataSource-dataSourceQueryQuery databasetruedataSource-dataSourceCountingCount recordstruefrontend-formFillerAuto-fill formstrueworkflowCaller-<key>Custom workflow toolfalse

Avatar IDs#

Common avatar IDs: nocobase-001-male through nocobase-060-male, nocobase-001-female through nocobase-060-female.

Model Settings#

Default LLM configuration:

json

{
  "llmService": "gemini",
  "model": "models/gemini-2.5-flash",
  "temperature": 0.7,
  "topP": 1,
  "timeout": 60000,
  "maxRetries": 1,
  "responseFormat": "text"
}

Common adjustments:

• temperature: 0.3 — more deterministic, better for data queries
• temperature: 0.9 — more creative, better for writing/suggestions
• timeout: 120000 — longer timeout for complex multi-step queries
• responseFormat: "markdown" — for formatted output

Page Integration — Complete Example#

Floating Avatar (Shortcut)#

Place AI employee avatars on a page for quick access:

text

nb_ai_shortcut("tab_uid", '[
    {"username": "my-helper", "tasks": [
        {"title": "Quick Query", "message": {"user": "帮我查一下最新数据"}, "autoSend": false},
        {"title": "Generate Report", "message": {"user": "生成本月汇总报表"}, "autoSend": false}
    ]}
]')

Multiple employees on the same page:

text

nb_ai_shortcut("tab_uid", '[
    {"username": "data-analyst", "tasks": [...]},
    {"username": "form-helper", "tasks": [...]}
]')

Block Button#

Add AI action button to a table's action bar:

text

nb_ai_button("table_uid", "my-helper", '[
    {"title": "Analyze Selected", "message": {"user": "分析当前选中的记录"}, "autoSend": false}
]')

Best Practices#

1. Role-focused: Each AI employee covers one business domain
2. Progressive: Start with basic query tools, add workflow tools later
3. Chinese-first: Use {{$nLang}} in system prompts for language awareness
4. Data scope: Explicitly list accessible tables in the system prompt
5. Preset tasks: Add 1-2 quick-start tasks to shortcuts and buttons
6. System prompt structure: Role → Data scope (table names) → Behavior rules → Output format
7. Skill selection: Start with dataSource-dataSourceQuery + dataModeling-getCollectionMetadata for data-oriented employees