Agents

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:

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

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