AI Agent Chat Interface
Relevant source files
The following files were used as context for generating this wiki page:
The AI Agent Chat Interface is a core feature of the ATMOS platform, providing a real-time, interactive bridge between users and AI agents. It enables developers to communicate with agents through a dedicated chat panel, facilitating tasks such as code generation, project research, and automated workflow execution. The system is built on a distributed architecture that spans a React-based frontend and a high-performance Rust backend.
This module leverages WebSocket-based communication to ensure low-latency message exchange and state synchronization. It manages persistent agent sessions, message history, and execution states, allowing for complex multi-turn dialogues. By integrating with the broader Backend: Business Logic, the chat interface serves as the primary touchpoint for the "Agent Integration" layer of the project.
Sources: AGENTS.md:12, apps/web/src/components/agent/AgentChatPanel.tsx
System Architecture
The AI Agent Chat Interface operates as a full-stack system involving the frontend user interface, a specialized React hook for state management, and a backend service that handles session persistence and agent logic.
Component Overview
The interface is structured into three primary layers:
- UI Layer (
AgentChatPanel.tsx): A React component providing the visual representation of messages, input fields, and session controls. - State & Hook Layer (
use-agent-session.ts): Manages local session state, handles WebSocket message sending/receiving, and maintains the message history. - Service Layer (
agent_session.rs): A Rust-based service that manages agent instances, message storage in the database, and interaction with the core AI engine.
The following diagram illustrates the high-level data flow and relationship between these layers:
Frontend Implementation
Agent Chat Panel
The AgentChatPanel is the primary entry point for users. It utilizes components from the @workspace/ui library to render a scrollable message list and an input area. Key features include session switching, auto-scrolling to the latest message, and status indicators (e.g., "thinking" or "typing").
| Component/Feature | Description |
|---|---|
| Message List | Renders an array of message objects with role-based styling (user vs. assistant). |
| Chat Input | A text area supporting multi-line input and submission via keyboard shortcuts. |
| Session Selector | Allows users to toggle between multiple active agent sessions. |
| Status Bar | Displays the current connection state and agent activity status. |
Sources: apps/web/src/components/agent/AgentChatPanel.tsx
Session Management Hook
The useAgentSession hook encapsulates the complex logic required for real-time interaction. It interacts with the WebSocket API to perform actions such as creating sessions, sending messages, and fetching historical data.
Backend Service and Communication
Agent Session Service
The backend AgentSessionService is responsible for the lifecycle of an AI agent interaction. It manages the AgentSession struct, which typically includes unique identifiers, timestamps, and metadata regarding the agent's configuration.
Key responsibilities include:
- Session Initialization: Setting up the environment for the agent.
- Message Persistence: Ensuring all chat history is saved for future context.
- Context Management: Providing the agent with relevant project or workspace data to improve response accuracy.
Sources: crates/core-service/src/service/agent_session.rs
WebSocket Protocol
Communication is standardized via WsAction and WsResponse enums. The Agent related actions are specifically defined to handle the unique needs of chat-based interaction.
| Action Type | Description |
|---|---|
AgentCreateSession | Requests the creation of a new persistent chat session. |
AgentSendMessage | Transmits a user prompt to the backend agent service. |
AgentListSessions | Retrieves a list of historical or active sessions for the current context. |
AgentGetHistory | Loads the message history for a specific session ID. |
Sources: crates/infra/src/websocket/message.rs
Data Models
Message Structure
Messages are exchanged using a structured format that identifies the sender's role and the content of the message.
// Representative structure based on crate logic
pub struct AgentMessage {
pub id: String,
pub session_id: String,
pub role: MessageRole, // User, Assistant, System
pub content: String,
pub created_at: DateTime<Utc>,
}
Sources: crates/core-service/src/service/agent_session.rs, crates/infra/src/websocket/message.rs
Summary
The AI Agent Chat Interface provides a robust, real-time communication channel between the user and AI agents. By utilizing a React frontend for the UI, a specialized hook for managing WebSocket-based state, and a Rust backend for high-performance session management, the system ensures that agent interactions are persistent, low-latency, and context-aware. This architecture allows the agent to function as a seamless part of the development workflow within the ATMOS ecosystem.