Agent & Chat Capabilities

Relevant source files

The following files were used as context for generating this wiki page:

• apps/web/spec/chat.md
• apps/api/src/modules/agent/application/agent.service.ts
• apps/api/test/modules/agent/application/agent.service.test.ts
• apps/api/test/infrastructure/http/agent.router.test.ts
• apps/web/test/features/chat/chat.api.test.ts
• apps/api/test/modules/agent/application/agent.instructions.test.ts
• apps/web/test/redux/slices/chat.test.ts

The Agent & Chat system enables visitors to interact with an AI agent to ask questions about a site owner. The agent generates answers based solely on the owner's profile and bio data, ensuring that responses remain relevant to the specific individual represented by the site handle.

The system is composed of a backend AgentService that manages conversation threads and interfaces with a language model, and a frontend chat interface that handles user input, conversation history, and local persistence. The architecture supports stateful conversations through a thread-based messaging model.

Sources: apps/web/spec/chat.md:9-10, apps/api/src/modules/agent/application/agent.service.ts

Core Architecture and Data Flow

The AgentService coordinates the interaction between user messages, thread persistence, and the AI model. When a visitor starts a chat, the system creates a unique Thread linked to a specific Profile (via a bioId).

Sequence of a Chat Request

The following diagram illustrates the flow of a message from the user interface through the API to the agent model and back.

Interaction Rules

• Thread Initialization: If it is the visitor's first message, a thread is started for the configured site handle. Sources: apps/web/spec/chat.md:19, apps/web/test/features/chat/chat.api.test.ts:50-57
• Message Processing: Long messages are trimmed to 500 characters. Blank messages are ignored and not sent to the API. Sources: apps/web/spec/chat.md:13-14
• Error Handling: If the agent model returns a blank reply, the system throws an AGENT_EMPTY_REPLY error (HTTP 502). If the model fails, no messages are saved to the database to prevent duplicate questions upon retry. Sources: apps/api/src/modules/agent/application/agent.service.ts:89-95, apps/api/test/modules/agent/application/agent.service.test.ts:133-140

Agent Instructions and Prompting

The agent's behavior is governed by specific instructions that incorporate the site owner's profile. The system converts the profile into a data structure and appends it to the system prompt.

Instruction Generation Logic

1. Data Isolation: The system prompt explicitly tells the model that the provided profile is data, not instructions, to prevent prompt injection.
2. Context Injection: The instructions include the owner's name, handle, headline, and about fields.
3. Instruction Structure:
   • System Prompt: Built via buildInstructions(profile).
   • Message History: Includes past user and assistant turns.
   • Current Question: The new user message.

Sources: apps/api/test/modules/agent/application/agent.instructions.test.ts:24-41, apps/api/test/modules/agent/application/agent.service.test.ts:98-112

API Endpoints

The AgentRouter exposes endpoints for managing threads and exchanging messages.

Endpoint	Method	Payload	Description
/threads	POST	{ handle: string }	Creates a new conversation thread for a specific bio handle.
/threads/:threadId/messages	POST	{ message: string }	Sends a message to the agent and receives a reply.

Sources: apps/api/test/infrastructure/http/agent.router.test.ts:36-70

Frontend State and Persistence

The web application manages chat state using Redux and persists history to localStorage.

Persistence Rules

• Storage Limit: Only the 20 newest conversations are kept in the browser. Sources: apps/web/spec/chat.md:16
• Ordering: Conversations are saved with the newest entries first. Sources: apps/web/spec/chat.md:15
• Failure Recovery: If a reply fails, the original message is returned to the input field so the visitor can try again. Sources: apps/web/spec/chat.md:25, apps/web/test/redux/slices/chat.test.ts:42-53

Chat State Machine

Technical Implementation Details

Data Models

The system uses several domain objects to represent the chat structure:

• Thread: Represents a conversation session. Contains id, bioId, and createdAt.
• Message: Represents a single turn in a thread. Contains id, threadId, role (user or assistant), content, and createdAt.

Sources: apps/api/test/modules/agent/application/agent.service.test.ts:8-63

Validation and Security

• Input Sanitization: The system validates that a threadId is a valid UUID before processing. Sources: apps/api/test/infrastructure/http/agent.router.test.ts:79-87
• Handle Validation: Threads can only be created for handles that have an existing bio. Sources: apps/api/test/modules/agent/application/agent.service.test.ts:78-86

The Agent & Chat capabilities provide a robust, stateful interface for interacting with personalized AI. By combining strict data-driven prompting with a thread-based persistence model, Thoth ensures that the chat experience remains focused on the site owner's specific background and information.