Define an Agent

Key concepts

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

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

Model

The model field specifies the model that the Agent uses.

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):

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:

1. GET the latest Agent to retrieve the current version

2. Re-apply your desired changes to the latest object data.

3. Use the new version to perform another PUT.

Best practices

1. Naming conventions — Use the team-purpose format, such as backend-code-review, frontend-test-gen.

2. Prompt refinement — Specify the role, output format, and constraints in the system field.

3. Apply the principle of least privilege: Grant only the tools essential for the task to minimize risk.

4. Use metadata effectively: Add key-value pairs to categorize Agents for easier filtering and auditing.

5. 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 tools array 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 name field?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.