Glossary for the Drupal AI initiative (#3577844) · Issues · project / ai

Glossary for the Drupal AI initiative

>>> [!note] Migrated issue   Reported by: [scott falconer](https://www.drupal.org/user/52557) >>> This is a first-pass glossary intended to align Drupal AI with common AI language, current framework language, and Drupal's existing terminology. The goal is to freeze the core terms now, avoid overloaded words, and refine edge cases later. Where a plain-language term and a provider-specific term both exist, prefer the plain-language term in public-facing docs and UI. Use the more precise technical term when architecture, runtime behavior, or interoperability matters. <h2>AX and shared-interface terms</h2> <ul> <li>Affordance: A clue in a UI, API, schema, or action surface that indicates what actions are available and how to use them.</li> <li>Agent Experience (AX): The design of systems so agents can discover, understand, and use capabilities effectively, especially when the same surfaces must also work well for humans.</li> <li>Allowed values (enum): A field or parameter restricted to a predefined set of values.</li> <li>Capability description: Human-readable and model-readable text that explains what a tool, action, field, or context item is for, when it should be used, and any key constraints.</li> <li>Constraint: A rule that restricts valid data or behavior, such as required fields, length limits, formats, allowed values, or conditional requirements.</li> <li>Discoverability: How easily a human or agent can find a relevant tool, action, field, or context item.</li> <li>Input schema: A machine-readable definition of expected inputs, including field names, types, and constraints.</li> <li>Output schema: A machine-readable definition of expected outputs, including structure, types, and constraints where applicable.</li> <li>Required field: A field or parameter that must be present for input to be considered valid.</li> <li>Schema: A machine-readable definition of structure, fields, types, and constraints.</li> <li>Shared interface: An interface, schema, or action surface intentionally designed to be understandable and operable by both humans and agents.</li> <li>Validation rule: A concrete runtime rule used to enforce one or more constraints.</li> </ul> <h2>Core terms</h2> <ul> <li>Agent: An LLM-directed execution unit that can decide whether and how to use tools, and can loop over those tools while continually working toward a task in response to the environment.</li> <li>Agent Instructions: The editable behavior text configured for an agent.</li> <li>Agent workflow: A workflow that includes one or more agent steps.</li> <li>Artifact: Stored tool output referenced by an artifact ID, handle, or placeholder string instead of being fully sent back to the model.</li> <li>Artifact storage: The mechanism that stores large tool outputs out of band and rehydrates them later.</li> <li>Assistant: A user-facing conversational wrapper that may delegate to an agent and may add chat-specific rules or presentation.</li> <li>Automator: A human-configured step-based automation that runs AI or other tools over field or entity data.</li> <li>Conversation history: The ordered transcript of messages and tool activity for a run.</li> <li>Context item: A reusable curated context artifact managed in AI Context / Context Control Center.</li> <li>Context pool: The set of context items assigned to an agent and available for runtime selection.</li> <li>Context scope: The routing or applicability rules that decide when a context item should be used.</li> <li>Drupal guardrail: A deterministic guardrail enforced by Drupal code.</li> <li>Drupal token: A placeholder pattern such as <code>[node:title]</code> resolved by Drupal's Token API.</li> <li>Embedding: A vector representation of content used for similarity search and retrieval.</li> <li>Field Widget Action (FWA): A UI trigger that adds an automator-backed action button to a field widget.</li> <li>Function call: A provider-specific or legacy term for a tool invocation. Prefer tool as the general architecture term.</li> <li>Guardrail: A configurable control applied before or after model generation or tool use to validate, stop, rewrite, or route input or output.</li> <li>Instructions: Behavior guidance given to an agent or model. In Drupal UI this will often appear as Agent Instructions.</li> <li>LLM (Large Language Model): A generative language model used for text generation, reasoning, classification, extraction, or structured output.</li> <li>LLM guardrail: A non-deterministic model-based check or rewrite.</li> <li>LLM token: A unit of model-processed text used for context-window limits, metering, and billing.</li> <li>MCP: The Model Context Protocol.</li> <li>MCP prompt: A prompt template exposed through MCP.</li> <li>MCP resource: A context-bearing resource exposed through MCP, such as files, schemas, or application data.</li> <li>MCP server: A server that exposes tools, resources, and prompts to MCP clients.</li> <li>MCP tool: A tool exposed through MCP.</li> <li>Message: A single unit in a conversation or response payload, such as a user, assistant, system, developer, or tool message.</li> <li>Message role: The message type used in an API payload, such as <code>user</code>, <code>assistant</code>, <code>system</code>, <code>developer</code>, or <code>tool</code>. This is not the same thing as a Drupal role or an initiative role.</li> <li>Model: The specific AI model used for a given call.</li> <li>Plugin context: Drupal core term for the objects passed into a plugin so it can perform its work. This is not the same thing as an AI context item.</li> <li>Prompt: A general term for text or messages sent to a model. Avoid using the bare word in Drupal AI docs when a more precise term is available.</li> <li>Provider: The service or platform that hosts or brokers model access.</li> <li>RAG (Retrieval-Augmented Generation): A pattern that retrieves relevant content, then supplies it as runtime context for generation.</li> <li>Runtime context: The information available during execution for a specific run.</li> <li>Short-term memory: The runtime layer that may summarize, rewrite, or compress conversation history, instructions, or tool state before the next model call.</li> <li>Structured output: Model output constrained to a defined schema instead of free-form text.</li> <li>System Prompt: The full system-level or developer-level instructions actually sent to the model at runtime.</li> <li>Tool: An executable capability exposed to an agent or external client.</li> <li>Tool API: The Drupal plugin and contract layer used to define typed tools.</li> <li>Vector store: A store that indexes embeddings so relevant content can be retrieved later.</li> <li>Workflow: A human-defined orchestration or automation path. Do not use this as a synonym for agent.</li> </ul> <h2>Identity and execution terms</h2> <ul> <li>Current user: The Drupal user account attached to the current request.</li> <li>Drupal role: A Drupal permission bundle assigned to user accounts. Do not confuse this with message roles or initiative roles.</li> <li>End user: The human using the UI or feature.</li> <li>Execution principal: The architecture-level identity concept instantiated at runtime by the executor.</li> <li>Executor: The Drupal user account actually used for access checks, tool execution, content mutation, and revision authorship. In plain-language docs this is often the acting user.</li> <li>Initiator: The upstream source that caused a run to begin. In plain-language docs this is often the trigger or source.</li> <li>Run mode (modality): How a run is being executed, such as interactive, background, outside-in, or scheduled.</li> <li>Runner: The execution-loop or correlation concept for a run. This is not the acting identity.</li> </ul> <h2>Multi-agent terms</h2> <ul> <li>Orchestration agent: A top-level agent whose primary job is to coordinate other agents or tools.</li> <li>Sub-agent: A normal agent when exposed to another agent as a tool.</li> <li>Triage agent: An agent that routes work to other agents but may also do some work itself.</li> </ul> <h2>Initiative-specific terms</h2> These are useful initiative terms, but they should be clearly labeled as initiative language rather than universal AI language. <ul> <li>AI Context: The broader module or project name.</li> <li>AI Maker: A Drupal AI initiative term for participating companies or contributors.</li> <li>Context Control Center (CCC): The admin and governance surface within AI Context.</li> <li>Drupal AI Role: A named initiative responsibility area. This is not the same thing as a Drupal runtime role or a message role.</li> <li>Drupal AI Team: A named initiative working group such as Leadership, Core, Innovation, Product, UX, QA, or Marketing.</li> </ul> <h2>Terms to avoid using bare</h2> Avoid these unless they are qualified: <ul> <li>context</li> <li>memory</li> <li>principal</li> <li>prompt</li> <li>role</li> <li>token</li> <li>user</li> <li>workflow</li> </ul> <h2>Style rules</h2> <ul> <li>Prefer tool over function call as the general architecture term.</li> <li>Prefer instructions over bare prompt in public-facing docs.</li> <li>Prefer conversation history over chat history in public docs.</li> <li>Prefer end user, current user, executor, or initiator over bare user.</li> <li>Prefer runtime context, context item, context pool, context scope, or plugin context over bare context.</li> <li>Prefer LLM token or Drupal token over bare token.</li> <li>Prefer message role, Drupal role, or initiative role over bare role.</li> <li>Prefer constraint or validation rule over guardrail for ordinary required fields, allowed values, length limits, and format checks.</li> <li>For AX work, describe shared interfaces in terms of discoverability, capability descriptions, schemas, constraints, and validation rules.</li> <li>Qualify workflow as agent workflow, content workflow, or Drupal workflow when ambiguity is possible.</li> </ul> <h2>Proposed status</h2> Freeze the core terms now, keep initiative terms explicitly scoped, and revisit edge cases once related issue-queue work settles.

issue