TheYgent

TheYgent是一个本地优先的AI Agent平台，采用双平面架构：推理平面运行模型（引擎进程、模型权重、模型注册表、API凭证），控制平面编排Agent（图运行时、Agent注册表、会话、触发器、MCP服务器、检索源、密钥和运行轨迹）。

TheYgent的架构规则是控制平面永远不导入引擎，不包含任何MLX、vLLM或llama.cpp的绑定，仅通过推理平面的OpenAI兼容HTTP API访问推理能力。

TheYgent的推理平面暴露OpenAI兼容的REST端点（如/v1/chat/completions、/v1/embeddings），任何兼容此协议的服务都可以作为推理后端接入。

TheYgent中Agent、聊天或基准测试中的每个模型引用都是逻辑ID（如triage-fast），引擎名称从不出现在数据平面上；若图试图以mlx或llamacpp作为模型名调用，会被拒绝并返回engine_name_not_allowed错误。

TheYgent的Binding字段只有四个值：mlx、vllm、llamacpp或openai-compatible；前三个是TheYgent管理生命周期的引擎，其他一切托管API或已有模型服务器都是openai-compatible加一个URL。

TheYgent中将模型绑定注册还包含另外两个维度：source表示权重来源（hf、local-path、url），modality表示服务器功能（chat、vision、embeddings、speech-to-text、text-to-speech、image generation）。

TheYgent的推理平面采用引擎管理器模式：引擎在首次调用其逻辑ID时惰性启动，同时加载引擎数量默认上限为两个，空闲十五分钟的引擎被回收，有请求在途的引擎永不被驱逐，无法释放时调用以no_capacity失败。

TheYgent中Agent本质上是一个类型化文档（类型化中间表示），在Pydantic中定义，编辑器使用的TypeScript类型从中生成，并有CI检查在两者偏离时失败；文档携带基于规范化JSON计算的内容哈希；发布生成不可变、内容寻址的版本。

TheYgent中密钥从不存放在Agent文档中，连接携带对加密存储的引用，因此轮换API密钥时引用保持不变，Agent的哈希也不变。

TheYgent的持久化运行时构建在DBOS之上——一个嵌入式Python库，将工作流状态记录到控制平面已有的Postgres中，无需部署新的有状态服务。

在TheYgent持久化运行时中，已完成的步骤是精确一次（恢复时从日志重放而不重新执行），崩溃时正在执行的步骤是至少一次，因此HTTP工具支持幂等键。

TheYgent的四种进程类型为界面、控制平面、推理平面和可选的持久化Worker，可通过make up在裸机上运行，也可在Docker Compose和Kubernetes上运行。

TheYgent模型通过应用内的Hugging Face目录获取，该目录在下载前显示每种量化版本是否适合机器内存；安装的权重注册为本地文件，加载它们永远不会访问网络。

TheYgent中将模型从Mac上的MLX迁移到Linux上的llama.cpp，或从本地模型迁移到托管API，只需更改一次注册，不需要编辑任何Agent或重新发布。