---
title: "STAIR Concepts"
group: "Reference"
groupOrder: 5
order: 1
---
STAIR concepts explain the records you work with in STAIR, such as agents, models, toolsets and gateways, and how they relate to each other.

## How the STAIR object model fits together

An **Agent** is the center of STAIR. It uses one **Model**, may use **Toolsets**, **Skills** and **Sub-agents**, and is run from STAIR Chat, the API, a **Workflow**, a **Schedule**, an **Agent Evaluation** or an **MCP Gateway**. Credentials never sit on the agent: an LLM provider key is stored as a **Secret** and referenced by its model provider, and toolset credentials are set on the toolset or entered by each user.

![STAIR object model: an agent uses one model from a model provider, tools from toolsets connected to MCP servers from the MCP Catalog, skills and sub-agents.](./stair-concepts-agent-building-blocks.png)

![What runs a STAIR agent: STAIR Chat, the OpenAI-compatible API, an MCP Gateway, a workflow or an agent evaluation, and a schedule that starts a workflow or an agent.](./stair-concepts-how-agents-run.png)

Every one of these records has an access list (**ACL**). People reach a record through their own user, a **Team** or, for integrations, a **Service Account** with an API key.

## STAIR concepts reference

### Build concepts

| Concept | What it is | Where in STAIR | Related page |
|---|---|---|---|
| Agent | A configured AI assistant: model, Agent Purpose, Boundaries, Instructions, toolsets, skills and sub-agents. Called by its **Agent Name** | Sidebar **Workspace → Agents** | [AI Agents](/docs/ai-agents/llm.md) |
| Sub-agent | An existing agent attached to another agent so that it can delegate tasks to it | Agent → **Sub Agents** tab | [AI Agents](/docs/ai-agents/llm.md) |
| Agent capabilities | Switches **Planning**, **Filesystem**, **Delegation** and **Code execution** that turn parts of the agent runtime on or off | Agent → **General** | [AI Agents](/docs/ai-agents/llm.md) |
| Run | One execution of an agent, workflow, schedule or evaluation, with status and duration | **Runs** tabs | [AI Agents](/docs/ai-agents/llm.md) |
| Skill | A reusable instruction package: a `SKILL.md` file plus optional files that an agent loads when it needs them | **Workspace → Skills** | [Agent Skills](/docs/agent-skills/llm.md) |
| Toolset | A connection to one MCP server, with its authentication mode and the list of tools agents may use | **Workspace → Toolsets** | [Toolsets and MCP Tools](/docs/toolsets-and-mcp-tools/llm.md) |
| Tool | One callable operation exposed by an MCP server, enabled per agent | Toolset → **Tools** tab; agent's **Toolsets** tab | [Toolsets and MCP Tools](/docs/toolsets-and-mcp-tools/llm.md) |
| Classification | A label inside a classification group, used to filter agents, toolsets, skills, workflows and MCP Gateways | **System → Classifications**; **Classifications** panel and tab | [Classifications](/docs/classifications/llm.md) |
| Classification group | A named, colored set of classifications with an **Applies to** list | **Classifications → Create** | [Classifications](/docs/classifications/llm.md) |

### Connect concepts

