Defining an Agent

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

Element	What it controls
Model	The agent’s reasoning capability
System prompt	The agent’s behavior and rules
Tools	What actions the agent can perform
Skills	Higher-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

Field	Type	Required	Description
`id`	string	—	System-generated, `agent_` prefix + 32 lowercase hex characters
`type`	string	—	Always `"agent"`
`name`	string	Yes	Agent name; lowercase kebab-case recommended (≤ 64 chars)
`description`	string	No	Free-form description; defaults to `""`
`model`	string	Yes	Model identifier; see below
`system`	string	No	System prompt; defaults to `""`
`tools`	array	No	List of tools the agent can use; see below
`skills`	array	No	List of associated Skill IDs
`mcp_servers`	array	No	List of MCP server configurations; defaults to `[]`
`multiagent`	object\|null	No	Agents configuration; returned as `null` when not set
`metadata`	object	No	Custom key/value pairs for tagging and filtering
`version`	integer	—	Version number, starting at 1
`archived_at`	string\|null	—	Archive time (ISO 8601), `null` when not archived
`created_at`	string	—	Creation timestamp (ISO 8601)
`updated_at`	string	—	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 name	Description
`Bash`	Run shell commands
`Read`	Read file contents
`Write`	Create or overwrite files
`Edit`	Partially edit files
`Glob`	Glob pattern file listing
`Grep`	File content search
`WebFetch`	HTTP GET a single page
`WebSearch`	Web search
`DeliverArtifacts`	Deliver 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/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 200 OK with version set to 1.

Read

# 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

Updates must include the current version. See “Versioning” below.

curl -s -X POST 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.

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:

GET the Agent to fetch the latest version.
Merge your changes.
POST again with the new version.

Best practices

Naming — use team-purpose format (e.g. backend-code-review, frontend-test-gen).
Tight prompts — be explicit in system about role, output format, and constraints.
Minimal tools — grant only what the task needs to reduce blast radius.
Use metadata — tag Agents for later filtering and audit.
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 POST 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.

​Core elements

​Field reference

​model

​tools

​Managing Agents

​Create

​Read

​Update

​Versioning

​Handling 409

​Best practices

​FAQ

​Next steps