Skip to main content
Define your agent

Define an Agent

Create a reusable, versioned agent configuration.

An Agent is the core configuration template in Qoder Cloud Agents — it defines what the AI agent can do: which model, what behavior, and which tools. One Agent can be reused across many Sessions, and updates to an Agent don't affect Sessions already running.

Core elements

Think of an Agent as a "job description":
ElementWhat it controls
ModelThe agent's reasoning capability
System promptThe agent's behavior and rules
ToolsWhat actions the agent can perform
SkillsHigher-level skills the agent can invoke
The Agent itself doesn't run anything — it's just configuration. The work happens inside a Session bound to that Agent.

Field reference

FieldTypeRequiredDescription
idstring—System-generated, agent_ prefix + 32 lowercase hex characters
typestring—Always "agent"
namestringYesAgent name; lowercase kebab-case recommended (≤ 64 chars)
descriptionstringNoFree-form description; defaults to ""
modelstringYesModel identifier; see below
systemstringNoSystem prompt; defaults to ""
toolsarrayNoList of tools the agent can use; see below
skillsarrayNoList of associated Skill IDs
mcp_serversarrayNoList of MCP server configurations; defaults to []
multiagentobject|nullNoMultiagent orchestration configuration; returned as null when not set
metadataobjectNoCustom key/value pairs for tagging and filtering
versioninteger—Version number, starting at 1
archived_atstring|null—Archive time (ISO 8601), null when not archived
created_atstring—Creation timestamp (ISO 8601)
updated_atstring—Last update timestamp

model

model is a string identifying the model used by the Agent. Model IDs are lowercase:
ValueDescription
autoAutomatic model selection
qwen3.7-maxQwen flagship
qwen3.7-plusQwen multimodal
qwen3.6-flashQwen lightweight
deepseek-v4-proDeepSeek flagship
deepseek-v4-flashDeepSeek lightweight
glm-5.1Zhipu flagship
kimi-k2.6Moonshot AI
minimax-m2.7MiniMax

tools

tools is an array of tool objects. Built-in tools are configured through agent_toolset_20260401, which selectively enables atomic tools via the enabled_tools array: 
{
  "tools": [
    {
      "type": "agent_toolset_20260401",
      "enabled_tools": ["Bash", "Read", "Write", "Edit", "Glob", "Grep", "WebFetch", "WebSearch"]
    }
  ]
}
Available enabled_tools values:
Tool nameDescription
BashRun shell commands
ReadRead file contents
WriteCreate or overwrite files
EditPartially edit files
GlobGlob pattern file listing
GrepFile content search
WebFetchHTTP GET a single page
WebSearchWeb search
ImageSearchSearch for images
ImageGenGenerate images from text prompts
DeliverArtifactsDeliver files produced under /data/ to the user
For custom client-side tools and permission policies, see Agent Tools.

Managing Agents

For the full CRUD surface see the API Reference / Agents. Below are common workflow snippets.

Create

curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "auto",
    "system": "You are a code review expert. Review code line by line and emit issues and improvements as Markdown.",
    "tools": [
      {
        "type": "agent_toolset_20260401",
        "enabled_tools": ["Bash", "Read", "Write"]
      }
    ],
    "metadata": {
      "team": "backend",
      "purpose": "code-review"
    }
  }' | jq .
A successful call returns 200 OK with version set to 1.

Read

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

# Paginated list
curl -s "https://api.qoder.com.cn/api/v1/cloud/agents?limit=20" \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN"

Update

Updates must include the current version. See "Versioning" below. 
curl -s -X POST https://api.qoder.com.cn/api/v1/cloud/agents/agent_xxx \
  -H "Authorization: Bearer $QODER_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "auto",
    "system": "You are a senior code reviewer focused on security and performance.",
    "version": 1
  }' | jq .
A successful call returns 200 OK with version incremented.

Versioning

Agents use optimistic concurrency control (OCC):
  • On creation, version starts at 1.
  • Each successful update increments version.
  • Updates must carry the current version. Two failure cases:
    • Missing version field — returns 400 invalid_request_error ("Field 'version' is required.")
    • version present but stale (does not match server) — returns 409 conflict_error
This prevents concurrent updates from silently overwriting each other.

Handling 409

When the held version is stale: 
{
  "type": "error",
  "request_id": "cb80235f-76a2-4ff3-9e28-5aa2da12dc14",
  "error": {
    "type": "conflict_error",
    "message": "Version conflict. Expected version 2, got 1."
  }
}
Recovery:
  1. GET the Agent to fetch the latest version.
  2. Merge your changes.
  3. POST again with the new version.

Best practices

  1. Naming — use team-purpose format (e.g. backend-code-review, frontend-test-gen).
  2. Tight prompts — be explicit in system about role, output format, and constraints.
  3. Minimal tools — grant only what the task needs to reduce blast radius.
  4. Use metadata — tag Agents for later filtering and audit.
  5. Pin versions in production — when creating a Session, pass {"id": ..., "version": ...} so production behavior doesn't shift when the Agent is updated.
To let one Agent delegate work to specialized Agents, see Multiagent orchestration.

FAQ

Q: Will updating an Agent affect Sessions that are already running? No. Each Session is bound to the Agent's specific version at creation time; later updates don't propagate. Q: Is an empty tools array allowed? Yes. An Agent without tools can only handle plain-text conversation — it can't perform any actions. Q: Are there limits on the name field? Keep it under 64 characters and use lowercase letters, digits, and hyphens. Q: How do I roll back to an older version of an Agent? Automatic rollback isn't supported yet. Snapshot the configuration before updating, then POST it back later (with the latest version).

Next