Help Center/ CodeArts Agent/ User Guide (CLI)/ Agents
Updated on 2026-08-03 GMT+08:00
View PDF
Share

Agents

Agents are programming assistants tailored for diverse development scenarios. CodeArts Agent CLI provides multiple out-of-the-box agents that require no manual creation, aiming to provide efficient programming assistance for various development scenarios. In addition to built-in agents, you can also create custom agents.

Built-in Agents

Built-in agents are classified into primary agents and sub-agents. Primary agents are the primary assistants you interact with. You can use the Tab key to switch between them. These agents handle your main conversations. Sub-agents are specialized assistants that primary agents can call to perform specific tasks. You can manually call a sub-agent by entering an at sign (@) followed by the sub-agent name in a session.

Table 1 Built-in agents

Type

Creator

Description

Primary agent

System built-in

CodeArts Agent CLI has two core primary agents built in: Build and Plan. They are responsible for development and planning, respectively.

  • Primary agent: Build

    The default development execution agent, which has full access to tools. It is suitable for scenarios where actual development operations are required, such as modifying code, executing commands, or creating files.

    Typical scenarios:

    • Writing, modifying, or deleting code files
    • Executing terminal commands for build, test, and deployment
    • Creating new functional modules or fixing bugs
    • Performing any actual operations that implements changes to the project
  • Primary agent: Plan

    A constrained read-only agent that focuses on analyzing code structure, designing solutions, and formulating implementation plans. It does not make any substantial changes to the code repository.

    Typical scenarios:

    • Analyzing code structure and logic
    • Designing functional solutions or refactoring strategies
    • Locating bugs and planning fixes
    • Architecture review and feasibility analysis
    • Any scenario where you need to think clearly before taking action

Sub-agent

System built-in

Sub-agents are specialized assistants that primary agents can call to perform specific tasks. You can manually call a sub-agent by entering an at sign (@) followed by the sub-agent name in a session.

NOTE:

You can view the built-in sub-agents using the following commands:

  • CLI environment: codearts run "<natural-language-description>". The description must contain the subagent keyword.
  • TUI environment: Enter an at sign (@) in the text box.
  • developer-test-agent: An agent used to generate, fix, and optimize unit tests, and review real code repositories.
  • explore: A code repository exploration agent dedicated to quickly locating files, searching code keywords, and answering related questions.
  • general: A general-purpose agent used to research complex problems and execute multi-step tasks.
  • rule-generator: A rule generator.
  • spec-design-agent: An agent used to generate comprehensive technical designs, converting requirements (what to do) into architectures (how to do it).
  • spec-requirement-agent: An agent used to generate requirements for the Easy Approach to Requirements Syntax (EARS) format based on the project description and context.
  • spec-task-agent: An agent used to generate implementation tasks based on requirements and design.

Custom Agents

In addition to built-in agents, CodeArts Agent CLI also supports custom agents. When project-level and personal-level agents share the same name, the project-level agent takes precedence over the personal-level agent.

Table 2 Classification of custom agents

Type

Scope

Description

Custom primary agent

Custom sub-agent

Project-level

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

Storage location: Project root directory/.codeartsdoer/agents

Personal-level

Agents are based on personal habits or preferences and take effect only for all projects of the current user.

Storage location: ~/.codeartsdoer/agents

The tilde (~) indicates the home directory of the current user. In Windows, it is equivalent to C:\Users\Username\. In macOS, it is equivalent to /Users/Username/. In Linux, it is equivalent to /home/Username/.

Creating Agents Using Markdown Files

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

Custom Agent File Format

Custom agents are written in the Markdown file format. The file header configures metadata using YAML front matter, and the body contains the system prompt and role instructions.

---
description: Agent desc # Agent function description
mode: subagent           # Agent description
model: provider/model     # If the model is configured in this format, the default model will be overwritten.
tools:                   # Tool permission configuration.
  tool1: true           # Allows the use of tool1.
  tool2: false            # Prohibits the use of tool2.
---

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

The following table describes the parameters of the custom agent.

Table 3 Markdown file parameters

Parameter

Mandatory

Type

Default Value

Description

description

Yes

String

N/A

Description of the custom agent

mode

Yes

String

subagent

Role of the agent

  • subagent: The agent can only be called as a sub-agent.
  • primary: The agent can only be a primary agent and cannot be called.
  • all: The agent can be a primary agent or called as a sub-agent.

model

No

String

N/A

Format: provider/model

tools

No

Object

N/A

Tool permissions available to the agent. For details about the tools supported by CodeArts Agent CLI, see Table 5. You can also use * to match all tools.

Example:

tools:
  "*":false    # Prohibits the use of all tools.

hidden

No

Boolean

N/A

Visibility control

If this parameter is set to true, the agent is hidden from the @ autocomplete menu. This setting is intended for internal agents that are called only through programmatic calls.

disable

No

Boolean

N/A

Switch control

  • true: disables the agent.
  • false: enables the agent.

Prompt

Yes

String

N/A

System prompt of the custom agent
Table 4 Object value description for tools

Parameter

Description

true

Allows the use of a tool.

false

Prohibits the use of a tool.
Table 5 Tools supported by CodeArts Agent CLI

Tool

Description

read

Reading files

write

Writing data to files

edit

Editing files

bash

Running commands

glob

File pattern matching

grep

Retrieving content

task

Sub-task

webfetch

Obtaining webpage content

question

Inquiring users

Example Custom Agent

This example describes how to configure a personal sub-agent in Windows.

  1. Go to the ~/.codeartsdoer/agents directory, create the test.md file, and write the content below to the file.

    The tilde (~) indicates the home directory of the current user. In Windows, it is equivalent to C:\Users\Username\. In macOS, it is equivalent to /Users/Username/. In Linux, it is equivalent to /home/Username/. 
    ---
# ========== Mandatory ==========
description: (Mandatory) Description of the agent's functions and application scenarios. The primary agent determines when to call this agent based on this description.
mode: subagent            # Enumerated values: subagent (sub-agent) / primary (primary agent) / all (both).

# ========== Model Configuration ==========
model: provider/model-id # Custom model. Format: provider/model-id. You can run the /models command to view the supported models.

# ========== Behavior Control ==========
hidden: false              # true: Hide from the @ autocomplete menu, only available for internal programmatic calls.
disable: false             # true: Disable the current agent.

# ========== Tool Permissions ==========
tools:
  write: false              # File write permission.
  edit: false               # File edit permission.
  bash: false               # System command execution permission.
  read: false               # File read permission.

# System prompt (supports multi-line Markdown format)
You are a senior code review expert. Focus on:

- Code quality and best practices
- Potential bugs and edge cases
- Performance impact
- Security risks

Provide constructive feedback and do not directly modify the code.

  2. Go to any code project and run the following command: 

    @test Analyze code

    After the command is delivered, the AI specifies a custom sub-agent to analyze code.

    Figure 1 Calling the test sub-agent to analyze code