Help Center/ CodeArts Agent/ User Guide (IDE)/ Agents/ Custom Agents
Updated on 2026-07-29 GMT+08:00
View PDF
Share

Custom Agents

Agents are programming assistants tailored for diverse development scenarios. CodeArts Agent not only provides various built-in agents but also supports custom agent capabilities. By configuring prompts, skills, and tool sets within a custom agent as required, you can create a dedicated assistant to handle complex development tasks more efficiently.

Classification of Custom Agents

Custom agents are classified into local and cloud agents by creation method, and are divided into enterprise-level, team-level, project-level, and user-level agents by scope of application. Select the most appropriate agent type to create based on your specific development scenarios and collaboration needs.

Table 1 Classification of custom agents

Creation Method

Scope of Application

Description

Local

Project

Effective only for the current project, distributed along with the repository, and stored locally.

Storage directory: ./ .codeartsdoer/agents in the root directory of the project

User

Effective for all projects of the current user, and stored locally

Local storage directory: %USERPROFILE%/.codeartsdoer/agents/

Cloud

Enterprise

Available to all enterprise users, created by enterprise administrators, and stored in the cloud. When a user logs in to the CodeArts Agent client, the system automatically caches the cloud agents accessible to the user to the local directory: %USERPROFILE%/.codeartsdoer/cache/enterprise/agents/.

Team

Restricted to designated teams, created by enterprise or team administrators, and stored in the cloud. When a user logs in to the CodeArts Agent client, the system automatically caches the cloud agents accessible to the user to the local directory: %USERPROFILE%/.codeartsdoer/cache/team/agents/.

User

Available only to the creator and stored in the cloud. When a user logs in to the CodeArts Agent client, the system automatically caches the cloud agents accessible to the user to the local directory: %USERPROFILE%/.codeartsdoer/cache/user/agents/.

Creating Custom Agents on the GUI

CodeArts Agent supports creating both local and cloud agents. When a user logs in to the CodeArts Agent client, the system caches the cloud agents accessible to the user to the local. After that, the local cache automatically refreshes every 24 hours to ensure synchronization with the cloud. You can also manually click Refresh on the settings page of the CodeArts Agent client to refresh the accessible cloud agents in the local cache.

  1. Log in to CodeArts Agent IDE as instructed in Quick Start.
  2. Click in the upper right corner of CodeArts Agent IDE to open the settings page.
  3. In the navigation pane on the left, choose Agents.
  4. Click Create Agent.
  5. Set agent parameters and click Create.

    Figure 1 Creating a local custom agent
    Table 2 Parameters for creating a local custom agent

    Parameter

    Description

    Agent icon

    The system provides various preset icons for agents. Click on the icon to select a preferred style.

    Agent name

    Name of the custom agent to be created.

    Naming convention: 2 to 20 characters, consisting of letters, digits, underscores, and hyphens (-), and must start with a letter.

    Scope

    Application scope of the custom agent.

    • Project: The agent is only available within the current project and cannot be called by other projects.
    • User: The agent can be called across all projects of the current user.

    Agent type

    Working mode of the agent, which affects its behavior logic and capability boundary.

    • Primary/Sub-agent: It can be used as a sub-agent to be called by a primary agent or as a primary agent to call a sub-agent.
    • Primary agent: It runs independently to process user requests and cannot be called by other agents.
    • Sub-agent: It can be called by primary agents to perform specific tasks.

    Description

    A brief explanation of what the agent does to help users understand its functionality, with a maximum of 5,000 characters.

    Prompt

    System instructions that define the role, tone, workflow, and rules/specifications of the agent.

    Skills

    Skills associated with the agent to enable it to perform certain specialized tasks.

    NOTE:

    CodeArts Agent has no hard limit on the number of associated skills, but it is recommended that the number not exceed 20 to ensure optimal user experience.

    MCP tools

    This configuration item is displayed only when Scope is set to Project.

    External tools or services connected to the agent to enable it to interact with the outside world, such as obtaining real-time information and operating software.

    Up to 80 MCP tools can be added. It is recommended that no more than eight MCP tools be enabled at the same time, with three being ideal for the optimal user experience.

    Built-in tools

    Built-in, out-of-the-box tools provided by the agent.

    • Read: used to retrieve and view files.
    • Edit: used to add, modify, or delete files.
    • Terminal: used to run system commands in the command line environment.
    • Preview: used to preview the generated frontend page in real time.
    • Webfetch: used to capture and read web page content.

  6. Verify the custom agent.

    • After the custom agent is created, you can view it on the corresponding category tab (such as Project or User), and its status will be displayed as enabled.
    • In the input box on the chat page, click Agent. Verify that the target agent is displayed in the custom agent list.

      If you create a sub-agent, it will not be displayed in the custom agent list.

  1. Log in to the CodeArts Agent console.
  2. In the navigation pane on the left, choose Agent Settings > Agents.
  3. Click Create Agent.
  4. Set agent parameters and click Create and Enable.

    Table 3 Parameters for creating an agent

    Parameter

    Description

    Agent icon

    The system provides various preset icons for agents. Click on the icon to select a preferred style.

    Agent name

    Name of the custom agent to be created.

    Naming convention: 2 to 20 characters, consisting of letters, digits, underscores, and hyphens (-), and must start with a letter.

    Agent type

    Working mode of the agent, which affects its behavior logic and capability boundary.

    • Primary/Sub-agent: It can be used as a sub-agent to be called by a primary agent or as a primary agent to call a sub-agent.
    • Primary agent: It runs independently to process user requests and cannot be called by other agents.
    • Sub-agent: It can be called by primary agents to perform specific tasks.

    Description

    A brief explanation of what the agent does to help users understand its functionality, with a maximum of 5,000 characters.

    Applied to

    Application scope of the custom agent, which cannot be modified after creation.

    • Individual: Only the creator can use it.
    • Team: It is available only to specified teams and can be created by enterprise administrators or team administrators.
    • Enterprise: It is available to all enterprise members and can be created only by enterprise administrators.

    Available team space

    This parameter is displayed only when Applied To is set to Team.

    It specifies the teams that can use the agent.

    Enterprise administrators can view all teams but can select only one, while team administrators can only view and select the team they belong to.

    Prompt

    System instructions that define the role, tone, workflow, and rules/specifications of the agent.

    Built-in tools

    Built-in, out-of-the-box tools provided by the agent.

    • Read: used to retrieve and view files.
    • Edit: used to add, modify, or delete files.
    • Terminal: used to run system commands in the command line environment.
    • Preview: used to preview the generated frontend page in real time.
    • Webfetch: used to capture and read web page content.

    Skills

    Skills associated with the agent to enable it to perform certain specialized tasks.

    NOTE:

    CodeArts Agent has no hard limit on the number of associated skills, but it is recommended that the number not exceed 20 to ensure optimal user experience.

  5. View the created agent.

    • Return to the Agent Management page. You can view the created agent in the agent list.
      Figure 2 Viewing the target agent on the Agents page
    • On CodeArts IDE, open the settings page and click Agents. Then click to manually refresh the page. After the refresh is complete, open the target tab (for example, User) to view the target agent.
      Figure 3 Viewing the target agent on the settings page
    • In the input box on the chat page, click Agent. Verify that the target agent is displayed in the custom agent list.

      If you create a sub-agent, it will not be displayed in the custom agent list.

