AI settings in Katalon Studio
Use this guide to configure AI keys and test case tags under AI Configuration, customize Katalon AI Assistant, and control AI capabilities for a project.
- A license that includes AI features. With a Free license, the AI pages show an upgrade screen.
- To use the Katalon AI key or the organization key, sign in to Katalon Studio with SSO. Your account admin decides which AI keys Katalon Studio can use.
AI Configuration
In Katalon Studio, go to Katalon Studio > Settings > Katalon > AI Configuration.
For OpenAI compatibility information, refer to OpenAI Supported Models.
Check or change your AI key source
- Katalon Studio version 11.7.0 onwards.
The AI key source group always lists three sources. Your account admin decides which ones are available. When only one source is allowed, it is selected and the others are disabled; you cannot switch sources in Katalon Studio. When more than one source is enabled, select the one you want to use. To change which sources are available, ask your account admin to update how Katalon uses AI keys.
| Source | What it is |
|---|---|
| Katalon AI key | Katalon's own managed key. You do not need to set anything up in Katalon Studio. |
| Organization key | The key your admin configured for your account or organization in True Platform. No setup in Katalon Studio is needed. |
| Personal AI key | Your own key for OpenAI, Azure OpenAI, Gemini, an OpenAI-compatible provider, or AWS Bedrock, entered in Katalon Studio. |
When a managed key and Personal AI key are both available, the managed key is the default. If only personal keys are available, add your own key.
When you are not signed in with SSO, for example with an offline license or an on-premise sign-in, no admin settings apply. You can use a personal AI key only, and the page shows: Katalon AI key and organization key need a True Platform sign-in. Studio uses personal AI keys.
If you select Personal AI key without entering one, Katalon Studio keeps using the managed key when available. Your personal key settings remain saved when you switch sources or your admin stops allowing personal keys, but Katalon Studio uses them only while personal keys are allowed. The chat box shows the key source in use.
The supported models for each source:
| AI key source | Supported model | Notes |
|---|---|---|
| Katalon AI key | gpt-5.6-luna for all features: Agent mode, Web Recording Agent, AI self-healing, Ask mode, Generate and Explain code in the script editor, and AI failure reason analysis in HTML, PDF and email reports. | Built-in; no configuration needed. Supports multilingual inputs. |
| Organization key | The provider and model your admin set on True Platform. | No configuration in Katalon Studio. |
| Personal OpenAI |
| Supports multilingual inputs. |
| Azure OpenAI | User-specified deployment Tested with:
| Requires specifying the deployment name in configuration. Notes: Some older API versions do not support tool calls in Agent mode. |
| Gemini |
| URL points to the latest supported version of the Google Generative Language API. |
| OpenAI-Compatible Provider |
| API key passed via the Authorization HTTP header. |
| AWS Bedrock |
| Requires credential-based authentication configuration. |
Click on the tab below to find more information about each AI key source.
- Katalon AI key
- Organization key
- Personal AI key
When selected, there is no need to set up a key for the Katalon AI key.
The Organization key is available when your admin set Katalon Studio to use the organization's AI key on True Platform. Your admin manages the provider, model, and key there. Katalon Studio has nothing to configure for this source and never receives the key.
Select Personal AI key to use your own OpenAI key, Azure OpenAI API key, Gemini API key, OpenAI-compatible provider, or AWS Bedrock key. This source is available when your admin allows personal keys, or when you are not signed in with SSO.
Katalon Studio removes leading and trailing spaces and line breaks from the values you enter, so a pasted key or token with extra whitespace still works.
- Select a Provider and provide its configuration.
-
Use personal OpenAI key: Provide the following information before using:
- Secret key: To get your Secret key, refer to the provider's instruction: Where do I find my secret key?.
- Max completion token: The default value that sets the maximum number of tokens the model can return in its response. The default value is 16000. To learn more about the token limits, refer to the OpenAI rate limits documentation: OpenAI Token Limits.
- Organization ID (optional): The organization ID on OpenAI is the unique identifier for your organization which can be used in API requests.
- Model: The OpenAI model you want to use. If not changed, the
gpt-4o-minimodel is used by default.
-
Use personal Azure OpenAI API key: Provide the following information before using:
- Base URL: The base URL for your Azure OpenAI resource in the following format:
https://{your-resource-name}.openai.azure.com. - Deployment name: Azure OpenAI uses the deployment name to call the model. Enter the deployment name of your choosing, make sure that the model supports chat completion.
- API key: To get your Azure OpenAI key, refer to this article: How to get Azure OpenAI Keys and Endpoint
- Max completion token: The default value that sets the maximum number of tokens the model can return in its response. The default value is 16000.
- API version: API version is selected for you by default.
- Base URL: The base URL for your Azure OpenAI resource in the following format:
-
Use Gemini API key: Provide the following information before using:
- Base URL: The base URL used to connect to the Gemini API service. This URL should point to the correct version of the Google Generative Language API.
- API key: Your Gemini key. Create a key for free in Google AI Studio.
- Model: The Gemini model you want to use. If not, Katalon AI Assistant will use the latest supported version of the Google Generative Language API by default.
- Max completion token: The default value that sets the maximum number of tokens the model can return in its response.
-
Use Open-AI compatible provider: Provide the following information before using:
- Base URL: The API endpoint for your OpenAI-compatible service.
- API key: Your API key.
- API key header name: The name of the HTTP header where the API key is passed (commonly
Authorization). This allows support for providers with different header naming conventions. - Model: The model you want to use. If not changed, the
gpt-4.1-minimodel is used by default. - Max completion token: The default value that sets the maximum number of tokens the model can return in its response.
-
Use personal AWS Bedrock key: Provide the following information before using:
- AWS access key: Your AWS access key ID. To learn how to create one, see Managing access keys for IAM users.
- AWS secret key: The secret key paired with your access key ID for authentication. You can only view it once when creating the key pair.
- AWS session token: A temporary security credential provided by AWS Security Token Service (STS). Required only if you use temporary credentials, such as those from assuming an IAM role or MFA authentication. For details, see
GetSessionToken. - AWS region: The AWS region where your Bedrock model is available.
- Model: The model ID in your AWS Bedrock account. See Supported foundation models in Amazon Bedrock.
- Max completion token: Sets the maximum number of tokens the model can return in its response. The default value is 16000.
noteKatalon Studio currently does not support proxy connections for AWS Bedrock.
-
Tag test cases created with AI
In AI Configuration, you can configure AI-generated test case tags regardless of which AI key source you use. Under Append tags for test cases used AI capabilities, select the features whose generated test cases you want to tag:
| Feature | Default tag |
|---|---|
| API Test Case Generation | API_Test_Generation |
| Katalon AI Assistant Code Generation | GenAI |
| Web Recording Agent | webRecordingAgent |
For each feature, use its default tag or select Custom tag and enter a name. Test cases with AI-generated tags are highlighted in green in the Test Explorer.
Turn AI features on or off in Katalon Studio
- Katalon Studio version 11.7.0 onwards.
Enable AI features in Katalon Studio is selected by default. Clear it if you do not want to use AI features in Katalon Studio. This replaces selecting None as the AI provider in earlier versions.
When you clear it:
- The key sources, AI tagging options, and Web Recording Agent options are disabled but keep their values. The page shows:
AI features are hidden in Studio. Your key choice is kept and comes back when you turn AI on again. - AI features show
AI features are turned off in Katalon Studio.with an Open AI settings button that opens this page.
The checkbox is cleared and disabled while AI is unavailable for the whole of Katalon Studio, for example when your admin turned AI off or the AI settings could not be loaded. This preference applies to Katalon Studio only. Katalon Runtime Engine follows the project's AI Capabilities settings by default and any command-line overrides, subject to your admin's AI settings. See AI execution arguments.
When AI is unavailable
- Katalon Studio version 11.7.0 onwards.
When an AI feature cannot run, Katalon Studio shows the reason in the chat or AI dialog. If AI is unavailable throughout Katalon Studio, the reason also appears at the top of AI Configuration.
| Reason | What to do |
|---|---|
| Your admin turned off AI, the required key source, or a specific feature | Use Request access. |
| You turned off Enable AI features in Katalon Studio | Use Open AI settings to turn it back on. |
| A personal key is required but none is configured | Use Add your API key. |
| Katalon Studio could not load the admin settings | Sign in again. |
| Your license does not include Katalon AI and personal keys are not allowed | You cannot use AI with the current license and admin settings. |
If more than one reason applies, Katalon Studio shows the admin-controlled reason first.
When a feature is unavailable, it behaves as follows:
- Chat, code generation, code explanation, and API test generation show the reason and any available action.
- Web Recording Agent records without the agent. Its saved toggle choice returns when the agent is available again.
- AI self-healing is skipped and logs the reason; LLM keywords fail the step with the reason; reports omit AI failure analysis.
- Katalon Studio MCP Server does not start when the admin turns it or AI overall off. It remains available when only an AI key source is missing, because the server does not use that key.
Your admin can turn off Katalon AI Assistant chat, code generation or explanation, AI failure analysis, AI self-healing, the Web Recording Agent, API test generation, AI keywords, or the Katalon Studio MCP Server. AI Configuration lists the features your admin turned off.
When Katalon Studio is not signed in with SSO, admin feature restrictions do not apply. Your local and project AI settings still control which features run.
Katalon Studio reads your admin's AI settings when it starts, when you sign in, and when your license is activated or reactivated. After your admin changes them, restart Katalon Studio or sign in again.
Katalon AI Assistant
These preferences apply regardless of which AI key source you use. In Katalon Studio, go to Katalon Studio > Settings > Katalon > Katalon AI Assistant to include project context, suggest follow-up questions, and display the agent's reasoning in chat. Reasoning is available only for models that support it.
Auto-include project context information
Select Object repository, Custom keywords, or both to include that project context in Katalon AI Assistant's Ask mode, Generate Code, and Explain Code. Agent mode can access project context through Katalon's built-in MCP tools.
These options help Katalon AI Assistant use test objects and custom keywords without requiring you to specify them in each prompt.
Auto-suggest follow-up questions in the chat
- Katalon Studio version
11.7.0onwards for follow-up questions in Agent mode.
When enabled, Katalon AI Assistant automatically suggests follow-up questions after providing a successful answer. This gives you control over your chat experience, whether you prefer guided suggestions or a more minimal interface. The feature works in both Ask mode and Agent mode. In Agent mode, the suggestions appear after the agent finishes its task. If the agent stops or fails, no suggestions appear.
Display the agent's reasoning inline in chat
- Katalon Studio version 11.4.0 onwards.
When enabled, Agent mode shows the model's reasoning inline in the chat as it works. Each turn displays a thinking note above the tool calls that turn triggers. This option is enabled by default and applies to Agent mode only. Ask mode streams the answer without a thinking note.
Use Reasoning effort to control how much reasoning the model does before it answers:
| Level | How it works |
|---|---|
| Low | The model reasons briefly. Use this level for straightforward tasks and the fastest responses. |
| Medium | The default level. Balances reasoning depth against response time. |
| High | The model reasons more thoroughly before answering. Use this level for complex tasks that involve several tools or files, and expect longer responses. |
When you clear Display the agent's reasoning inline in chat, the Reasoning effort list is disabled, and Agent mode no longer requests or displays reasoning.
- Reasoning is available only for models that support it. If your selected model does not support reasoning, Katalon AI Assistant answers without it instead of returning an error, and skips reasoning for that model for the rest of the session.
- The model spends part of its output budget on reasoning. If a response stops before the answer is complete, lower Reasoning effort or raise Max completion token for your provider, then try again.
For details on how reasoning appears in a conversation, see Follow the agent's reasoning.
Customize engineering prompts with Prompt Library
Customize your engineering prompts using Prompt Library to provide more context and improve the accuracy of Katalon AI Assistant responses. This works for both Ask mode and Agent mode.
- Click Katalon Studio on the main navigation and select Settings to open the Preferences dialog.
- Select Katalon > Katalon AI Assistant > Prompt Library.
- Configure your Prompt Library. Click on the prompt type you want to customize. Edit this text directly to include more context or specific instructions about how you want the AI to respond.
- Ask mode: Used in the Katalon AI Assistant Ask mode. This controls how Katalon AI Assistant responds to your general questions or guidance requests in Ask mode conversations. Add more context about your application under test (AUT) or focus area, so you don’t have to repeat this every time you start a new Ask mode chat.
- Agent mode: Used in Agent mode conversations. This defines the agent's behavior, tool priorities, and response patterns for Agent mode and Agent Profile conversations. You can customize this prompt to match your workflow, team conventions, or testing methods, for example, setting tool priority. Changes take effect right away and are saved across restarts. You can click Revert Original or leave the prompt empty to use the default prompt from Katalon AI Assistant system.
- Generate code: Used in the script editor, add style guide details or coding preferences to make the generated code better fit your project.
- Explain code: Used in the script editor, specify if you want detailed technical explanations or a high-level summary, depending on your needs.
- Analyze test failure: Used to customize the system prompt for AI Failure Analysis. This defines how Katalon AI Assistant interprets failure logs and generates analysis results.
- Click Apply or Apply and Close to save.
You can now use Katalon AI Assistant with your customized prompts. If the generated output is not to your expectation, simply open the Prompt Library and select Revert Original to revert each prompt or click Restore to Defaults to restore all prompts.
- Use
${userSelection}for Generate code and Explain code. This variable represents the specific piece of text or code you have highlighted (selected) in the script editor. - Customize prompt is not applied for Katalon AI service.
Project AI capabilities
Turn AI capabilities on or off for a project
- Katalon Studio version 11.7.0 onwards.
- A Katalon Studio license that includes AI failure reason analysis or AI self-healing.
Each project has one switch, Enable AI capabilities for this project, that turns on or off every project-level AI feature: AI failure reason analysis in reports and AI self-healing during test runs. Each feature also keeps its own setting.
- Go to Project > Settings > AI Capabilities. AI Capabilities is the first item in the Project Settings tree.
- Select or clear Enable AI capabilities for this project.
- Click Apply and Close.
To set this option when creating a project, see Create a test project in Katalon Studio.
When you clear the switch:
- Katalon Studio and Katalon Runtime Engine run no AI failure reason analysis (HTML, PDF and email reports) and no AI self-healing for this project, unless a Katalon Runtime Engine command-line argument turns a feature on.
- The feature options on the page are disabled but keep their values. When you select the switch again, each feature returns to its previous value.
For Katalon Runtime Engine command-line overrides, see Turn AI failure analysis on or off and AI self-healing.
Choose the AI features for a project
Under the switch, the AI Capabilities page holds every project-level AI option:
- AI failure reason analysis: select the outputs that show the AI analysis: HTML report, PDF report and Email report. See AI Failure Analysis in Reports.
- AI self-healing: select Web UI, Mobile, or both, and the input data sources the AI uses. See Configure AI Self-healing.
The page also links to the Report, Email and Self-healing pages, where you still choose which reports to generate and how locator-based self-healing works.
By default, every option is selected except the Accessibility tree data source for Web UI.
Some configuration checkboxes may be unavailable in the following cases:
- No usable AI key is available: the switch is cleared and disabled, and the page shows
No AI provider is set up. Set up AI in Preferences. Click Set up AI in Preferences to check which key sources are available to you. See Check or change your AI key source and When AI is unavailable. - Free license: the switch appears cleared. Clicking it opens an upgrade dialog, and nothing is saved.
AI settings in existing projects
Projects created before Katalon Studio 11.7.0 keep their AI feature settings. The settings previously found under Report, Email, Self-healing > Web UI, and Self-healing > Mobile are now under AI Capabilities. Availability still depends on your AI provider and license.