Knowledge Agent Template

The Knowledge Agent Template is composed of two primary architectural components designed to build AI agents with up-to-date knowledge access:

1. Main App (apps/app): A unified Nuxt application. It serves as the central hub providing the chat interface, API endpoints, bot integrations (e.g., Discord, GitHub), sandbox management, and content synchronization services.
2. SDK (packages/sdk): A client library designed for integration into external AI applications. It provides tools that are compatible with the AI SDK, specifically bash and bash_batch tools, allowing an agent to execute commands in a managed sandbox.

The Knowledge Agent Template uses a file-based search approach instead of traditional embeddings or vector databases.

The Workflow

1. Aggregation: Documentation from all sources is aggregated into a single snapshot repository.
2. Execution Environment: When a user asks a question, a Vercel Sandbox is created from that snapshot.
3. Tool Use: The AI agent uses bash and bash_batch tools (via the Vercel AI SDK) to run commands like grep, find, and cat directly within the sandbox.
4. Synthesis: The results of these file operations are synthesized into a natural language answer with citations.

Admin mode operates on a separate AI pipeline from the standard chat mode:

1. Tool Loading: When an admin chat is created, the server loads admin tools instead of the standard documentation sandbox tools.
2. System Prompting: The agent receives a specialized system prompt instructing it to use admin tools for monitoring and analytics.
3. Direct Database Access: Queries run directly against your NuxtHub database without a sandbox environment.
4. Data Tagging: Admin chats are stored in the database with the attribute mode: 'admin'.

The application uses @evlog/nuxthub for structured logging.

• Storage: Every API request, bot interaction, and workflow execution is logged to the evlog_events table in your NuxtHub database.
• Data Included: Logs include HTTP method, path, status code, duration, request ID, and optional structured data.
• Automatic Cleanup: A daily cron job removes logs older than 7 days.
• Integration: The query_logs, log_stats, and query_errors admin tools directly query this data for real-time insights.

You can customize agent behavior in two ways:

1. Via Code: Modify files in packages/agent/src/prompts/:

• router.ts: Controls question complexity classification.
• chat.ts: Defines the chat interface system prompt and admin prompt.
• bot.ts: Defines the system prompt for bots (GitHub, Discord).
• shared.ts: Contains shared utilities for style and complexity hints.

2. Via Admin UI: Navigate to /admin/agent to adjust settings without code changes. You can modify:

• Response style
• Language
• Temperature
• Citation format
• Additional instructions

The agent uses a deterministic, file-system-based approach instead of traditional vector embeddings:

1. Source Storage: Sources (GitHub, YouTube, etc.) are stored in SQLite via NuxtHub.
2. Content Aggregation: Sources are synced to a snapshot repository using Vercel Workflows.
3. Sandbox Execution: When a query is made, the API connects to a Vercel Sandbox containing the cloned snapshot repo.
4. Tool Execution: The @savoir/sdk provides bash and bash_batch tools that execute grep, find, and cat commands directly against the files in the sandbox.
5. Result Delivery: The output of these commands is returned to the LLM, providing instant and explainable search results without the overhead of a vector database.

Authentication is managed via Better Auth.

• Sign-in methods: Email/password and GitHub OAuth.
• API Key Authentication: Supported via Authorization: Bearer <key> or x-api-key headers.
• Roles: The first registered user is automatically granted the Admin role. Additional admins can be promoted via the admin panel.

The Discord bot uses the Vercel Chat SDK with the @chat-adapter/discord adapter to provide knowledge base answers.

Mentions

Trigger the bot by mentioning it in any channel:

@your-bot How do I configure authentication?

Thread Continuation

Once the bot has replied within a thread, it will automatically respond to follow-up messages in that same thread without requiring a new mention. Note that the bot only continues threads where it has already participated; it will not respond to messages in threads it has not been part of.

Role-Based Triggering

If you provide NUXT_DISCORD_MENTION_ROLE_IDS in your environment variables, the bot will also respond when those specific roles are mentioned (e.g., mentioning an @ask-docs role).

The template uses a complexity-based router to optimize performance and cost. When a question is received, routeQuestion() uses a lightweight model (google/gemini-2.5-flash-lite) to classify the request.

Routing Logic:

• trivial/simple: Uses flash models with low maxSteps (4 or 8).
• moderate: Uses sonnet models with moderate maxSteps (15).
• complex: Uses opus models with high maxSteps (25).

Administrators can override this behavior via the agent_config settings, specifically using defaultModel and maxStepsMultiplier.

API keys allow external services to authenticate without a browser session by creating a virtual session tied to the key owner via the Better Auth API key plugin.

You can include the key in your HTTP requests using either the Authorization header or the x-api-key header. Both methods are functionally equivalent.

# Authorization header
curl -H "Authorization: Bearer sk_live_..." <your-url>/api/chat

# x-api-key header
curl -H "x-api-key: sk_live_..." <your-url>/api/chat

The project utilizes Nuxt auto-imports, meaning you do not need explicit import statements for files located in specific directories. The availability of these auto-imports depends on the runtime environment (Client, Server, or Both).

| Directory | Available in |
|-----------|--------------|
| `app/composables/` | Client |
| `app/components/` | Client |
| `server/utils/` | Server |
| `shared/utils/` | Both |
| `shared/types/` | Both (via `#shared/types`) |

The sandbox system uses Vercel Sandbox Snapshots for instant startup. It allows the agent to perform read-only operations on synced content.

Allowed Commands: find, ls, tree, grep, cat, head, tail, wc, sort, uniq, diff, echo, stat, file, du, basename, dirname, realpath, xargs.

Blocked Commands: rm, curl, wget, git, ssh, sudo, command substitution, redirects, and interpreters.