Built-in Agents

Built-in Agents

Agent Architecture

Agents follow a modular architecture with a base class and registry pattern:

┌──────────────────┐     ┌──────────────────┐     ┌──────────────────┐
│   User Request   │     │  Agent Registry  │     │  Provider        │
│   (API Stream)   │────▶│  getAgent(id)    │────▶│  createModel()   │
└──────────────────┘     └──────────────────┘     └──────────────────┘
                                  │                        │
                                  ▼                        ▼
                         ┌──────────────────┐     ┌──────────────────┐
                         │  BaseAgent       │     │  LangChain Model │
                         │  - buildMessages │────▶│  - stream()      │
                         │  - stream()      │     │  - invoke()      │
                         └──────────────────┘     └──────────────────┘
                                  │
                                  ▼
                         ┌──────────────────┐
                         │  SSE Response    │
                         │  (text/events)   │
                         └──────────────────┘

Agent Registry

AI providers and agents are configured in config/ai.ts. Define your LLM providers (OpenAI, Anthropic, Google), available models, and agent definitions. Each agent specifies which models it can use and its system prompt. Credits are charged uniformly across agents — 1 credit per LLM token (input + output), deducted post-stream against provider-reported usage. There is no per-agent credit cost field.

Base Agent Class

All agents extend the BaseAgent class which provides common functionality: message building, streaming, token counting, and credit deduction. Each agent implements its own metadata (ID, name, description, allowed models) and getSystemPrompt() method. The base class handles the LangChain model instantiation, SSE streaming, and error handling automatically.

Creating a Custom Agent

To create a new agent, create a folder under lib/ai/agents/ with an index.ts file. Extend the BaseAgent class and implement the metadata property (agent ID, name, description, allowed models) and the getSystemPrompt() method. Then register your agent in the agent registry at lib/ai/agents/index.ts. Your new agent will automatically appear in the agent selector dropdown in the chat interface.

AI Streaming Endpoint

The streaming endpoint at /api/ai/stream handles authentication (verifies the user session), rate limiting (using the AI-specific rate limiter), credit checking (ensures the account has enough credits), and then streams the response using Server-Sent Events (SSE). After the response completes, it logs the token usage to ai_requests, saves the message to chat_messages, and deducts credits from the account.

Using the AI Stream (Client)

The client-side chat interface sends messages to the streaming endpoint and processes the SSE response in real time. The chat component manages conversation state, displays streaming text with a typing indicator, handles errors gracefully, and persists the chat history through the session API. The agent and model selectors allow users to switch between different AI agents and models within the interface.

Adding a New Agent

1. Create a new folder: lib/ai/agents/my-agent/index.ts
2. Extend BaseAgent and implement metadata and getSystemPrompt()
3. Register in lib/ai/agents/index.ts
4. Add the agent to the AGENTS array in components/private/chat-interface.tsx (icon, colors)
5. Add translations in all locale message files under i18n/messages/ under chat.agents