AI Agents Builder is the tenant administration surface for configuring the agents available in Jetstack embedded chat. Each configured agent defines:
This is not just a prompt editor. It is the control point where AI behavior, permissions, visibility, and operational risk are shaped together.
AI agents in Jetstack are governed tenant capabilities, not anonymous assistants. The way you configure an agent determines:
Good agent design therefore combines prompt design, permission design, and integration design.
This chapter covers:
Use this together with:
An AI agent in Jetstack is a combination of five layers:
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.
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.
A general agent is the normal business assistant pattern.
Typical characteristics:
model_management_enabled is offallowed_tools usually contains a narrow set of workspace toolswrite_policy is often confirm for safety, or auto for tightly controlled operational agentsUse this when the agent should:
An app-builder agent is the model-management pattern.
Typical characteristics:
model_management_enabled is onallowed_tools is carefully curated, because this agent can affect the application structureWhen 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:
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:
model_management_enabled requests app-builder capabilityallowed_tools narrows the operational surfacewrite_policy defines how write-capable actions are presented or executedThe AI Agents screen supports more than just editing fields. It also manages the lifecycle of the configured agent list.
The builder always offers a draft slot for creating a new agent definition before saving it into the tenant configuration.
Saving writes the normalized agent definition into tenant configuration. The agent then becomes part of the configured agent set used by embedded chat.
You can toggle an agent without deleting it. Disabled agents stay configured but do not appear as available runtime agents.
Duplication creates a copy of an existing agent. This is useful when creating variants for different departments, providers, or permission scopes.
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.
Deleting removes the agent definition from tenant configuration.
enabledWhat 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 this agent switch when the agent should be available.How it behaves
When to use it
nameWhat 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
Agent name.Good examples
Workspace AssistantFinance OperationsSupport TriageApplication BuilderBest practice
Prefer names that explain business purpose. Model choice may change later, but the agent’s function should remain understandable.
idWhat 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
_, and -.How it behaves
Example
workspace_assistantfinance_opsapplication_builderBest practice
Choose a stable ID early and avoid changing it casually once external references or user habits depend on the agent.
providerWhat it is
The AI provider used for this agent.
Why it matters
Provider choice affects:
How to configure it
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:
modelWhat 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
How it behaves
Best practice
reasoning_effortWhat 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
Use model default to inherit the model’s default behavior.minimal, low, medium, or high.How it behaves
When to use it
Best practice
Leave this at model default unless you have a clear reason to tune it.
write_policyWhat 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
Auto-run writes when the agent should execute allowed write actions immediately.Require approval when write-capable actions should return as approval-required instead of executing immediately.How it behaves
General guidance
confirm is usually the safer default.auto can be appropriate.confirm is usually the better starting point unless you are deliberately building a trusted implementation assistant.api_key_refWhat 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
Provider API key secret.How it behaves
Best practice
provider_toolsWhat 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
How it behaves
Examples
image_generation or code_interpreter.code_execution.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_idWhat 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
Application access or AI agents.Dedicated app user.How it behaves
Best practice
Always use a dedicated application user. Do not point production agents at a human administrator account.
promptTemplateWhat 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
system_prompt field.How it behaves
system_prompt.Current prompt-template direction
The platform includes templates such as:
Best practice
Use prompt templates as starting points, not as final production prompts.
system_promptWhat it is
The main behavioral instruction set for the agent.
Why it matters
The system prompt defines:
This is the main place where the intended purpose of the agent is expressed.
How to configure it
How it behaves
Best practice
model_management_enabledWhat 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
How it behaves
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
allowed_toolsWhat 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
How it behaves
Best practice
visible_to_human_rolesWhat 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
How it behaves
When to use it
visible_to_human_usersWhat 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
How it behaves
Best practice
The most important design combinations are:
model_management_enabled: offagent_user_id: dedicated business-facing application userallowed_tools: read and routine action tools onlywrite_policy: usually confirmvisible_to_human_roles: scoped to the intended audiencesystem_prompt: operational, concise, business-specificmodel_management_enabled: offallowed_tools: read-only or narrow analytical setwrite_policy: confirmsystem_prompt: explicitly forbids side effectsmodel_management_enabled: offallowed_tools: tightly bounded write toolswrite_policy: often autosystem_prompt: explicit, procedural, and conservativemodel_management_enabled: onagent_user_id: dedicated implementation user with model permissionsallowed_tools: curated model-management and workspace setwrite_policy: usually confirmvisible_to_human_roles: implementers or administrators onlysystem_prompt: implementation-oriented and schema-awareAn agent becomes invalid when key configuration requirements are not met.
Common reasons include:
idnameprovidermodelagent_user_idapi_key_refThe builder surfaces invalid configurations so they can be fixed before relying on the agent.
allowed_tools explicit for production agents.visible_to_human_roles and visible_to_human_users to keep specialized agents out of broad circulation.model_management_enabled off unless the agent is intentionally an implementation assistant.