# Adding Custom Server Plugins to Agent-Native's /_agent-native/ Route

> Extend Agent-Native's /_agent-native/ route by creating custom server plugins. This guide shows how to add new HTTP handlers using defineNitroPlugin in your TypeScript files.

- Repository: [Builder.io/agent-native](https://github.com/BuilderIO/agent-native)
- Tags: how-to-guide
- Published: 2026-06-27

---

**Create a TypeScript file in `server/plugins/` that exports a default `defineNitroPlugin` function to register new HTTP handlers under the `/_agent-native/` prefix.**

Agent-Native (BuilderIO/agent-native) runs on Nitro, the server engine behind Nuxt 3. The `/_agent-native/` API surface is constructed from Nitro plugins located in the `server/plugins/` directory, which auto-load at server startup. Adding custom server plugins allows you to extend this API while reusing core utilities like authentication guards and database clients.

## Where Core Endpoints Are Defined

The built-in `/_agent-native/` routes are established by the core agent-chat plugin and imported by application templates.

### Core Plugin Implementation

In [`packages/core/src/server/agent-chat-plugin.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/agent-chat-plugin.ts), the primary Nitro plugin registers handlers for routes including `/agent-chat` and `/env-status`. This file exports a default plugin using `defineNitroPlugin` that configures the router with the foundational API endpoints consumed by the Agent-Native UI.

### Template-Level Integration

Application templates import this core functionality through files like [`templates/clips/server/plugins/agent-chat.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/clips/server/plugins/agent-chat.ts). This re-exports the core plugin, making the `/_agent-native/` endpoints available to specific template instances such as video or slide decks. The plugin loader also scans additional files in `server/plugins/` automatically, as illustrated by [`templates/clips/server/plugins/_dev-upload-stub.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/clips/server/plugins/_dev-upload-stub.ts).

## Creating a Custom Server Plugin

Nitro automatically discovers and executes any TypeScript file in `server/plugins/` that exports a default plugin definition.

### File Structure and Boilerplate

Create a new file at [`server/plugins/my-custom-api.ts`](https://github.com/BuilderIO/agent-native/blob/main/server/plugins/my-custom-api.ts). The file must export a default function wrapped in `defineNitroPlugin`, which receives the Nitro instance containing the `h3` router.

```typescript
// server/plugins/my-custom-api.ts
import { defineNitroPlugin } from '@agent-native/core/server'
import { runAuthGuard } from '@agent-native/core/server/middleware/auth'

export default defineNitroPlugin((nitro) => {
  const { router } = nitro

  // Define your custom endpoint
  router.get('/_agent-native/custom/status', async (event) => {
    await runAuthGuard(event) // Enforces authentication
    return { status: 'operational', timestamp: Date.now() }
  })
})

```

### Registering Routes with the Router

The `router` object is the underlying h3 instance used by all Agent-Native endpoints. Use standard methods like `router.get()`, `router.post()`, or `router.use()` to attach handlers. All paths must begin with `/_agent-native/` to remain consistent with the public API surface and ensure compatibility with client-side helpers.

## Securing Custom Endpoints

Protect your routes by importing the shared authentication utilities from the core package.

### Using runAuthGuard

The `runAuthGuard` function, available from `@agent-native/core/server/middleware/auth` (as implemented in [`templates/clips/server/middleware/auth.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/clips/server/middleware/auth.ts)), validates the session and throws a 401 error if the request lacks valid credentials. Apply it at the start of each handler to enforce consistent security with built-in endpoints.

```typescript
import { runAuthGuard } from '@agent-native/core/server/middleware/auth'

router.post('/_agent-native/custom/data', async (event) => {
  await runAuthGuard(event)
  const body = await readBody(event)
  // Process authenticated request
  return { success: true }
})

```

## Accessing Database and Request Utilities

Custom plugins can leverage the same infrastructure as core plugins by importing utilities from `@agent-native/core/server`.

### Database Connections

Use `createDbClient` or access existing database pools initialized by the core plugin. Since custom plugins execute after the core plugin initializes in [`packages/core/src/server/agent-chat-plugin.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/agent-chat-plugin.ts), you can rely on established connections.

### Request Helpers

Helpers like `readBody`, `getQuery`, and `getSession` are exported from the core server package. These provide typed access to request data and session context.

```typescript
import { readBody, getSession } from '@agent-native/core/server'

router.get('/_agent-native/custom/user-profile', async (event) => {
  await runAuthGuard(event)
  const session = await getSession(event)
  return { userId: session.userId }
})

```

## Architecture and Execution Order

Nitro bundles all files from `server/plugins/` into the server output and executes them sequentially during startup.

The execution flows as follows:

1. The core plugin in [`packages/core/src/server/agent-chat-plugin.ts`](https://github.com/BuilderIO/agent-native/blob/main/packages/core/src/server/agent-chat-plugin.ts) initializes first, setting up database pools and authentication context.
2. Template-specific plugins in `templates/*/server/plugins/` load next.
3. Your custom plugins execute last, allowing you to depend on fully initialized core resources.

All plugins share the same router instance, meaning your custom `/_agent-native/` routes mount alongside built-in ones without additional configuration.

## Client-Side Integration

Consume your custom endpoints using the same client libraries provided by Agent-Native.

```typescript
// Client-side component
import { useActionQuery } from '@agent-native/core/client'

const fetchStatus = () => useActionQuery('GET', '/_agent-native/custom/status')

```

The `useActionQuery` helper automatically handles base URL resolution and JSON parsing, treating your custom endpoints identically to native Agent-Native routes.

## Summary

- Agent-Native's `/_agent-native/` API is constructed from Nitro plugins in the `server/plugins/` directory.
- Create custom plugins by exporting a default `defineNitroPlugin` function that registers routes on the `router` object.
- Prefix all custom routes with `/_agent-native/` to maintain API consistency.
- Import `runAuthGuard` from `@agent-native/core/server/middleware/auth` to enforce authentication.
- Reuse core utilities like `readBody` and `getSession` from `@agent-native/core/server` for typed request handling.
- Plugins auto-load at startup with no manual registration required.

## Frequently Asked Questions

### Do custom plugins execute before or after the core agent-chat plugin?

Custom plugins execute after the core plugin. The core [`agent-chat-plugin.ts`](https://github.com/BuilderIO/agent-native/blob/main/agent-chat-plugin.ts) initializes first in `packages/core/src/server/`, establishing database connections and session handling that your custom code can safely depend on.

### Can I use the existing database connection in my custom server plugin?

Yes. Since your plugin runs after the core initialization, you can import `createDbClient` from `@agent-native/core/server` and utilize existing connection pools. The core plugin handles the initial database setup, allowing custom routes to perform queries immediately.

### What authentication mechanism protects custom routes under `/_agent-native/`?

Routes are protected using the `runAuthGuard` function imported from `@agent-native/core/server/middleware/auth`. This utility, defined in [`templates/clips/server/middleware/auth.ts`](https://github.com/BuilderIO/agent-native/blob/main/templates/clips/server/middleware/auth.ts), validates session tokens and throws 401 errors for unauthenticated requests, ensuring consistent security across all API endpoints.

### Does Agent-Native require a server restart to load new plugin files?

Nitro automatically discovers new files in `server/plugins/` during the build process. In development mode, the server may auto-reload, but a manual restart ensures a clean initialization order, particularly when adding dependencies that the core plugin must initialize before your custom code executes.