Define an Agent - Qoder CN

An Agent is a reusable configuration template that defines an AI agent's model, instructions, and tools. Multiple Sessions can share one Agent, and modifying an Agent does not affect running Sessions.

Key concepts

You can think of an Agent as a "job description":

Element	Description
model	The Agent's intelligence level
system prompt	The Agent's behavioral guidelines
tools	The actions the Agent performs
Skills	The high-level skills the Agent invokes

An Agent itself does not execute tasks; it is merely a configuration. Task execution is handled by a Session bound to that Agent.

Parameter reference

Parameter	Type	Required	Description
`id`	string	—	System-generated ID, with an `agent_` prefix followed by 32 lowercase hexadecimal characters.
`type`	string	—	Always `"agent"`.
`name`	string	Yes	The Agent name. The recommended format is kebab-case (≤ 64 characters).
`description`	string	No	A description for the Agent. Defaults to `""`.
`model`	string	Yes	The model identifier. See details below.
`system`	string	No	The system prompt. Defaults to `""`.
`instructions`	string	No	Behavioral instructions appended to the system prompt.
`tools`	array	No	A list of available tools. See details below.
`skills`	array	No	A list of associated Skill IDs.
`mcp_servers`	array	No	A list of MCP server configurations. Defaults to `[]`.
`default_environment`	string	No	The default Environment ID for this Agent. Defaults to `""`.
`metadata`	object	No	Custom key-value pairs for tagging and filtering.
`version`	integer	—	The version number, which starts at 1 and increments with each update.
`archived`	boolean	—	Whether the Agent has been archived. Defaults to `false`.
`archived_at`	string\|null	—	The archival timestamp in ISO 8601 format. `null` if the Agent is not archived.
`created_at`	string	—	The creation timestamp in ISO 8601 format.
`updated_at`	string	—	The timestamp of the last update.

Model

The model field specifies the model that the Agent uses.

Value	Description
`Auto`	Automatic model selection
`Qwen3.7-Max`	Qwen flagship
`Qwen3.7-Plus`	Qwen multimodal
`Qwen3.6-Flash`	Qwen lightweight
`DeepSeek-V4-Pro`	DeepSeek flagship
`DeepSeek-V4-Flash`	DeepSeek lightweight
`GLM-5.1`	Zhipu flagship
`Kimi-K2.6`	Moonshot AI
`MiniMax-M2.7`	MiniMax

Tools

The tools field is an array of tool objects. Currently, only the agent_toolset_20260401 toolset is supported. You enable atomic tools within this toolset by listing them in the enabled_tools array:

{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}

Available values for enabled_tools (values are case-sensitive and must be in PascalCase):

Tool name	Description
`Bash`	Execute shell commands.
`Read`	Read file content.
`Write`	Create or overwrite a file.
`Edit`	Edit part of a file.
`Glob`	List files using wildcards.
`Grep`	Search for content within files.
`WebFetch`	Perform an HTTP GET request for a single webpage.
`WebSearch`	Search the web.

For more tool configurations, see Agent Tool Configuration.

Manage agents

For all CRUD operations, see API Reference / Agents. The following examples cover common workflows.

Create

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "auto",
    "instructions": "You are a code review expert. Review the code line by line and output issues and improvement suggestions in Markdown.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      }
    ],
    "metadata": {
      "team": "backend",
      "purpose": "code-review"
    }
  }' | jq .

A successful request returns 201 Created. The version starts at 1.

Query

# Get a single Agent
curl -s https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT"

# List Agents with pagination
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=20" \
  -H "Authorization: Bearer $QODER_PAT"

Update

When you update an Agent, you must provide the current version. For more information, see Version management below.

curl -s -X PUT https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "auto",
    "instructions": "You are a senior code review expert, focusing on security vulnerabilities and performance issues.",
    "version": 1
  }' | jq .

A successful request returns 200 OK, and the version increments by 1.

Delete

curl -s -X DELETE https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_PAT"

Deleting an Agent does not terminate active Sessions bound to it. A Session snapshots the Agent's configuration upon creation.

Version management

The Agent API uses optimistic concurrency control (OCC):

The version starts from 1 upon creation.
After each successful update, the version is automatically incremented by 1.
Update requests must include the current version. Two failure scenarios:
- Missing version field — returns 400 invalid_request_error ("Field 'version' is required.")
- The version is provided but does not match the server-side version — returns 409 conflict_error

This prevents concurrent modifications from overwriting each other.

Handling 409 conflicts

If your request fails because the version is outdated, you receive this error:

{
  "type": "error",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 2, got 1."
  }
}

To resolve the conflict:

GET the latest Agent to retrieve the current version
Re-apply your desired changes to the latest object data.
Use the new version to perform another PUT.

Best practices

Naming conventions — Use the team-purpose format, such as backend-code-review, frontend-test-gen.
Prompt refinement — Specify the role, output format, and constraints in the system field.
Apply the principle of least privilege: Grant only the tools essential for the task to minimize risk.
Use metadata effectively: Add key-value pairs to categorize Agents for easier filtering and auditing.
Version locking in production — When creating a Session, use the {"id": ..., "version": ...} format to lock the Agent version. This prevents new versions from affecting your online services.

FAQ

Q: Does updating an Agent affect currently running Sessions?No. A Session is bound to a specific Agent version upon creation.Q:Can the toolsarray be empty?Yes. An Agent without tools can only engage in text-based conversation and cannot perform actions.Q:Is there a length limit for the namefield?Keep it under 64 characters and use lowercase letters, numbers, and hyphens.Q: How do I roll back to an older version of an Agent?Automatic rollback is not supported. Save the Agent configuration before updating it. To revert, PUT the old configuration with the latest version number.

Next steps

Cloud Environment — Configure the infrastructure where the Agent runs.
Start a Session — Create a Session with an Agent.
Agent Tool Configuration — Learn more about tool types and permission policies.

​Key concepts

​Parameter reference

​Model

​Tools

​Manage agents

​Create

​Query

​Update

​Delete

​Version management

​Handling 409 conflicts

​Best practices

​FAQ

​Next steps