- name
- nocobase-app-plugin-agents
- description
- Register the Agents plugin in a NocoBase App and configure it (agents.* in config.yml), contribute subjects, scopes, business actions, agent defaults, the App's own agents, CLI commands and reports through agentsToken, enable the agents discovered from runners, configure OnlineAgentService and OnlineAgentConfigurator for SDK chats, business tools and native web search, set up model services for the App's own model calls, connect runners (registration tokens, protocol, upgrade_required), build and serve the CLI and runner tarballs (pnpm nocobase cli build, --runner), or work out why a run, a runner or a model fails.
- metadata
- short-description: Agents, runners, model services and their distribution
Agents App Plugin
Use this Skill when an App gives people agents to work with: agents that drive a coding tool (native tools and the shared ACP catalog) on a runner someone connects, one for each tool and model the runners report. Use it as well to build the App's CLI and the runner as tarballs the App serves, and to diagnose a run, a runner or a model that does not work. Do not use it for the business data agents act on; that stays with nocobase-app-development and the plugins that own it.
The package README is the full reference: read it at node_modules/@nocobase/app-plugin-agents/README.md (in this repository, packages/plugins/app-plugin-agents/README.md). The references below say what to do and point to its sections rather than repeating them.
Key rules
-
Runner tool selection is server-owned and explicit. New registrations default to Codex and Claude Code; additional catalog tools must be selected. Native adapters take precedence over ACP. Owners manage personal tools, and runner managers may also manage shared tools. Unknown tools and custom launch commands are not supported. See the README’s “Selecting runner tools and ACP agents” for protocol upgrades, detection triggers and default-model behavior.
-
The plugin knows no business of its own. Subjects, scopes, business actions, the instructions and actions every discovered agent gets, CLI commands and report pages are the App's, contributed through
agentsTokenfrom@nocobase/app-plugin-agents/server/tokenswhen the App's providers boot. With nothing contributed, agents still work in conversations. -
Add runner agents from the live available-model list, enabled directly. Recommended models are auto-added; other reports create no agent. Runner agents are enabled or disabled. Only enabled agents take work.
-
Native files follow legacy Provider defaults: OpenAI/Anthropic/Google/OpenAI-compatible forward PDFs and images, Alibaba forwards images and extracts document text locally, and Moonshot forwards images and uploads supported documents to its selected Kimi Files service automatically. Ollama images remain native; PDF and other supported documents use local text extraction by default, not failure-triggered fallback. DeepSeek/Cohere retain local document extraction and do not forward undeclared images; existing exact profiles still override defaults. Read the package README's Native document inputs before configuring exact service/model/Provider/protocol/base URL overrides. Never promote extracted content above the user role, or silently change routes after failure.
-
Unsupported user attachments must not terminate the conversation: replace only the model replay file part with an untrusted filename/MIME/controlled-limitation description, explicitly stating that the contents were not parsed. Apply the same policy to historical follow-up and explicit extractor results; never forward unsupported bytes, guess contents, persist the description as an original message or cache it as extracted text. Keep authorization, inline validation, format-mismatch, budget, cancellation and actual parsing/Provider failures unchanged.