AI Agents Builder

What It Is

AI Agents Builder is the tenant administration surface for configuring the agents available in Jetstack embedded chat. Each configured agent defines:

  • which model provider and model should be used
  • which dedicated Jetstack user identity the agent should act as
  • which workspace tools the agent may access
  • whether the agent may work with application-model management
  • which human users may see the agent in chat
  • what system prompt should govern the agent’s behavior

This is not just a prompt editor. It is the control point where AI behavior, permissions, visibility, and operational risk are shaped together.

Why It Matters

AI agents in Jetstack are governed tenant capabilities, not anonymous assistants. The way you configure an agent determines:

  • what the model can see
  • what it can change
  • whether it is read-only, action-oriented, or app-building
  • who in the tenant may use it
  • how much provider-side capability it receives

Good agent design therefore combines prompt design, permission design, and integration design.

How To Read This Chapter

This chapter covers:

  • how AI agents work in Jetstack
  • how to think about agent purpose
  • what each configuration option means
  • how the builder-level controls affect runtime behavior
  • what the common design patterns are for general agents and app-builder agents

Use this together with:

Mental Model

An AI agent in Jetstack is a combination of five layers:

  1. A visible chat persona for human users.
  2. A dedicated Jetstack user identity that defines the hard permission boundary.
  3. An MCP tool and resource scope derived from that user and further narrowed by agent configuration.
  4. A provider and model configuration used by the AI sidecar.
  5. A system prompt that tells the model how to behave.

This means an agent is never defined by prompt alone. The prompt tells the model what role to play, but the user identity, allowed tools, and model-management settings decide what it is actually capable of doing.

Agent Purpose: General Agent Versus App Builder

Jetstack does not have a separate purpose field such as general or app_builder.

Instead, purpose is composed from the configuration. In practice, the two most important patterns are a general workspace agent and an app-builder agent.

General agent

A general agent is the normal business assistant pattern.

Typical characteristics:

  • model_management_enabled is off
  • the prompt focuses on business work, analysis, navigation, follow-up, support, finance, or operations
  • the dedicated agent user has business-facing tenant permissions, not schema-management permissions
  • allowed_tools usually contains a narrow set of workspace tools
  • write_policy is often confirm for safety, or auto for tightly controlled operational agents

Use this when the agent should:

  • answer questions about data
  • summarize current state
  • create routine follow-up work
  • update business records
  • help users inside the existing application

App-builder agent

An app-builder agent is the model-management pattern.

Typical characteristics:

  • model_management_enabled is on
  • the dedicated agent user has enough rights to inspect and change the application model
  • the system prompt is written for schema design, model discovery, and controlled implementation work
  • the visible audience is usually limited to implementers or administrators
  • allowed_tools is carefully curated, because this agent can affect the application structure

When model management is enabled, Jetstack extends the agent’s MCP environment with model-related tools, resources, and prompts, but only if the dedicated agent user is actually allowed to use them.

Use this when the agent should:

  • inspect the current application model
  • propose or implement types and properties
  • help reshape data structures
  • work as an implementation assistant rather than a normal business assistant

Important distinction

Turning on model_management_enabled does not magically make an agent an app builder. It only requests model-management capability. The final result still depends on the dedicated agent user and its permissions.

In other words:

  • the prompt defines intended purpose
  • the dedicated user defines the hard permission boundary
  • model_management_enabled requests app-builder capability
  • allowed_tools narrows the operational surface
  • write_policy defines how write-capable actions are presented or executed

Agent Lifecycle In The Builder

The AI Agents screen supports more than just editing fields. It also manages the lifecycle of the configured agent list.

New draft

The builder always offers a draft slot for creating a new agent definition before saving it into the tenant configuration.

Save

Saving writes the normalized agent definition into tenant configuration. The agent then becomes part of the configured agent set used by embedded chat.

Enable and disable

You can toggle an agent without deleting it. Disabled agents stay configured but do not appear as available runtime agents.

Duplicate

Duplication creates a copy of an existing agent. This is useful when creating variants for different departments, providers, or permission scopes.

Move up and move down

The configured order is meaningful. The builder preserves agent order, and that order is the natural list order seen in the management surface and fed into the visible configured set.

