Creating Custom Agents
In addition to the built-in K2View agents, Studio AI lets you create your own agents. A custom agent has a name, a focused purpose, and a prompt you write. Once created, it appears in the chat alongside the built-in agents and can be addressed with @AgentName like any other.
Custom agents are useful when you have a repeated workflow that none of the built-in agents covers well: an agent specialized in a specific LU, a coding style enforcer, or an agent that always injects a particular set of project context.
Creating a Custom Agent
- Open the AI Configuration panel: click More Actions… ("…") in the AI Chat panel toolbar, then Open AI Configuration. See Using the AI Chat.
- Select the Agents category.
- Click Add Custom Agent.
- Fill in the agent definition fields (described below).
- Click Save.
The new agent is immediately available in the AI Chat.
Agent Definition Fields
| Field | Required | Description |
|---|---|---|
| ID | Yes | A unique identifier used internally. Use lowercase with hyphens (e.g., my-agent). Must not conflict with existing agent IDs. k2-assistant and k2-worker are reserved for the built-in agents: agent definitions under .agents/agents/ with either ID are ignored. |
| Name | Yes | The display name shown in the chat and in AI Configuration. This is also the @Name used to address the agent in the chat. |
| Description | Yes | A one-line summary of what the agent does. Appears in the agent list and on the AI Chat welcome screen. |
| Prompt | Yes | The system prompt that defines the agent's behavior, persona, and knowledge. Supports {{variable}} and ~{function} syntax. See Customizing Agent Prompts. |
| Default LLM | No | The model or model alias the agent uses. If omitted, the agent uses the workspace default. |
Where Custom Agents Are Stored
Custom agents are stored as files in the project workspace:
.agents/agents/<id>/agent.html- the default location for new agents..prompts/agents/<id>/agent.html- an older location, still read for backward compatibility. Older projects may also define agents in a.prompts/customAgents.ymlfile.
Because these files are part of the project, an agent is available to everyone working on the project, and can be versioned in Git with the rest of the project.
Studio AI does not load custom agents from the user's home folder: there is no user-level (~/.agents/agents/) agent location that spans workspaces. This differs from skills, which are also read from ~/.agents/skills (see AI Features Settings). To reuse an agent in another project, copy its folder into that project's .agents/agents/.
Writing an Effective Custom Agent Prompt
The prompt is the most important part of a custom agent. A few guidelines:
Start with identity and scope. Tell the agent what it is and what it should focus on:
You are a specialized assistant for the customer_bank Logical Unit in this K2View project.
You help with designing and modifying tables, populations, enrichment functions, and globals
within this LU only.
Include project-specific conventions. If the agent should follow particular patterns:
All enrichment functions must follow the pattern established in
~{readFile('implementation/Shared Objects/functions/ParseDate.java')}.
Use try-with-resources for all database operations.
Set boundaries. Tell the agent what it should not do:
Do not modify any files outside the customer_bank LU directory. If a request requires
cross-LU changes, describe what is needed and ask the user to confirm.
Use variables for dynamic context. Inject the current file or project path automatically:
The project is located at {{projectRoot}}.
When the user asks about the current file, refer to {{currentRelativeFilePath}}.
Example: A LU-Specific Coding Agent
Here is a complete example of a custom agent focused on a specific Logical Unit:
---
name: CustomerBank-Dev
description: Coding assistant specialized in the customer_bank Logical Unit
---
You are a senior K2View developer specializing in the customer_bank Logical Unit.
Your responsibilities:
- Writing and modifying Java functions (enrichments, populations, decision functions)
- Designing LU table schemas
- Reviewing code for correctness and K2View best practices
Conventions to follow in this project:
~{fragment('shared/coding-standards')}
Current project: {{projectRoot}}
Current file: {{currentRelativeFilePath}}
Only modify files within the customer_bank LU. For cross-LU work, propose the changes
and ask the user to confirm before proceeding.
Editing and Deleting Custom Agents
To edit a custom agent, open AI Configuration, find the agent in the Agents category, and click Edit. You can modify any field and save.
To delete a custom agent, click Delete next to the agent in the list. Built-in agents cannot be deleted (only disabled).
Creating Custom Agents
In addition to the built-in K2View agents, Studio AI lets you create your own agents. A custom agent has a name, a focused purpose, and a prompt you write. Once created, it appears in the chat alongside the built-in agents and can be addressed with @AgentName like any other.
Custom agents are useful when you have a repeated workflow that none of the built-in agents covers well: an agent specialized in a specific LU, a coding style enforcer, or an agent that always injects a particular set of project context.
Creating a Custom Agent
- Open the AI Configuration panel: click More Actions… ("…") in the AI Chat panel toolbar, then Open AI Configuration. See Using the AI Chat.
- Select the Agents category.
- Click Add Custom Agent.
- Fill in the agent definition fields (described below).
- Click Save.
The new agent is immediately available in the AI Chat.
Agent Definition Fields
| Field | Required | Description |
|---|---|---|
| ID | Yes | A unique identifier used internally. Use lowercase with hyphens (e.g., my-agent). Must not conflict with existing agent IDs. k2-assistant and k2-worker are reserved for the built-in agents: agent definitions under .agents/agents/ with either ID are ignored. |
| Name | Yes | The display name shown in the chat and in AI Configuration. This is also the @Name used to address the agent in the chat. |
| Description | Yes | A one-line summary of what the agent does. Appears in the agent list and on the AI Chat welcome screen. |
| Prompt | Yes | The system prompt that defines the agent's behavior, persona, and knowledge. Supports {{variable}} and ~{function} syntax. See Customizing Agent Prompts. |
| Default LLM | No | The model or model alias the agent uses. If omitted, the agent uses the workspace default. |
Where Custom Agents Are Stored
Custom agents are stored as files in the project workspace:
.agents/agents/<id>/agent.html- the default location for new agents..prompts/agents/<id>/agent.html- an older location, still read for backward compatibility. Older projects may also define agents in a.prompts/customAgents.ymlfile.
Because these files are part of the project, an agent is available to everyone working on the project, and can be versioned in Git with the rest of the project.
Studio AI does not load custom agents from the user's home folder: there is no user-level (~/.agents/agents/) agent location that spans workspaces. This differs from skills, which are also read from ~/.agents/skills (see AI Features Settings). To reuse an agent in another project, copy its folder into that project's .agents/agents/.
Writing an Effective Custom Agent Prompt
The prompt is the most important part of a custom agent. A few guidelines:
Start with identity and scope. Tell the agent what it is and what it should focus on:
You are a specialized assistant for the customer_bank Logical Unit in this K2View project.
You help with designing and modifying tables, populations, enrichment functions, and globals
within this LU only.
Include project-specific conventions. If the agent should follow particular patterns:
All enrichment functions must follow the pattern established in
~{readFile('implementation/Shared Objects/functions/ParseDate.java')}.
Use try-with-resources for all database operations.
Set boundaries. Tell the agent what it should not do:
Do not modify any files outside the customer_bank LU directory. If a request requires
cross-LU changes, describe what is needed and ask the user to confirm.
Use variables for dynamic context. Inject the current file or project path automatically:
The project is located at {{projectRoot}}.
When the user asks about the current file, refer to {{currentRelativeFilePath}}.
Example: A LU-Specific Coding Agent
Here is a complete example of a custom agent focused on a specific Logical Unit:
---
name: CustomerBank-Dev
description: Coding assistant specialized in the customer_bank Logical Unit
---
You are a senior K2View developer specializing in the customer_bank Logical Unit.
Your responsibilities:
- Writing and modifying Java functions (enrichments, populations, decision functions)
- Designing LU table schemas
- Reviewing code for correctness and K2View best practices
Conventions to follow in this project:
~{fragment('shared/coding-standards')}
Current project: {{projectRoot}}
Current file: {{currentRelativeFilePath}}
Only modify files within the customer_bank LU. For cross-LU work, propose the changes
and ask the user to confirm before proceeding.
Editing and Deleting Custom Agents
To edit a custom agent, open AI Configuration, find the agent in the Agents category, and click Edit. You can modify any field and save.
To delete a custom agent, click Delete next to the agent in the list. Built-in agents cannot be deleted (only disabled).