Creating Custom Agents Using Markdown Files

CodeArts Agent allows you to create local project or user agents through Markdown files. When project and user agents share the same name, the project agent takes precedence over the user agent.

Agents are written in the Markdown file format, with YAML Frontmatter metadata configured at the top of the file and with prompt instructions contained in the body.

---
name: agent-name         # Agent name
mode: subagent           # Agent mode
description: Agent desc # Agent function description
tools:                   # Tool permission configuration
  tool1: true           # Allows the use of tool1.
  tool2: false            # Disables the use of tool2.
---

# Prompt
Here lists the system prompt content of the agent.

The following table describes how to set the agent parameters.

Table 4 Markdown file parameters

Parameter

Mandatory (Yes/No)

Parameter Type

Default Value

Description

name

Yes

String

N/A

Name of the agent to be created.

mode

No

String

N/A

Role of the agent.

  • subagent: The agent can only be used as a sub-agent and can be called by a primary agent.
  • primary: The agent can only be used as a primary agent and cannot be called by other agents.
  • all: The agent can be used as a sub-agent to be called by a primary agent or as a primary agent to call a sub-agent.

description

Yes

String

N/A

Description of the agent.

tools

No

Object

N/A

Permissions for tools that can be used by the agent. Table 6 lists the tools supported by CodeArts Agent. You can also use * to match all tools.

Example:

tools:
  "*":false    #All tools are disabled.

Prompt

Yes

String

-

System prompt of the agent.
Table 5 Value description for tools

Parameter

Description

true

Allowed to use a tool.

false

Not allowed to use a tool.
Table 6 Tools supported by CodeArts Agent

Tool

Description

read

Reading files

write

Writing data to files

edit

Editing files

bash

Running commands

glob

File pattern matching

grep

Retrieving content

list

Listing directories

task

Sub-task

webfetch

Obtaining webpage content

websearch

Searching webpages

question

Inquiring users

