A Deep Dive into Project AIRI: An AI Agent System Designed for Long-Term Operation
As AI Agent technology rapidly evolves, numerous projects have emerged, but most remain at the demonstration level. Project AIRI offers a different perspective. It’s not just a wrapper for Large Language Model (LLM) tool-calling APIs; it is dedicated to building a sustainable, continuously evolving runtime system for digital personas. Its design philosophy shifts from “completing single tasks” to “ensuring the long-term, stable, and cross-platform existence of a persona,” showcasing a systems-thinking approach to advancing AI Agents from proof-of-concept to production-grade products.
System Architecture: Designed for Long-Term Operation and Cross-Platform Consistency
Unlike traditional Agent frameworks that focus on task flow orchestration, Project AIRI’s architecture adds three crucial layers to support its positioning as a “digital persona runtime system”:
- Real-time Interaction Layer: Integrates voice I/O and character driving (e.g., Live2D/VRM), pursuing a sense of “presence” rather than one-off responses, emphasizing low latency and collaborative work.
- Multi-Modal Runtime Layer: Ensures the persona has consistent behavior and capabilities across different platforms like web, desktop, and mobile by sharing core functionalities, thus avoiding redundant development.
- Long-Term Operation Layer: Manages the persistence and systematization of sessions, states, configurations, and plugins to support the project’s long-term evolution.
This design philosophy is reflected in its clear Monorepo code structure. The apps directory handles entry points for different platforms, such as the server and desktop application; packages contains reusable core functionalities like the plugin SDK and UI components; plugins provides functional extensions; and services connects to external channels like Telegram. This layered strategy effectively isolates changes, ensuring the stability of the core system while allowing for rapid iteration.
Gateway Governance and Resource Management: The Foundation of System Stability
Project AIRI prioritizes service stability. Its request processing flow adopts a model that separates the “governance layer” from the “business logic layer.” In the implementation within apps/server/src/app.ts, all requests to /api/ first pass through a series of middleware for processing, including Cross-Origin Resource Sharing (CORS) policies, session management, logging, observability tracing (OpenTelemetry), and request body size limits. These governance measures are completed before the request reaches specific business logic (like chat or character management), thereby addressing potential stability risks upfront and avoiding the complexity of scattered handling within the business code.
This governance mindset extends to the management of model providers. Instead of treating sensitive information like API keys as simple configuration files, AIRI abstracts them into user-manageable system resources. In apps/server/src/routes/providers.ts, CRUD operations on providers are strictly constrained:
- Access Control: All routes are protected by
authGuard middleware, ensuring only authenticated users can access them.
- Data Validation: Schemas like
CreateProviderConfigSchema are used for structured validation of new and updated configurations, preventing invalid data from entering the system.
- Ownership Binding: When a provider is created, the
ownerId is forcibly bound to the current session’s user ID. During updates, the system first queries the target resource and verifies that the existing.ownerId matches the current user’s ID, effectively preventing unauthorized modification attempts. This series of backend-enforced validations firmly establishes the resource security boundary at the system level.
Pluggable Extensions: Balancing Openness and Control
Extensibility is key to the evolution of Agent systems, but uncontrolled expansion can introduce security and stability risks. Project AIRI establishes clear boundaries and a controllable lifecycle for its plugin system by introducing a state machine and a permission assertion mechanism.
The core of this is the pluginLifecycleMachine defined in packages/plugin-sdk/src/plugin-host/core.ts. This is a state machine-based implementation that precisely defines a plugin’s entire process from loading (loading) to being ready (ready), including intermediate states like authenticating (authenticating), configured (configured), and failed (failed). This allows the system to know the exact state of each plugin at any given moment, facilitating monitoring, debugging, and error handling, which significantly enhances the system’s predictability.
At the same time, AIRI emphasizes the “principle of least privilege.” Before a plugin can call any capabilities provided by the host, it must use the assertPermission method to make a permission assertion. This method checks the plugin’s scope to determine if it has the right to perform a specific action (e.g., read, write) in a specific domain (e.g., apis, resources). Any attempt to exceed its permissions is immediately blocked, and a PermissionDeniedError is thrown. This design ensures that the plugin’s extension capabilities are confined within predefined security boundaries, achieving a balance between openness and control.
The Execution Loop: From Passive Responses to Proactive Task Completion
A true Agent system must not only respond to user commands but also possess the ability to plan and execute complex tasks to achieve goals. Project AIRI implements a classic Agent Loop in its channel services (e.g., services/telegram-bot/src/bots/telegram/index.ts).
The core logic of this loop can be summarized as “Plan-Execute-Iterate”:
- Plan (Imagine): Through the
imagineAnAction function, the system combines the current conversation context, message history, and available actions to infer the next best action to execute using an LLM.
- Execute (Dispatch): The
dispatchAction function is responsible for executing the planned action. This could be a simple reply or a tool call.
- Iterate (Loop): If the execution result is a function that requires further action (
typeof result === 'function'), the system enters a while loop, continuously executing the returned subsequent operations until the task is finally completed. This chained-call mechanism enables the Agent to autonomously complete complex, multi-step tasks, forming the core closed loop of its intelligent behavior.