| Concept | What it is | Where in STAIR | Related page |
|---|---|---|---|
| Model Provider | A connection to an LLM provider (Open AI, Open Router, Azure OpenAI, vLLM, Ollama or Custom) with a Base URL and an optional authentication secret | **Configuration → Models → Providers** | [LLM Models](/docs/llm-models/llm.md) |
| Model | An LLM registered from a model provider, used by agents and as a judge model. Holds context window and pricing | **Configuration → Models → Models** | [LLM Models](/docs/llm-models/llm.md) |
| Secret | A stored credential value (text or JSON), referenced by model providers in their **Authentication secret** field | **Configuration → Secrets** | [Secrets](/docs/secrets/llm.md) |
| Registry | A source of MCP Catalog entries. Static registries sync automatically; custom registry sources are managed by users | **MCP → Registries** | [MCP Server Catalog](/docs/mcp-server-catalog/llm.md) |
| MCP Catalog | The browsable list of MCP servers from all registries, with **Deploy** or **Add Toolset** | **MCP → Catalog** | [MCP Server Catalog](/docs/mcp-server-catalog/llm.md) |
| MCP Server Instance | An MCP server that STAIR deploys from a catalog entry and runs; toolsets connect to it | **MCP → Server Instances** | [MCP Server Catalog](/docs/mcp-server-catalog/llm.md) |
| MCP Gateway | One MCP endpoint that exposes selected toolset tools and agents (as stateless MCP tools) to external MCP clients, authenticated with an API key in the `STAIR-API-KEY` header | **MCP → MCP Gateways** | [MCP Gateways](/docs/mcp-gateways/llm.md) |
| Identity Provider | An OAuth or OIDC provider configuration (Okta, Microsoft Entra or Generic OIDC) used by the OAuth authentication modes of toolsets | **Administration → Identity Providers** | [STAIR Administration](/docs/stair-administration/llm.md) |
| Personal API key | A key (`aip_sk_…`) that a user creates for themselves. It is shown once, needs an expiration date and acts with the owner's roles | User menu → **Connections → Tokens** | [API Keys and Service Accounts](/docs/api-keys-and-service-accounts/llm.md) |
| Service Account | A non-human identity with API keys for integrations. It gets access through ACL, for example Execute Access on an agent or MCP Gateway | **Configuration → Service Accounts** | [API Keys and Service Accounts](/docs/api-keys-and-service-accounts/llm.md) |
| Toolset connection | A credential of yours stored for a toolset: an OAuth token you approved or a header value you entered | User menu → **Connections → Toolset** | [Toolsets and MCP Tools](/docs/toolsets-and-mcp-tools/llm.md) |

### Operate concepts

| Concept | What it is | Where in STAIR | Related page |
|---|---|---|---|
| STAIR Chat | The end-user app for talking to agents, with folders, attachments and shared links | **External Tools → Chat** | [STAIR Chat](/docs/stair-chat/llm.md) |
| Folder | A group of conversations in STAIR Chat | STAIR Chat sidebar → **New folder** | [STAIR Chat](/docs/stair-chat/llm.md) |
| Knowledge | The document knowledge-base app with categories, uploads and its own chat | **External Tools → Knowledge** | [Knowledge Base and RAG](/docs/knowledge-base-and-rag/llm.md) |
| Workflow | A graph of nodes (Start, STAIR Agent, Condition, Notification, Action) run with initial instructions | **Workspace → Workflows** | [Agent Workflows](/docs/agent-workflows/llm.md) |
| Node | One step of a workflow graph; later nodes can use the output of earlier ones | Workflow → **Graph** | [Agent Workflows](/docs/agent-workflows/llm.md) |
| Schedule | A cron rule that runs a workflow or an agent between a start and an end date, in a time zone | **Workspace → Schedules** | [Scheduled Agent Runs](/docs/scheduled-agent-runs/llm.md) |
| Agent Evaluation | A test that sends scripted requests to a target agent and grades the answers with evaluators | **Workspace → Agent Evaluations** | [Agent Evaluations](/docs/agent-evaluations/llm.md) |
| Request | One scripted dialog in an evaluation, ending with the User message to grade | Evaluation → **Requests** | [Agent Evaluations](/docs/agent-evaluations/llm.md) |
| Evaluator | A built-in grading rule, such as a text match, a tool-call check or an LLM judge | **Agent Evaluations → View all evaluators** | [Agent Evaluations](/docs/agent-evaluations/llm.md) |
| Judge model | The model that LLM-based evaluators use to grade answers; optional | Evaluation → **General** | [Agent Evaluations](/docs/agent-evaluations/llm.md) |
| Job | A background task: Export, Import, Keycloak Sync, Purge or MCP Registry Sync | **Administration → Jobs** | [STAIR Administration](/docs/stair-administration/llm.md) |
| Data Transfer | Export of selected records into a ZIP bundle and import of a bundle into another installation | **System → Data Transfer** | [Data Transfer](/docs/data-transfer/llm.md) |
| License | The installation license, with expiry date and per-entity limits | **Administration → License** | [STAIR Administration](/docs/stair-administration/llm.md) |
| Usage | An embedded dashboard with runs, estimated cost, LLM calls, tokens and response time | **Usage** tab on agents, toolsets and models | [Logs and Usage Metrics](/docs/logs-and-usage-metrics/llm.md) |

### Access control concepts

