---
title: Agents
description: Create, configure, version, and manage the lifecycle of AI agents in AKOS.
---

The Agents screen is where you define the AI assistants that power your workflows. Every agent has an identity, a model, a prompt, tools, skills, memory settings, and a lifecycle state.

## Agent registry

The registry lists all agents in the workspace. You can switch between **card view** and **list view** using the toggle in the toolbar. Use the search box and the filter menu to narrow the list by name, ID, or lifecycle state.

### Lifecycle states

Each agent moves through a controlled lifecycle enforced by the governance engine:

| State | Meaning |
|---|---|
| **Draft** | In development; not used by live flows. |
| **Review** | Submitted for review; pending approval. |
| **Approved** | Cleared for staging; governance gates satisfied. |
| **Staged** | In a pre-production environment; final verification. |
| **Production** | Live and available to flows and triggers. |
| **Deprecated** | Scheduled for removal; still runs existing flows. |
| **Retired** | Decommissioned; preserved for audit. |

To move an agent to the next state, click the **Promote** action on its row. A confirmation dialog explains which governance gates must be satisfied. Unsatisfied gates are listed with actionable hints. You can also demote or retire an agent from the same menu.

## Creating an agent

Click **New agent** in the toolbar. You have four starting options:

- **Blank** — fill in all fields yourself.
- **Template** — choose a pre-built template for your vertical (finance, healthcare, legal, etc.).
- **Natural language** — describe the agent in plain English; AKOS generates a draft you can edit.
- **Import** — import from a YAML/JSON file or a URL.

### Agent form tabs

The new-agent form has two modes: **Simple** (fewer fields) and **Advanced** (all fields). Use the toggle in the form header to switch. The form is split into steps:

**Basic**
- **ID** — unique slug (lowercase, digits, dashes). **Auto-generated from the name** as you type, so you rarely set it by hand. Use the **Advanced** disclosure to override it on creation. Locked after creation.
- **Name** — display name. Required.
- **Description** — short summary shown in cards and lists.
- **Role** — optional role to inherit capabilities and a default model from.
- **Risk tier** — classification used by governance policies.

**Model**
Override the LLM provider and model for this agent, or leave blank to inherit from the assigned role. The model field is a **searchable catalog picker** backed by the live model catalog — over 5,000 models across 140+ providers. Start typing a provider or model name and the dropdown narrows as you type; each result shows the provider, model id, and capability tags such as `reasoning` and `tools`. See [Model catalog](/docs/using-the-app/model-catalog) for how the catalog works and how to pick the right model.

**Prompt**
The agent's **system prompt** — the standing instructions given to the model at the start of every run. Required.

**Skills & Tools**
- **Skills** — high-level named capabilities (for example, `web.search`, `doc.summarize`). You can type a custom skill slug if needed.
- **Tools** — low-level primitives the agent may invoke (for example, HTTP calls, SQL queries, notification sends). Tools are grouped by their integration provider.

**Memory**
Choose how the agent maintains conversation history:

| Mode | Behaviour |
|---|---|
| **None** | No per-agent memory; uses the workspace default if configured. |
| **Ref** | Points to a named workspace memory slot. |
| **Inline** | Defines its own memory backend (file, SQLite, Redis, vector store). |

For inline memory, fill in the backend-specific fields (path, Redis URL, vector provider, collection, dimensions, embeddings model).

**Advanced**
Additional settings for timeouts, retry policy, and output schema (available in Advanced mode).

Click **Create draft** to save the agent in draft state. You can review and submit from any step using **Next** / **Back**.

## Editing an agent

Click **Edit** on any agent row or card. The same multi-step form opens with the agent's current values. The **ID** field is locked because changing an agent's ID would break all references to it.

## Testing an agent (sandbox)

Click **Test** on an agent to open the **Sandbox drawer**. Enter a test prompt and run the agent in isolation. The result panel shows the model's response, tool calls made, and cost.

## Version history

Click **Versions** on an agent to open the **Version history drawer**. This shows every saved snapshot of the agent, with timestamps and the actor who made each change.

- Select a version in the left panel to see a **diff** against the current live version in the right panel.
- To roll back, click **Rollback** next to the version you want. You will be asked to enter an optional reason. The rollback mints a new version pointing back at the selected snapshot — no history is lost.

## Bulk operations

Check multiple agents in list view to activate the **bulk toolbar**. You can promote or retire a selection of agents at once, or delete a set of drafts.

## Related screens

| Need | Go to |
|---|---|
| Use agents in flows | [Workflows](/docs/using-the-app/flows) |
| Regression testing | [Quality checks (Evals)](/docs/using-the-app/evals) |
| Coding agents | [Coding](/docs/using-the-app/coding) |
| Multi-agent layouts | [Route-only screens](/docs/using-the-app/route-only-screens) (`topologies`) |
| Model selection | [Model catalog](/docs/using-the-app/model-catalog) |