server-plugins
Framework server plugins and the `/_agent-native/` route namespace. Use when adding a custom server plugin, deciding whether to create an `/api/` route vs an action, or debugging auto-mounted framework routes.
67
82%
Does it follow best practices?
Run evals on this skill
Adds up to 20 points to the overall score
View guide
Passed
No findings from the security scan
Server Plugins & Framework Routes
Default Plugins (auto-mount)
Five default plugins auto-mount when your app doesn't have a custom version in server/plugins/:
| Plugin | Default behavior | Customize when |
|---|---|---|
agent-chat | Agent chat endpoints | Custom mentionProviders or systemPrompt |
auth | Auth middleware | Custom publicPaths or Google OAuth config |
core-routes | /_agent-native/poll, /_agent-native/ping, etc | Custom envKeys or sseRoute |
resources | Resource CRUD | Rarely |
terminal | Terminal emulator | Rarely |
Only create plugin files for plugins you need to customize. Let defaults auto-mount.
Framework Route Namespace: /_agent-native/
All framework-level routes live under /_agent-native/ to avoid collisions with template-specific /api/* routes.
Hard rule
- ALL framework routes go under
/_agent-native/. - Templates own
/api/*only for route-only domain concerns such as uploads, streaming, webhooks, OAuth callbacks, or non-JSON protocols. - Never put framework routes under
/api/. - Never put template routes under
/_agent-native/— that namespace is reserved. - Never create
/api/*routes that only wrap, proxy, or re-export actions. Use the existing/_agent-native/actions/:nameendpoint or the React action hooks.
Auto-mounted framework routes
| Route | Purpose |
|---|---|
GET /_agent-native/poll | Polling endpoint for DB change detection |
GET /_agent-native/events | SSE endpoint for real-time sync |
GET /_agent-native/ping | Health check |
GET/PUT/DELETE /_agent-native/application-state/:key | Application state CRUD |
GET/PUT/DELETE /_agent-native/application-state/compose/:id | Compose draft CRUD |
POST /_agent-native/agent-chat | Agent chat SSE endpoint |
GET /_agent-native/agent-chat/mentions | Mention search for @-tagging |
GET /_agent-native/env-status | Env key configuration status |
POST /_agent-native/env-vars | Save env vars |
/_agent-native/auth/* | Authentication (login, session, logout) |
/_agent-native/google/* | Google OAuth (callback, auth-url, etc.) |
/_agent-native/resources/* | Resource CRUD |
/_agent-native/actions/:name | Auto-mounted action endpoints |
/_agent-native/available-clis | Available CLI tools |
/_agent-native/agent-terminal-info | Terminal connection info |
/_agent-native/collab/* | Real-time collaboration (see real-time-collab) |
/_agent-native/a2a | A2A JSON-RPC endpoint (see a2a-protocol) |
Actions-First Approach
For standard CRUD and data operations, use defineAction in actions/ — the framework auto-mounts them as HTTP endpoints at /_agent-native/actions/:name. Only create custom /api/* routes for things actions can't do:
- File uploads with multipart form data
- Streaming responses
- Webhooks from external services
- OAuth callbacks
Before adding a route, inspect the existing action files. Reuse the action if it already encodes the business rule, or add a new action if the operation should be available to both the agent and the UI. A route whose implementation mostly calls an action is usually the wrong abstraction.
The Nitro Vite plugin handles both /api/ and /_agent-native/ prefixes via file-based routing in server/routes/.
Related Skills
actions— Prefer actions over custom/api/routesauthentication— Auth middleware and session handlingportability— Use H3 (not Express) for all routes
- Repository
- BuilderIO/agent-native
- Commit
e9a2f0e
- Last updated
- First committed
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.