| Concept | What it is | Where in STAIR | Related page |
|---|---|---|---|
| Role | An installation-wide role: **Root**, **Admin**, **User** or **Classifier**. It decides which console pages you see | User button in the sidebar | [STAIR Console Navigation](/docs/stair-console-navigation/llm.md) |
| Owner | The required primary maintainer (user or team) accountable for a record | **Access Control** tab → **Ownership** | [Security and Access Control](/docs/security-and-access-control/llm.md) |
| ACL | The per-record permission list: **Read Access**, **Write Access**, **Manage Access** (required) and, on runnable records, **Execute Access** | **Access Control** tabs; **System → ACL Rules** | [Security and Access Control](/docs/security-and-access-control/llm.md) |
| Execute Access | Permission to run or call a record: agents, models, MCP Gateways and agent evaluations | **Access Control** tab | [Security and Access Control](/docs/security-and-access-control/llm.md) |
| Team | A group of users from the directory, used as an ACL principal | ACL pickers; **ACL Rules** | [Security and Access Control](/docs/security-and-access-control/llm.md) |
| PII masking | Agent setting (**Handles personal data**, **PII Entity Types**) that replaces personal data with placeholders before the request reaches the LLM | Agent → **General** | [Security and Access Control](/docs/security-and-access-control/llm.md) |
| Activity Log | The audit list of created, updated, status-changed, deleted and ACL-updated records | **System → Activity Log**; **Show History** | [Logs and Usage Metrics](/docs/logs-and-usage-metrics/llm.md) |
| Status | **Enabled** or **Disabled**. A disabled agent, toolset, model, workflow, schedule or gateway cannot be used | Status badge | [AI Agents](/docs/ai-agents/llm.md) |

## How STAIR records relate

- **Agent → Model.** Each agent uses exactly one model. A model belongs to one model provider, and the provider holds the Base URL and the authentication secret.
- **Agent → Toolsets → Tools.** An agent can use several toolsets and, for each, a subset of its tools. A tool's description can be appended to or replaced for one agent.
- **Toolset → MCP server.** A toolset points either to an MCP Server Instance that STAIR runs or to a server URL. Its authentication mode decides whose credential reaches the MCP server: none, a token header (static, or dynamic per user), OAuth 2.1 per user, or OAuth 2.0 client credentials through an Identity Provider.
- **Registry → MCP Catalog → MCP Server Instance.** Registries fill the catalog; **Deploy** on a catalog entry creates a server instance; a toolset then connects to it.
- **Agent → Sub-agents.** A sub-agent is a full agent with its own model and tools. The parent delegates to it when **Delegation** is on.
- **Agent → Skills.** Skills are loaded by the agent at run time; one skill can be attached to many agents.
- **Workflow, Schedule, Agent Evaluation → Agent.** A workflow's STAIR Agent node, a schedule of type Agent and an evaluation's target agent each run an existing agent.
- **MCP Gateway → Toolsets and Agents.** A gateway republishes selected tools and agents through one endpoint. Callers need Execute Access on the gateway.
- **Personal API key, Service Account → ACL.** A personal key acts as its owner. A service account gets access only through ACL entries.
- **Classification → records.** Classifications tag agents, toolsets, skills, workflows and MCP Gateways so lists can be filtered by them.

## FAQ

### What is the difference between a model and an agent in STAIR?

A model is an LLM registered from a provider. An agent uses one model and adds instructions, tools, skills and sub-agents. In the OpenAI-compatible API, the `model` field is the agent name, not the LLM.

### What is the difference between a toolset and an MCP server instance?

An MCP server instance is a running MCP server that STAIR deploys. A toolset is the connection that agents use: it points to an instance or a server URL, sets authentication and selects tools.

### What is the difference between a skill and a tool?

A tool is an operation that an MCP server performs, such as running code. A skill is a set of instructions and files that tells the agent how to do a task; it does not call anything by itself.

### What is the difference between a personal API key and a service account?

A personal API key belongs to a user and has that user's roles and permissions. A service account is a separate identity for an integration and has only the permissions granted to it through ACL.

### What is the difference between a role and an ACL in STAIR?

A role (Root, Admin, User, Classifier) applies to the whole installation and decides which pages you see. An ACL applies to one record and decides who can read, edit, manage or run it.

## Related

- [What is STAIR](/docs/what-is-stair/llm.md)
- [STAIR Console Navigation](/docs/stair-console-navigation/llm.md)
- [AI Agents](/docs/ai-agents/llm.md)
- [Toolsets and MCP Tools](/docs/toolsets-and-mcp-tools/llm.md)
- [MCP Gateways](/docs/mcp-gateways/llm.md)
- [Security and Access Control](/docs/security-and-access-control/llm.md)
- [STAIR FAQ](/docs/stair-faq/llm.md)