Delete

Deleting removes the agent definition from tenant configuration.

Configuration Options

enabled

What it is

The activation switch of the agent.

Why it matters

It determines whether the agent is available to embedded chat users at all.

How to configure it

  • Enable the Enable this agent switch when the agent should be available.
  • Disable it to keep the definition stored without exposing it at runtime.

How it behaves

  • Disabled agents remain configured.
  • Disabled agents are skipped when Jetstack builds the visible agent list for users.

When to use it

  • staged rollout
  • temporary suspension
  • keeping draft-like variants without exposing them

name

What it is

The human-readable agent label.

Why it matters

This is the primary display name shown in the builder and chat-related agent listings.

How to configure it

  • Enter a clear business-facing name in Agent name.
  • Name the agent by role, not by model.

Good examples

  • Workspace Assistant
  • Finance Operations
  • Support Triage
  • Application Builder

Best practice

Prefer names that explain business purpose. Model choice may change later, but the agent’s function should remain understandable.

id

What it is

The system identifier of the agent.

Why it matters

The ID is the stable internal identifier used when selecting the agent at runtime.

How to configure it

  • Enter a lowercase system ID using letters, numbers, _, and -.
  • If you leave it empty, Jetstack generates it from the name.
  • IDs must be unique across all configured agents.

How it behaves

  • The ID is normalized and validated.
  • Duplicate IDs are rejected.
  • If an ID is omitted but the name exists, Jetstack derives the ID from the name.

Example

  • workspace_assistant
  • finance_ops
  • application_builder

Best practice

Choose a stable ID early and avoid changing it casually once external references or user habits depend on the agent.

provider

What it is

The AI provider used for this agent.

Why it matters

Provider choice affects:

  • which models are available
  • which provider-hosted tools may be offered
  • how the sidecar communicates with the model backend

How to configure it

  • Select one supported provider from the list.
  • The available providers come from the tenant’s provider catalog.

Current behavior

The platform currently exposes provider options from the configured provider catalog, for example OpenAI, Anthropic, and Gemini.

Best practice

Choose the provider based on:

  • required model family
  • needed provider-hosted tools
  • operational policy and cost expectations

model

What it is

The specific model ID used for the agent.

Why it matters

The model influences quality, speed, reasoning support, and provider-specific tool behavior.

How to configure it

  • Select a model suggested for the chosen provider.
  • The form refreshes model choices according to the selected provider.
  • The runtime also accepts provider model IDs beyond the friendly label list as long as the provider can resolve them.

How it behaves

  • Jetstack normalizes provider-specific aliases to canonical model IDs where known.
  • If the selected provider changes, the builder resolves the model again against that provider.

Best practice

  • Use a smaller, cheaper model for routine agents.
  • Use a stronger model for app-building, planning, or high-ambiguity work.
  • Keep model selection aligned with the agent’s actual job instead of defaulting every agent to the strongest available model.

reasoning_effort

What it is

An optional reasoning override for models that support reasoning-effort levels.

Why it matters

It lets you increase or reduce the depth of reasoning requested from the model.

How to configure it

  • Choose Use model default to inherit the model’s default behavior.
  • Or choose one supported level such as minimal, low, medium, or high.

How it behaves

  • Jetstack only keeps the override if the chosen model supports that reasoning level.
  • If the override is invalid for the current model, it is ignored.
  • If no explicit override is set, Jetstack may still use the model’s default reasoning setting if one exists.

When to use it

  • Lower settings for simple high-volume assistants.
  • Higher settings for complex analysis or implementation guidance.

Best practice

Leave this at model default unless you have a clear reason to tune it.

write_policy

What it is

The policy controlling how write-capable or action-capable capabilities are executed.

Why it matters

This is one of the main safety controls of the agent.

How to configure it

  • Choose Auto-run writes when the agent should execute allowed write actions immediately.
  • Choose Require approval when write-capable actions should return as approval-required instead of executing immediately.

How it behaves

  • Read capability always remains available.
  • This setting mainly affects write and action operations.
  • It does not expand permissions. It only changes how allowed writes are handled.

