nocobase-app-plugin-agents · git:20261023.d490379 · 2026-10-23 · sha256 3d90193790d66dc5
nocobase-app-plugin-agents git:20261023.d490379A
Immutable. This exact content never changes and is served at /api/v1/blob/3d90193790d66dc5.
--- 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 team 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 `agentsToken` from `@nocobase/app-plugin-agents/server/tokens` when the App's providers boot. With nothing contributed, agents still work in conversations. - Nobody creates agents: each coding tool and model a runner reports becomes one, pending until someone who manages agents writes what it is good at and enables it. Only enabled agents get work, and only on a runner that is online, has the agent's tool signed in with its model, and whose owner's local policy lets it take the work. The `agentsToken.onlineAgent` service selects native SDK execution or an explicitly chosen Runner Agent through one realtime conversation contract. Native execution runs registered business tools directly through the SDK; Runner chat uses the existing queue and canonical history. The original chat API and shared browser controller use this service, and never silently change executors. Read [OnlineAgent chats and business tools](references/online-agent.md) to configure that service and its `OnlineAgentConfigurator`. - 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 `unsupported` 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. - Local DOCX text extraction omits embedded binary images before budgeting; it does not perform OCR. Image-only documents fail as unreadable. Do not raise text limits to accommodate base64 image data or change Knowledge's default image representation. - File preparation failures expose only controlled reason codes in execution-status notice params, with fixed fallback titles and viewer-localized wording. Keep parser/Provider errors and credentials private; never infer a historical failure reason from current model configuration or turn Stop into a failure. - Local document cache hits still reauthorize and read current bytes; cache keys isolate users, sources and extractor instances. Historical/native/reference inputs count toward execution budgets; declare a verified lower native count through profile `maxNativeFiles` when the Provider requires it. Model changes and approvals rebuild replay copies from originals. Stop waits for file-stream cancellation and Worker termination; retryFinalization does not repeat extraction or tools. - Kimi Files extraction is automatic for Moonshot; OpenAI-compatible services require an exact remote profile. An exact local profile opts out for a Moonshot model. Use the selected service's saved API key and bound endpoint, never a model-name heuristic, environment-key fallback or second service. Native support skips upload; remote results are execution-only. Upload/content have one five-minute deadline, while DELETE has an independent five-second cleanup window awaited by Stop/shutdown. Lost upload IDs and failed DELETE can leave remote objects; log only sanitized diagnostics. Read the README's **Kimi extraction and exact overrides** section. - Native Skills and bash are opt-in server scope capabilities, not a Runner or default global tool set. Read [Native Skills and application CLI](../../docs/native-sandbox.md) before enabling them. Use `context.execution` only inside the current tool invocation, forward `context.signal`, and never retry unknown writes or restore approval-time `/tmp`. - Variables and model service keys are sealed with the App's secrets service: configure `secrets.keys` before storing any, or the API answers `SECRETS_KEY_MISSING` (503). - The plugin registers no pages. The App routes the exported pages and mounts the chat; the App also binds `agentsAccessToken`, or every business action level is `none`. - `subjects.register`'s `context.assemble`, brief sections and mounts run inside the claim's transaction: database reads only, never a network or a model call. Read anything else in the optional `prepare(run)`. - Tarballs are built by `pnpm nocobase cli build` (the App's CLI) and `cli build --runner` (`nocobase-runner`), either as separate CI artifacts mounted into `storage/runners/dist` (or `agents.dist.dir`), or by the App's own `pnpm build` into its build output (universal packages, at the versions it was built with) and served from there. Never commit them. - In examples, name the App's CLI after the App (`acme`), never `nocobase` or `nocobase-runner`. ## References | Task | Read | | --------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | | Register the plugin, its prerequisites and `agents.*` configuration, mount the pages and the chat | [Setup and configuration](references/setup-and-config.md) | | Contribute subjects, scopes, actions, agent defaults, the App's own agents, CLI commands, people, reports, mounts | [Extension points](references/extension-points.md) | | Agents discovered from runners, the model catalog, enabling agents, availability, the App's own agents | [Agents](references/agents.md) | | Configure OnlineAgentService/OnlineAgentConfigurator, register SDK tools, use realtime/background sessions | [OnlineAgent chats and business tools](references/online-agent.md) | | Enable native web search, verify platform admission, isolation, budgets and Registry upgrades | `node_modules/@nocobase/app-plugin-agents/docs/native-web-search.md` | | Open JSON UI context, custom SDK tool cards, generic form adapters and safe browser-draft application | [UI context, tool cards and local form drafts](references/online-agent.md#open-ui-context-custom-tool-cards-and-local-form-drafts) | | Model services, the model gateway, vectors | [Model services](references/model-services.md) | | Register runners, how claims and heartbeats work, local policy, protocol and `upgrade_required` | [Runners](references/runners.md) | | Build the CLI and runner tarballs, serve them, CI artifacts, install script, download tokens, updates, the npm runner | [Distribution](references/distribution.md) | | Variables and secrets, the skill library, chat attachments, usage, prices and reports | [Variables, skills, attachments and usage](references/variables-skills-usage.md) | | Check that everything works, and diagnose failures | [Verification and troubleshooting](references/verification-and-troubleshooting.md) |