Nocobase App Plugin Agents Agent Skill

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 agentsToken from @nocobase/app-plugin-agents/server/tokens when 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 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 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 |

| Contribute subjects, scopes, actions, agent defaults, the App's own agents, CLI commands, people, reports, mounts | Extension points |

| Agents discovered from runners, the model catalog, enabling agents, availability, the App's own agents | Agents |

| Configure OnlineAgentService/OnlineAgentConfigurator, register SDK tools, use realtime/background sessions | OnlineAgent chats and business tools |

| 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 |

| Model services and the model gateway | Model services |

| Register runners, how claims and heartbeats work, local policy, protocol and upgrade_required | Runners |

| Build the CLI and runner tarballs, serve them, CI artifacts, install script, download tokens, updates, the npm runner | Distribution |

| Variables and secrets, the skill library, chat attachments, usage, prices and reports | Variables, skills, attachments and usage |

| Check that everything works, and diagnose failures | Verification and troubleshooting |