General guidance

  • For general assistants, confirm is usually the safer default.
  • For tightly scoped operational agents, auto can be appropriate.
  • For app-builder agents, confirm is usually the better starting point unless you are deliberately building a trusted implementation assistant.

api_key_ref

What it is

The Secrets Manager reference to the provider API key for this agent.

Why it matters

It is the preferred way to assign provider credentials without embedding them directly into normal tenant configuration.

How to configure it

  • Create the provider credential in Secret Store.
  • Select that secret in Provider API key secret.
  • Leave it empty only if you intentionally want the sidecar’s environment-level fallback key to be used.

How it behaves

  • If a secret is selected, the sidecar resolves the provider key from that secret.
  • If the referenced secret no longer exists, the agent becomes invalid.

Best practice

  • Use a dedicated secret for important agents.
  • Avoid relying on sidecar fallback credentials in production unless that is an intentional infrastructure policy.

provider_tools

What it is

Optional provider-hosted tools exposed directly by the selected model provider.

Why it matters

These tools are separate from Jetstack MCP tools. They represent provider-native capabilities such as hosted image generation or code execution.

How to configure it

  • Select one or more provider tools from the list shown for the selected provider.
  • The available options depend on the provider.

How it behaves

  • The option list changes with the provider.
  • Unsupported provider tools are rejected.
  • These tools are additive provider capabilities, not tenant permission grants.

Examples

  • OpenAI may expose image_generation or code_interpreter.
  • Anthropic may expose code_execution.
  • Some providers may expose no provider tools at all.

Best practice

Enable provider tools only when the agent really needs them. Do not turn them on by default just because they are available.

agent_user_id

What it is

The dedicated Jetstack user identity used by the agent.

Why it matters

This is one of the most important settings in the whole builder. The dedicated user defines the hard boundary for what the agent may do in Jetstack.

How to configure it

  • Create a dedicated non-human user in Users.
  • Assign only the required roles.
  • Optionally place it in a dedicated group such as Application access or AI agents.
  • Select that user in Dedicated app user.

How it behaves

  • The agent runs through this user identity.
  • Jetstack derives MCP access from this user’s permissions.
  • Object changes remain attributable to this acting identity.
  • If the user cannot be resolved, the agent is not valid for runtime use.

Best practice

Always use a dedicated application user. Do not point production agents at a human administrator account.

promptTemplate

What it is

A builder helper for applying a predefined system-prompt starting point.

Why it matters

It speeds up agent creation by giving you a strong role-based baseline prompt.

How to configure it

  • Choose one of the built-in prompt templates.
  • Apply it into the system_prompt field.
  • Then tailor the resulting prompt for your tenant.

How it behaves

  • This control does not store separate runtime state by itself.
  • It is an authoring aid that writes prompt content into system_prompt.

Current prompt-template direction

The platform includes templates such as:

  • workspace assistant
  • read-only analyst
  • project coordinator
  • client success assistant
  • support triage agent
  • operations executor
  • finance operations assistant

Best practice

Use prompt templates as starting points, not as final production prompts.

system_prompt

What it is

The main behavioral instruction set for the agent.

Why it matters

The system prompt defines:

  • the agent’s role
  • tone
  • decision style
  • safety expectations
  • escalation behavior
  • how to use tools

This is the main place where the intended purpose of the agent is expressed.

How to configure it

  • Write a prompt that explains what the agent is for.
  • Define what it should prioritize.
  • State whether it may act, analyze only, or require clarification before changes.
  • Align the prompt with the real permissions of the dedicated user.

How it behaves

  • The prompt is passed into the runtime session payload.
  • If model management is enabled, Jetstack appends additional model-management guidance to the effective system prompt.

Best practice

  • Keep prompts operational and concrete.
  • Do not describe powers the agent does not actually have.
  • For app-builder agents, explicitly instruct the agent to inspect the current model first and to prefer deliberate schema changes.

model_management_enabled

What it is

A switch that requests application-model management capability for the agent.

Why it matters

This is the main configuration difference between a general business agent and an app-builder agent.

How to configure it

  • Turn this on when the agent should inspect and change the application model.
  • Keep it off for normal business assistants working only inside the existing app.

