Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.qoder.com/llms.txt

Use this file to discover all available pages before exploring further.

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, prefixed with ag_
namestringYesAgent name; lowercase kebab-case recommended (≤ 64 chars)
modelstringYesModel identifier; see below
systemstringNoSystem prompt that defines agent behavior
toolsarrayNoList of tools the agent can use; see below
skillsarrayNoList of associated Skill IDs
metadataobjectNoCustom key/value pairs for tagging and filtering
versioninteger—Version number, starting at 1
created_atstring—Creation timestamp (ISO 8601)
updated_atstring—Last update timestamp

​
model

A string identifier for the model the Agent uses:
ValueDescription
"ultimate"The strongest model — best for complex reasoning and long tasks
"auto"Automatically picks the best price-performance model

​
tools

tools is an array of tool objects. Each entry declares one capability the Agent can perform: 
{
  "tools": [
    {"type": "bash_20250124"},
    {"type": "file_read"},
    {"type": "file_write"},
    {"type": "web_search"}
  ]
}
Common tool types:
TypeDescription
bashRun shell commands
file_readRead file contents
file_writeCreate or modify files
web_searchSearch the web
For more (including 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://openapi.qoder.sh/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": "bash_20250124"},
      {"type": "file_read"},
      {"type": "file_write"}
    ],
    "metadata": {
      "team": "backend",
      "purpose": "code-review"
    }
  }' | jq .
A successful call returns 201 Created with version set to 1.

​
Read

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

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

​
Update

Updates must include the current version. See “Versioning” below. 
curl -s -X PUT https://openapi.qoder.sh/api/v1/cloud/agents/ag_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.

​
Delete

curl -s -X DELETE https://openapi.qoder.sh/api/v1/cloud/agents/ag_xxx \
  -H "Authorization: Bearer $QODER_PAT"
Deleting an Agent does not terminate Sessions bound to it. Each Session snapshots the Agent’s configuration at creation time.

​
Versioning

Agents use optimistic concurrency control (OCC):
  • On creation, version starts at 1.
  • Each successful update increments version.
  • Updates must carry the current version, otherwise the API returns 409 Conflict.
This prevents concurrent updates from silently overwriting each other.

​
Handling 409

When the held version is stale: 
{
  "error": {
    "type": "conflict",
    "message": "Version mismatch: expected 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