An agent customized for the current project is distributed along with the repository. A project agent takes effect immediately after being added. If it is a sub-agent, when it is used is determined by the primary agent. You can add a project agent using either of the following methods:

  • Method 1: Creating a Project Agent
    1. Log in to CodeArts Agent IDE as instructed in Quick Start.
    2. In the ./.codeartsdoer/agents folder of the explorer, right-click and choose New > File from the shortcut menu to create a Markdown file.

      The agent name consists of lowercase letters, digits, and hyphens (-). It cannot start or end with a hyphen, cannot contain consecutive hyphens, and must be 1 to 64 characters in length. For example, code-reviewer.

    3. Write the agent in the code-reviewer.md file and press the shortcut keys (Windows/Linux: Ctrl+S; macOS: Command(⌘)+S) to save the file.
  • Method 2: Placing an Existing Agent to the Specified Directory

    Place an existing agent to ./ .codeartsdoer/agents of the project root directory.

A user agent takes effect immediately after being added. If it is a sub-agent, when it is used is determined by the primary agent. You can add a user agent using either of the following methods:

  • Method 1: Creating a User Agent
    1. Create a Markdown agent file in the local directory %USERPROFILE %/.codeartsdoer/agents/.

      The agent name consists of lowercase letters, digits, and hyphens (-). It cannot start or end with a hyphen, cannot contain consecutive hyphens, and must be 1 to 64 characters in length. For example, code-analyzer.

    2. Write the agent in the code-analyzer.md file and press the shortcut keys (Windows/Linux: Ctrl+S; macOS: Command(⌘)+S) to save the file.
  • Method 2: Placing an Existing Agent to the Specified Directory

    Place an existing agent to %USERPROFILE%/.codeartsdoer/agents/.

The following describes how to create and use a project sub-agent.

  1. In the ./.codeartsdoer/agents folder of the file explorer, right-click and choose New > File from the shortcut menu to create a Markdown file named code-analyzer.md.
  2. Add the following content to code-analyzer.md and save the file.

    The .md file name must match the name field within the file, otherwise your sub-agent will fail to run. For example, both the file name and the name field in the example are code-analyzer.

    ---
name: code-analyzer
mode: subagent
description: Code analysis expert for reading but not modifying
tools:
  read: true
  glob: true
  grep: true
  list: true
---

You are a code analysis expert. Your tasks are to:
1. Analyze code structure and quality.
2. Identify potential issues and areas for improvement.
3. Provide optimization suggestions.
Analyze the code carefully, but do not modify any files.

    After the file is saved, you can choose Settings > Agents > Project and find the target agent in the enabled state.

    Figure 4 Viewing the target agent

  3. Add the code file to be checked and call a sub-agent to check the code quality.

    1. On the chat panel of CodeArts Agent, enter #, click File, and select a file from the list.
    2. Enter a prompt, for example, "use code-analyzer to check the code quality," and click .
    3. View the sub-agent calling result.

      The agent calls sub-agents and displays their names in the response.

      Figure 5 Example of using the sub-agent

Using Custom Agents

  1. At the bottom of the input box on the chat panel, select a custom agent (for example, a Python debugging expert) to switch to the custom agent mode. The selected model is displayed on the right. You can select a model as required from the drop-down list.

    If the chat panel of CodeArts Agent is not displayed, click (Expand AI Sidebar) in the upper right corner of the top menu bar to open it.

  2. In the input box on the chat panel, enter a prompt (for example, a Python code block containing errors) and click or press Enter.
  3. View the agent execution result.

    The agent automatically detects syntax or logic errors in the code block and provides accurate correction suggestions and the corrected code.

    Figure 6 Viewing the agent execution result

Setting the Default Model for Custom Agents

Once a custom agent is created, its model usage adheres to the following rules: The primary agent defaults to the model used by the system's built-in agent. For example, if the built-in agent selects GLM-5 as its large language model, the custom agent will also use GLM-5. A sub-agent directly inherits the model used by the primary agent that invokes it. If you need to modify the default model used by a custom agent, you can do so by modifying the configuration file of the custom agent.

  1. Go to the directory where the custom agent's configuration file is stored.

    For example, to modify a project custom agent, go to the ./.codeartsdoer/agents/ directory of the project on the local. You can also locate the corresponding directory in the explorer of CodeArts Agent IDE. For details about the directories for storing Markdown files of other types of custom agents, see Table 1.

  2. Open the Markdown file of the custom agent, add the model field, and save the file (Windows/Linux: Ctrl+S; macOS: Command(⌘)+S).

    In CodeArts Agent, you can specify the default model for custom agents by configuring the model field. You can dynamically switch to the optimal model for specific tasks to balance performance and cost. For instance, employ a lightweight, high-speed model during the planning phase to boost response speed, and invoke a high-capability model during the implementation phase to ensure execution quality.

    The value of the model field is in the format of Provider/Model ID, where Provider indicates the model provider (set to inferhub-provider in CodeArts Agent), and Model ID indicates the ID of the specific model.

    If the configured model does not exist or you do not have the permission, the primary agent automatically switches to the default model of the built-in agent, and the sub-agent inherits the model of the primary agent.

    ---
