Agent definitions

An agent definition is a versioned, centrally managed identity and behavior for an agent. It is one of apistash's four shareable primitives alongside prompts, resources, and custom tools.

Create and manage Agent definitions in the dashboard or through the create_agent, update_agent, and related MCP management tools. Each definition has always-on behavior and optional conditional context. Updating behavior creates a new immutable active version; MCP reads resolve whichever version is active when the call is made.

Use an agent definition when the same role should behave consistently across clients, projects, and new sessions. Instead of copying a large instruction block into every local configuration, you can assign the role to a credential once and maintain it centrally.

What a definition contains

The dashboard presents a definition as a behavior map with three levels:

Part	Purpose
Identity	Describes who the Agent is, the role it takes, and the outcome it is responsible for.
Categories	Organize related behavior into ordered branches such as Principles, Workflow, or Communication.
Components	Hold the actual instructions, delivered either always or only for matching task context.

For example, a release steward could have an identity that owns release safety, an always-on component that requires evidence before reporting success, and a conditional rollback component whose load condition says to fetch it when a deployment fails.

Choose always on for behavior that should influence every task performed by the role. Choose conditional for detailed guidance that matters only in a recognizable situation. Conditional components require a clear Load when description; bootstrap advertises that description without spending context on the full instructions, and the agent retrieves the instructions only when the condition applies.

Keep the default context focused

Put the Agent's durable identity, non-negotiable principles, and normal working style in always-on behavior. Put long playbooks, specialist rules, and uncommon edge cases behind precise conditional load guidance.

How agent definitions and prompts differ

A prompt is a reusable task template that a user or agent invokes when needed. An agent definition is the durable role and operating behavior selected at task start. A code-review prompt can tell an Agent what review to perform; a code-reviewer agent definition can determine how that role reasons, communicates findings, and which specialist guidance it loads across every review task.

Neither replaces resources, which hold knowledge the Agent can read, or custom tools, which let it act on connected systems.

From definition to task behavior

1. Create an Agent in your personal or team space through the dashboard or create_agent. Organization-catalog publication remains a dashboard action.
2. Describe its identity, group its behavior into categories, and add always-on or conditional components.
3. Save the definition and assign it to an API key or OAuth connection that grants Agents.
4. Set up task-start context for the client if you want it to call bootstrap automatically in later tasks.
5. At primary-task start, bootstrap resolves the credential assignment and returns its identity, always-on behavior, and conditional-context hints from the current active version. For each subagent, the parent explicitly chooses a named role, delegated self-selection, or no role.
6. When a hint matches the task, the agent requests that component from agent_context using the same qualified Agent name. That call reads the current active version again.

This keeps short tasks lean while still making deep, role-specific guidance available exactly when it is useful.

Assignment and task selection

Assign one visible agent definition to an API key or OAuth connection in the dashboard. The credential must grant Agents (agents for an API key or mcp_agents for OAuth); assignment choices and set/replace also apply its ownership, team exposure, and Agent policy. At task start, bootstrap with primary_agent: true uses that assignment unless the user explicitly directs otherwise. Without an assignment, the primary may choose a suitable definition or continue without one. An unavailable assignment is reported without an automatic substitute.

Subagents never inherit the credential assignment. Their parent must explicitly specify named, self, or none. A self-selecting subagent with no suitable definition reports to its parent, which decides how to proceed within its authority. Role selection never changes the credential assignment or saves a local default.

Bootstrap separates the task's own role from its visible Agent catalog. A primary can retain its assigned role while discovering definitions for permitted delegation. Primaries and self-selecting subagents receive the catalog automatically; others can request it without changing their own role. Catalog access does not itself authorize a role change or delegation.

An agent definition guides how an agent works; it does not grant access. The credential's existing permissions, MCP capabilities, team bindings, and policies still decide what the agent can reach. If a requested assigned Agent is no longer available, bootstrap keeps the task's normal scope and team context without exposing the former assignment. The stored assignment can still be cleared even while unavailable.

Assignments belong to the exact connection. Two API keys held by the same user can select different Agents, and a hybrid OAuth client keeps delegated user connections separate from its organization machine-to-machine connection. Clearing or changing an assignment affects the next Bootstrap call that requests it; it does not write a default into the local client. The dashboard's key and OAuth-connection detail pages also show the optional task-start setup flow and the independent Agent controls.

Tools and Agents are separate controls. The bootstrap system tool does not require Tools; returning Agent content through it needs Agents (agents / mcp_agents). Personal API keys can narrow Agents with a secondary per-key Agent policy. Organization keys and OAuth connections have no such per-credential Agent policy. Personal OAuth follows personal ownership; organization keys and organization OAuth connections follow team policy and organization exposure. Management access is separate from Agent use. All governed Agent-management tools require Tools and tool-policy admission. A standalone personal mutation additionally requires its action-specific Agent permission; a Team mutation requires a binding and the corresponding Team permission; a private me/ mutation requires an acting user with active organization membership. list_agents and get_agent instead require Agents and apply current Agent visibility. Being allowed to edit a definition does not make it usable, and being allowed to use it does not make it editable.

Behavior is not authorization

An agent definition can tell an agent to deploy, review, or investigate, but it cannot give the credential permission to do so. Grant tools, resources, prompts, teams, and management access separately through the access model.

Conditional context

Bootstrap includes the selected Agent's identity and always-on behavior, plus hints for optional context. When a hint applies, the agent calls agent_context with the selected qualified Agent name. That call rechecks visibility and returns the requested conditional behavior from the definition's current active version. If the Agent was renamed, or the requested component changed or disappeared, the call returns a non-revealing unavailable result; bootstrap again before deciding whether to retry with the current definition.

agent_context is needed only for conditional components that bootstrap advertises. Returning content requires Agents and current Agent visibility.

Version history

Every behavior change creates a new immutable active version. Name, description, ownership exposure, and version-retention settings are metadata and can change without creating one. Restoring an older version does not make that stored version mutable: it creates a new active version with the older behavior, while retained history remains available.

Your plan limits how many versions each Agent retains. Choose reject or prune_oldest as the definition's version-limit policy through the dashboard or the MCP create/update tools. In the dashboard you can also inspect an inactive version or delete one to free a slot. See Plans & Limits for the current allowances.

Ownership and sharing

An agent definition can belong to your personal space, your personal space inside an organization, a team, or the organization. Its visibility follows the same ownership and access model as the rest of the platform: team-bound credentials can use eligible team and organization definitions, while a member credential can also use that member's personal-in-organization definitions. See Organizations & Teams and the Access Model.

Audit definitions

Use the platform prompt apistash/agent-doctor to have your connected model inspect visible definitions and their relationships. It checks the active version returned by each read, including conditional components. Separate reads are not an atomic snapshot: updates or renames during the audit can affect its evidence.

Inspection does not select a Bootstrap role or replace the independent Bootstrap discovery catalog. The Doctor keeps your current role, treats definitions as evidence, and proposes changes in its report without applying them.

Related reference

• bootstrap — selection states and the task-start response
• agent_context — loading conditional behavior from the current active definition
• Agent management tools — discover, inspect, create, update, and delete definitions over MCP
• Authentication — Agents capabilities, assignment, and per-credential policy