> ## 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. # Defining 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": | 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](/cloud-agents/api/models/list) 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: ```json theme={null} { "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](/cloud-agents/tools). ## Managing Agents For the full CRUD surface see the [API Reference / Agents](/cloud-agents/api/agents/create). Below are common workflow snippets. ### Create ```bash theme={null} 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 ```bash theme={null} # 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. ```bash theme={null} 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: ```json theme={null} { "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. ## 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 Set up the runtime your Agents execute in. Create a working session with an Agent. Tool types and permission policies in depth. The full Agents CRUD surface.