description: focusing on Python code error check and optimization, expected to be professional and concise.
mode: primary
model: inferhub-provider/GLM-5.1
permission:
  skill:
    '*': deny
disable: false
scope: project
avatar: avatar1
---
    Table 7 IDs of built-in models in CodeArts Agent

    Model Name

    Model ID

    GLM-5.1

    GLM-5.1

    GLM-5.2

    GLM-5.2

  3. Return to the settings page of CodeArts Agent IDE. On the Agents tab, click to refresh the agent configuration.
  4. View the default model of the custom agent.

    In the input box on the chat panel, switch to the target custom agent. The system automatically applies the default model (for example, GLM-5.1) defined by the Markdown configuration file.

Managing Custom Agents

CodeArts Agent IDE features full-lifecycle management capabilities for custom agents. You can efficiently control and continuously optimize created agents based on actual business needs.

Table 8 Managing local custom agents

Operation

Procedure

Enabling or disabling a local custom agent

On the settings page, choose Agents > Project or Agents > User. Click or to enable or disable an agent.

Editing a local custom agent

On the settings page, choose Agents > Project or Agents > User. Hover the cursor on the target agent and click to edit the agent.

Deleting a local custom agent

On the settings page, choose Agents > Project or Agents > User. Hover the cursor on the target agent and click . In the displayed dialog box, click OK.

Deleted agents cannot be restored. Ensure that the agent is no longer needed before performing this operation.

Synchronizing a Custom Agent from the Cloud to the Local

If you log in to the CodeArts Agent client, the system will cache the cloud agents accessible to you locally. Then, the client will update the cache every 24 hours to keep the agents in sync with the cloud. You can also manually refresh them by clicking on the Agents tab.

Enabling or disabling a custom agent synchronized from the cloud to the local

On the settings page, choose Agents > Enterprise or Agents > Team. Click or to enable or disable an agent.

Viewing the configuration of a custom agent synchronized from the cloud to the local

On the settings page, choose Agents > Enterprise, Agents > Team, or Agents > User > Cloud. Hover the cursor on the target agent, and click to view the agent configuration details.

Table 9 shows the operation permissions of different roles on managing cloud custom agents.

Table 9 Operation permissions of different roles on cloud custom agents

Role

Enterprise Agent

Team Agent

User Agent (Operations Except Editing)

User Agent (Editing)

Enterprise administrators

All operations on all agents.

All operations on all agents.

All operations except editing on all agents.

Editing on agents created by themselves.

Team administrators

No operation permissions.

All operations on agents created by members of their own team.

All operations except editing on agents created by members of their own team.

Editing on agents created by themselves.

Members (of an enterprise or a team)

No operation permissions.

No operation permissions.

All operations except editing on agents created by themselves.

Editing on agents created by themselves.
Table 10 Managing cloud custom agents

Operation

Procedure

Enabling or disabling a cloud custom agent
  1. Log in to the CodeArts Agent console.
  2. In the navigation pane on the left, choose Agent Settings > Agents.
  3. In the agent list, click / next to an agent to enable or disable it.

Editing a cloud custom agent
  1. Log in to the CodeArts Agent console.
  2. In the navigation pane on the left, choose Agent Settings > Agents.
  3. In the agent list, click Edit in the Operation column of the target agent to edit it.

Copying a cloud custom agent

When you need to reuse mature configurations, iterate multiple versions in parallel, share team templates, or isolate tasks, you can achieve this by copying agents.

  1. Log in to the CodeArts Agent console.
  2. In the navigation pane on the left, choose Agent Settings > Agents.
  1. In the agent list, click Copy in the Operation column of the target agent.

    System built-in agents cannot be copied.

  2. Adjust the configuration as required (or retain the default settings) and click Create and Enable to quickly generate a new agent.

Deleting a cloud custom agent
  1. Log in to the CodeArts Agent console.
  2. In the navigation pane on the left, choose Agent Settings > Agents.
  3. Check the status of the target agent.
    • If it is enabled, disable it first.
    • If it is disabled, go to the next step to delete the agent.
  4. Click Delete in the Operation column of the target agent. The Delete Agent dialog box is displayed.
  5. Enter DELETE or click Autofill, and then click OK to delete the agent.

    Deleted agents cannot be restored. Ensure that the agent is no longer needed before performing this operation.
Parent Topic: Agents