Skip to content

Glossary

The terms used across TheYgent and this documentation, in alphabetical order. Where a concept has its own page, the definition links to it.

Activity

One of the three node kinds. Activity nodes do non-deterministic work with side effects — calling a model (llm), running a tool (tool, mcp_tool), transcribing audio, generating an image. See Nodes, ports & edges.

Agent

A saved, runnable AI workflow: a graph of nodes plus its model and tool bindings, published under an id. You build agents in the editor and run them from the Bench, from chat, or behind a trigger. See Agents & graphs.

Artifact

A blob of generated media — audio or an image — stored on local disk and passed between steps by reference (an art_… id) rather than inline. A voice agent's spoken reply and an image node's output are artifacts. Bytes stay in your trust domain and are never journaled into a run's history. See Voice.

Binding

How a logical model maps to something that can actually answer a request. The binding value is one of four: mlx, vllm, llamacpp (local engines TheYgent manages), or openai-compatible (any reachable OpenAI-style server or hosted API). See Models & engines.

Boundary

One of the three node kinds: the entry, exit, and wait points of a graph — input, output, human, subgraph. See Nodes, ports & edges.

Capability

A property of a model, probed from the engine: whether it supports tool-calling, structured output, vision, or reasoning, and its maximum context length. Capabilities drive which controls appear on the Bench and which badges show in the Registries page.

Channel

What an edge carries between ports. data passes a value; control is pure sequencing (run-after, no value); tool is a capability wire connecting a tool node to an llm so the model may call it. See Nodes, ports & edges.

Connection

A named, reusable credential for a tool or MCP server — kind http_auth or mcp_server. The non-secret config is stored plainly; the secret is encrypted, write-only, and never appears in the graph. See Tools.

Content hash

The sha256: fingerprint that gives an agent version its identity, computed over the graph with layout stripped and defaults filled. Rearranging the canvas, zooming, or changing a node's icon never changes it; changing a message, config value, or edge does. See Agent versioning.

Control plane

The hosted orchestration service (default http://localhost:8080) that owns agents, runs, sessions, triggers, connections, artifacts, and observability, backed by your Postgres. It reaches the inference plane over HTTP only and never runs models itself. See Architecture.

Durable run

A run executed on the durable runtime, which checkpoints each completed step so the run survives a crash and resumes where it left off. Durable mode also unlocks the human, subgraph, loop, and map node types. See Durable runs.

Edge

A wire connecting one node's out-port to another's in-port, carrying a channel. At most one data edge may feed a given in-port. See Nodes, ports & edges.

Engine

The underlying server program that runs a model — llama.cpp, an MLX server, whisper.cpp, vLLM, or an image-generation CLI wrapper. TheYgent lazily spawns and supervises managed engines; you never name an engine when calling a model. See Engines.

Graph

The document that defines an agent: a camelCase JSON envelope holding the model and tool bindings, a list of typed nodes, and the edges wiring them, plus a never-hashed view block for canvas layout. Also called the IR (intermediate representation). See Agents & graphs.

Guardrail

A node that checks its input against a rule (regex, length, allow/deny list, JSON-shape, PII) or an LLM judge, then routes to a pass or block port. Wire block to an output to refuse a request before doing expensive work. See Guardrail.

Inference plane

The user-controlled service (default http://localhost:8081) that registers models under logical ids, spawns engines, and answers OpenAI-compatible requests. It runs wherever you point it and keeps its registry and weights on your machine. See Architecture.

I/O capture

The policy governing whether a run's per-node input/output payloads are recorded for the observability waterfall: off, metadata (byte sizes only), or full. Capped by an environment ceiling. See Observability.

Kind

The category of a node: activity, orchestration, or boundary. Every node type has exactly one correct kind (the guardrail is the one exception, whose kind follows its check type). See Nodes, ports & edges.

Logical model id

The name you give a model when you register it (for example triage-fast) and the only thing you ever put in a model field. It hides the engine and weights behind it, so swapping a local model for a hosted one is one registration change with no graph edits. See Models & engines.

MCP (Model Context Protocol)

An open protocol for exposing external tools to models. TheYgent connects to MCP servers — over stdio (a local process) or HTTP — and lets your agents call the tools they expose through the mcp_tool node. See MCP tools.

Modality

What kind of input/output a model handles: chat, vision, embeddings, audio.transcription, audio.speech, or images.generation. A model is registered for one modality; it is a third axis orthogonal to binding and source. See Models & engines.

Node

One step in a graph: a typed box with a config, in-ports, and out-ports. Seventeen types are executable, across the three kinds. See the node reference.

Orchestration

One of the three node kinds: deterministic control flow — router, transform, loop, map. See Nodes, ports & edges.

Port

A named connection point on a node, on the in or out side, carrying a channel (data, control, or tool). A required in-port must be fed by exactly one data edge for the graph to validate. See Nodes, ports & edges.

Run

One execution of an agent or graph. It moves through statuses created → streaming → waiting → completed | failed, persists in Postgres, and survives restarts. Its output is the value that reached the output node. See Runs & sessions.

Session

Opt-in conversational memory: a stored thread of turns that a run can read back and append to, so a model remembers earlier messages. Passing a session_id on a run turns it on; without one, the run is a one-shot. See Runs & sessions.

Source

Where a managed model's weights come from: hf (a Hugging Face repo), local-path (a file or directory on disk), or url. Separate from the binding — Hugging Face is a source of weights, not an engine. See Models & engines.

Span

One node in a run's trace: a timed bar in the observability waterfall, with a status (ok, err, skipped, running) and, on model-generation phases, token counts. Spans carry timing and metadata; payloads are stored separately and gated by the I/O capture policy.

Trigger

A deployed entry point that fires a saved, pinned agent unattended: a schedule (cron) or a webhook (an HTTP POST with an HMAC signature). A saved agent can also be reached through the always-on token-invoke endpoint, which is gated by THEYGENT_INVOKE_TOKEN rather than created as a trigger. See Triggers & webhooks.

Version

An immutable, content-addressed snapshot of an agent, identified by its version string and content hash. Publishing new content mints a new version; the old ones remain runnable. See Agent versioning.

Webhook

A trigger kind that runs an agent when an external system POSTs to /hooks/{id}. The request body becomes the run input; a per-webhook secret authenticates the call via an HMAC signature. See Triggers & webhooks.

Worker

The standalone process (theygent-worker) that runs the durable queue in a server or air-gapped deployment. On your own machine you don't need it — setting THEYGENT_DURABLE=1 runs the same runtime inside the control plane. See Durable runs.