Skip to main content
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.

​
Agent configuration fields

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 []
metadataobjectNoCustom key/value pairs for tagging and filtering
versioninteger—Version number, starting at 1
archivedboolean—Whether archived (default false)
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 the identifier of the model the Agent uses. Call List models to discover the values available to the current account, then pass the model id when creating or updating an Agent.

​
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
DeliverArtifactsDeliver files produced under /data/ to the user
For custom client-side tools and permission policies, see Agent Tools.

​
Create an agent

curl -s -X POST https://api.qoder.com/api/v1/cloud/agents \
  -H "Authorization: Bearer $QODER_PAT" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "code-reviewer",
    "model": "ultimate",
    "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 201 Created with version set to 1.

​
Get or list agents

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

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

​
Update an agent

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

​
Update semantics

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",
  "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. PUT 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.

​
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 PUT it back later (with the latest version).

​
Next steps

Cloud environment setup

Set up the runtime your Agents execute in.

Start a session

Create a working session with an Agent.

Tools

Tool types and permission policies in depth.

Agents API

The full Agents CRUD surface.