How it behaves

  • When enabled, Jetstack tries to extend the agent scope with model-management MCP tools, resources, and prompts.
  • Jetstack also appends special model-management guidance to the effective system prompt.
  • The final capability still depends on what the dedicated agent user is actually allowed to do.

Important warning

This setting is a request, not a guarantee. If the dedicated user lacks the necessary permissions, model-management capability will be partial or absent.

Best practice

  • Turn this on only for implementation-oriented agents.
  • Pair it with a carefully designed dedicated agent user and narrow audience visibility.

allowed_tools

What it is

The explicit allow-list of Jetstack MCP tools the agent may use.

Why it matters

This is the main scope-narrowing control after the dedicated user identity.

How to configure it

  • Select the tools the agent should be able to call.
  • The option list is derived from the dedicated user’s permissions and whether model management is enabled.
  • You can also keep previously stored tool names when refining an agent over time.

How it behaves

  • If the list is empty, the agent receives all MCP tools available to its dedicated user identity.
  • If the list is populated, the runtime intersects the agent’s tool scope with that selected subset.
  • When model management is enabled and the user is allowed to manage the model, Jetstack also includes the model tool family required for that scope.

Best practice

  • Treat empty as wide-open within the agent identity.
  • For production agents, prefer explicit scoping.
  • For app-builder agents, include only the model and workspace tools the agent truly needs.

visible_to_human_roles

What it is

The role-based visibility filter for who may see the agent in embedded chat.

Why it matters

Not every agent should be visible to every authenticated human user.

How to configure it

  • Select one or more human roles.
  • Leave it empty for no role-based restriction.

How it behaves

  • If empty, role membership does not restrict visibility.
  • If populated, the human user must have at least one matching role to see the agent.

When to use it

  • department-specific assistants
  • implementer-only app-builder agents
  • manager-only strategy assistants

visible_to_human_users

What it is

The user-specific visibility filter for who may see the agent in embedded chat.

Why it matters

It allows targeted rollout to named individuals without introducing a separate role.

How to configure it

  • Select one or more specific human users.
  • Leave it empty for no user-specific restriction.

How it behaves

  • If empty, user-specific visibility is not restricted.
  • If populated, only the listed users may see the agent.

Best practice

  • Use this for pilot rollout, testing, or executive-only assistants.
  • Prefer role-based visibility for larger stable audiences.

How The Main Options Work Together

The most important design combinations are:

Business assistant pattern

  • model_management_enabled: off
  • agent_user_id: dedicated business-facing application user
  • allowed_tools: read and routine action tools only
  • write_policy: usually confirm
  • visible_to_human_roles: scoped to the intended audience
  • system_prompt: operational, concise, business-specific

Read-only analyst pattern

  • model_management_enabled: off
  • allowed_tools: read-only or narrow analytical set
  • write_policy: confirm
  • system_prompt: explicitly forbids side effects

Operations executor pattern

  • model_management_enabled: off
  • allowed_tools: tightly bounded write tools
  • write_policy: often auto
  • system_prompt: explicit, procedural, and conservative

App-builder pattern

  • model_management_enabled: on
  • agent_user_id: dedicated implementation user with model permissions
  • allowed_tools: curated model-management and workspace set
  • write_policy: usually confirm
  • visible_to_human_roles: implementers or administrators only
  • system_prompt: implementation-oriented and schema-aware

Validation And Failure Modes

An agent becomes invalid when key configuration requirements are not met.

Common reasons include:

  • missing or duplicate id
  • missing name
  • unsupported provider
  • missing model
  • unsupported provider tools
  • missing or invalid agent_user_id
  • missing secret referenced by api_key_ref

The builder surfaces invalid configurations so they can be fixed before relying on the agent.

Best Practices

  • Create one dedicated application user per meaningful agent or agent family.
  • Name agents by business purpose, not by model marketing name.
  • Keep allowed_tools explicit for production agents.
  • Use visible_to_human_roles and visible_to_human_users to keep specialized agents out of broad circulation.
  • Keep model_management_enabled off unless the agent is intentionally an implementation assistant.
  • Treat app-builder agents as higher-risk tools and scope them tightly.
  • Store provider credentials in Secret Store, not in ad hoc notes or config fields elsewhere.
Previous← IntroductionNextAi Sidecar →