TheYgent

TheYgent is a local-first AI Agent platform with a two-plane architecture: the inference plane runs models (engine processes, model weights, model registry, API credentials), and the control plane orchestrates Agents (graph runtime, Agent registry, sessions, triggers, MCP servers, retrieval sources, secrets and run traces).

TheYgent's architectural rule is that the control plane never imports the engine, contains no MLX, vLLM or llama.cpp bindings at all, and accesses inference capability only through the inference plane's OpenAI-compatible HTTP API.

TheYgent's inference plane exposes OpenAI-compatible REST endpoints (such as /v1/chat/completions, /v1/embeddings), and any service compatible with this protocol can be connected as an inference backend.

In TheYgent, every model reference in an Agent, chat or benchmark is a logical ID (such as triage-fast), and engine names never appear on the data plane; if a graph tries to call with mlx or llamacpp as the model name, it is rejected with an engine_name_not_allowed error.

TheYgent's Binding field has only four values: mlx, vllm, llamacpp or openai-compatible; the first three are engines whose lifecycle TheYgent manages, and everything else—managed APIs or existing model servers—is openai-compatible plus a URL.

Registering a model binding in TheYgent also includes two other dimensions: source indicates the weight origin (hf, local-path, url), and modality indicates server capabilities (chat, vision, embeddings, speech-to-text, text-to-speech, image generation).

TheYgent's inference plane uses an engine manager pattern: engines start lazily on the first call to their logical ID, the default upper limit on simultaneously loaded engines is two, engines idle for fifteen minutes are reclaimed, engines with requests in flight are never evicted, and calls fail with no_capacity when they cannot be released.

In TheYgent, an Agent is essentially a typed document (a typed intermediate representation), defined in Pydantic, with the TypeScript types used by the editor generated from it, and a CI check that fails when the two diverge; the document carries a content hash computed from canonicalized JSON; publishing produces immutable, content-addressed versions.

In TheYgent, secrets are never stored in Agent documents; connections carry references to encrypted storage, so rotating an API key leaves the reference unchanged and the Agent's hash unchanged.

TheYgent's durable runtime is built on DBOS—an embedded Python library that records workflow state into the Postgres the control plane already has, with no need to deploy a new stateful service.

In TheYgent's durable runtime, completed steps are exactly-once (on recovery they are replayed from the log rather than re-executed), while a step that was executing at the time of a crash is at-least-once, so HTTP tools support idempotency keys.

TheYgent's four process types are the interface, the control plane, the inference plane and an optional durable Worker, and it can be run on bare metal via make up, or on Docker Compose and Kubernetes.

TheYgent models are obtained through the in-app Hugging Face catalog, which shows before downloading whether each quantization fits the machine's memory; installed weights are registered as local files, and loading them never touches the network.

In TheYgent, migrating a model from MLX on a Mac to llama.cpp on Linux, or from a local model to a managed API, requires only changing the registration once, with no need to edit any Agent or republish.