应用管理

在 Snail AI 的分布式架构中，"应用"（App）是连接 Server 端与 Agent Client 客户端的桥梁。每个应用代表一个独立的执行环境，拥有自己的身份标识、认证 Token 和路由策略，负责管理一组 Agent Client 节点，并将智能体的推理请求分发到合适的客户端实例上执行。

核心概念

Server-Client 分布式架构

Snail AI 采用 Server-Client 分离的分布式架构：

┌─────────────────────────────────┐
│         Snail AI Server         │
│  ┌───────────┐  ┌────────────┐  │
│  │ REST API  │  │ Agent 责任链│  │
│  │ SSE 推送  │  │ RAG 引擎   │  │
│  └─────┬─────┘  └─────┬──────┘  │
│        │     gRPC      │        │
│        └──────┬────────┘        │
└───────────────┼─────────────────┘
                │
          ┌─────┴─────┐
          │   应用     │
          │ (路由分发)  │
          └─┬───┬───┬─┘
            │   │   │
     ┌──────┘   │   └──────┐
     ▼          ▼          ▼
┌─────────┐ ┌─────────┐ ┌─────────┐
│ Client  │ │ Client  │ │ Client  │
│ Node 1  │ │ Node 2  │ │ Node 3  │
│(gRPC)   │ │(gRPC)   │ │(gRPC)   │
└─────────┘ └─────────┘ └─────────┘

• Server：负责用户请求接入、智能体配置管理、RAG 检索、记忆管理等编排调度工作。
• 应用（App）：逻辑分组单元，管理一组 Agent Client 实例，并定义请求的路由策略。
• Client Node：实际的执行节点，通过 gRPC 双向流与 Server 通信，负责调用 LLM、执行本地工具、运行拦截器链等推理逻辑。

应用的作用

应用在分布式架构中承担以下职责：

职责	说明
身份隔离	每个应用拥有独立的 appId 和 token，不同应用的客户端实例互不干扰
认证鉴权	Agent Client 通过应用 Token 向 Server 注册，确保只有合法的客户端能接入
路由分发	根据配置的路由策略，将推理请求分发到最合适的客户端节点
负载管理	跟踪各节点的在线状态和负载情况，实现智能化的流量调度

智能体与应用的关系

智能体可以通过 appId 字段绑定到特定的执行应用。绑定后，该智能体的所有推理请求将通过对应应用的路由策略分发到其管理的客户端节点上执行。

• 如果智能体未绑定应用（appId 为空），则使用 Server 本地的默认执行逻辑。
• 一个应用可以服务多个智能体。
• 智能体只能绑定一个应用（单选）。

应用数据模型

每个应用包含以下核心字段：

字段	类型	说明
id	number	数据库自增主键
appId	string	应用唯一标识，创建后不可修改
appName	string	应用显示名称
description	string	应用描述
token	string	应用认证 Token，客户端注册时需要携带
routeStrategy	string	路由策略（LEAST_LOAD/ROUND_ROBIN/CONSISTENT_HASH/RANDOM/LRU/FIRST）
status	number	应用状态：1 = 启用，0 = 禁用
onlineNodes	number	当前在线的客户端节点数
createDt	string	创建时间

应用管理操作

创建应用

1. 在「应用管理」页面，点击「新增」按钮。
2. 在弹出的抽屉中填写以下信息：

字段	必填	说明
应用 ID	是	应用的唯一标识，例如 order-agent-app。创建后不可修改
应用名称	是	应用的显示名称，例如"订单处理应用"
描述	否	应用的功能说明
路由策略	是	请求分发策略，默认为"最少负载"。详见 路由策略

3. 点击「确定」提交。

创建成功后，系统会自动生成一个 Token，该 Token 用于 Agent Client 向 Server 注册时的认证。

重要

Token 是应用的认证凭证，创建后会以弹窗形式展示一次。请妥善保存 Token，它在后续列表中会以脱敏形式展示（显示为 ••••••••）。

查看应用列表

应用列表以表格形式展示，包含以下列：

列	说明
应用 ID	点击可查看该应用下的客户端节点
名称	应用显示名称
Token	脱敏展示，提供「复制」按钮
描述	应用描述
路由策略	当前使用的路由策略（标签形式展示）
状态	启用/禁用
在线节点	当前在线的客户端实例数（绿色高亮）
创建时间	应用创建时间
操作	实例、编辑、启停、删除

编辑应用

点击操作列中的「编辑」按钮，可以修改应用的名称、描述和路由策略。应用 ID 创建后不可修改。

切换应用状态

点击操作列中的「启用」或「禁用」按钮，可以切换应用的启停状态：

• 启用：应用处于活跃状态，可以接受客户端注册和请求分发。
• 禁用：应用被停用，已连接的客户端仍保持连接，但不再接受新的注册和请求分发。

删除应用

点击操作列中的「删除」按钮，在确认后删除应用。删除操作不可撤销。

注意

删除应用前，请确保没有智能体正在绑定该应用。删除应用后，绑定到该应用的智能体将失去远程执行能力。

查看客户端实例

点击应用 ID 或操作列中的「实例」按钮，可以打开客户端节点管理抽屉，查看该应用下所有已注册的客户端实例。详见 客户端节点。

搜索与过滤

应用列表支持以下搜索条件：

• 关键词搜索：按应用 ID 或名称进行模糊搜索。
• 状态过滤：筛选启用或禁用状态的应用。
• 时间范围：按创建时间范围过滤。

使用建议

1. 按业务分组：建议按业务领域或团队创建独立的应用，例如"订单处理应用"、"客服应用"、"数据分析应用"。
2. 合理选择路由策略：根据业务特点选择合适的路由策略。详见 路由策略。
3. 保管好 Token：Token 是客户端接入的唯一凭证，应妥善保管，避免泄露。
4. 监控在线节点数：定期检查各应用的在线节点数，确保有足够的计算资源。

下一步

• 客户端节点 -- 了解客户端节点的注册、管理和监控
• 路由策略 -- 详细了解 6 种路由策略的工作原理和适用场景