Managing Agents (Tab: General)

The Agents screen (/organizations/{org}/workspaces/{ws}/instances - the instances path segment is preserved, only the UI label changed) is where you create, list, edit, export, and delete assistants. This is the main hub of operational work. The API, slug fields, and database table name (instances) remain unchanged: “Agent” is purely the UX-facing term.

Listing agents

The agents page supports two view modes - toggle in the top-right:

• List view. Tabular: name, slug, provider, model, status, last activity. Best for browsing many agents.
• Grid view. Card grid with the agent icon prominent. Best for visually distinguishing a small number of agents.

The list is rendered in the order returned by the API - there is no client-side sort.

Active / All filter

A segmented control next to the view-mode toggle switches between two scopes:

• Active (instances.filter.activeOnly i18n key) - shows only agents with status = active. This is the default.
• All (instances.filter.all i18n key) - shows every agent, including disabled ones.

The choice - together with the list/grid view-mode toggle - is persisted in the browser via the instances-show-inactive and instances-view-mode localStorage keys. Neither affects the API itself.

Top action-bar Save

Across every tab on an agent’s detail page, the Save button lives in the top action bar (powered by the usePageSaveAction hook). Per-tab Save buttons no longer exist - every editable surface (General, Prompts, Tools, Skills, Settings, Channels, Room) routes its pending state through the same top-of-page button, which is disabled when there are no changes and shows a spinner while saving.

Creating an agent

Click New Agent. The dialog asks for:

• Name. Free-form display name (any UTF-8). Shown in lists, in conversations, and on the Playground selector.
• Slug. URL-safe identifier (lowercase, alphanumeric, hyphens). The slug is immutable once saved and is the model id used in /v1/chat/completions.
• Description. Free-form text, useful for discriminating similar instances.
• Icon. Optional image, uploaded via the IconUpload widget and stored as a data URI.

When you save, the engine seeds the new instance with:

• The default prompt sections (see Prompts tab).
• The default tool set: readSkill and spawnTask (see packages/engine/src/instances/defaults.ts → DEFAULT_TOOL_NAMES).
• An empty skills list.
• Default flags: memoryEnabled = false, knowledgeEnabled = false, langsmithEnabled = false, authEnabled = true. Memory is off until you turn it on in the Advanced section (see Feature flags).
• Authentication required: the agent answers its HTTP endpoints only to callers presenting its API key, and it has no key until you save one on the Channels → Web/API card.
• Every channel off, Web included: the OpenAI-compatible endpoint and chat/stream answer 404 until you switch Web on, which needs the key unless you turn authentication off and accept the risk notice. The Playground works meanwhile, since it uses your panel session rather than the Web channel.
• Speech-to-text off: sttProvider = disabled, so voice notes are not transcribed until you pick a provider in the Model section.
• No spend cap (managed services): the agent calls the model with no limit until someone sets one.

The instance is active by default. You can disable it later; see “Disabling and deleting” below.

Editing an agent

Clicking an agent opens its detail page, and that page is a destination: it takes over the sidebar with its own index, plus a link back to the agent list. The tenancy is stated by the header breadcrumb - organization › workspace › agent slug.

Its sections are rows in that sidebar, under five headings, and there is no tab row above the page. The three automation sections share one Automation row in the Behaviour group, just before Advanced: it opens a page with three tabs, Webhooks, Scheduled and Room.

Dev mode appears only where the organization and workspace have been granted dev mode, and only to an operator who may open dev sessions. Providers and Spend cap are available with managed services.

Putting every section in the sidebar removed the “which group was that in?” step, and then exposed the real problem: too many destinations, several of them a single toggle. A section is a place you go; a lone switch is a row on a page. So sections merged where nobody read them apart: the six per-channel sections into one Channels, and the tool traces, the runs and the governance events into Logs.

Credentials and Parameters are gone as destinations, because a key is set beside the thing that uses it. On the open-source build a provider key sits in the Model section, in the block of the task that reads it (conversation, embeddings, transcription); with managed services each task’s provider connection is picked in Providers; a tool’s keys and parameters are set in that tool’s panel on Tools; a hook’s on the Hooks page.

One merge was undone. The opt-out and the retention policy were briefly a single Data & privacy section, on the argument that a GDPR opt-out and a data TTL are the same concern. They are two: one is a per-contact switch an operator flips daily, the other a destructive schedule nobody touches for months. They are separate sections again - GDPR opt-out and Retention.

The address is ?tab=<section>; the Automation tabs are webhooks, scheduled and room, and Spend cap is budget. There is no alias table: a value that no longer names a section lands on Status, the same way any unknown value does. Bookmarks to runs, governanceEvents, triggers, the old per-channel addresses or the retired Credentials and Parameters sections will land there. retention is not among them: it is a live section again.

What each section can do depends on the operator’s permissions and, for the areas available only with managed services, on the deployment: each declares the permission its own engine route requires, so a section you cannot use is not offered.

The detail page also has an Export button in the page header that downloads a JSON bundle of just this agent (the same format as the bulk Export described below).

Status

The landing section (?tab=overview) answers one question the rest of the page cannot: is this agent actually working? It is a list of checks the engine computes for the agent, and it exists because a configuration can be green in every individual section and still do nothing at runtime.

It began as a configuration audit - “what is not set”. It now also reports what is failing: a scheduled task that errors, an MCP server that has stopped answering, a retention policy that never ran, knowledge that never finished indexing, a spend cap that has stopped the agent. The list runs to several dozen checks, covering configuration and credentials, tool, skill and knowledge assignments, automation, the model and its provider, runtime health, spend caps, privacy and governance, and dev mode.

The page opens with a single verdict - All good, Needs attention, or Something is not working - over a list ordered by severity.

Checks come in three weights:

Five rules shape the list, and they are worth knowing because they explain what is not there:

• Every check has a destination. Without a section to go and fix it, an alert is just a complaint.
• Falsifiable, never probabilistic. “The prompt looks long” is not a check; “three tools never reach the model because their keys are missing” is.
• What is normal for many agents is a note, not a warning - an agent that only talks is right to have no tools.
• Compare the agent with its own past, not with a threshold of ours. A fixed “>5 s” is an opinion that ages, so the cost and latency checks compare the last seven days against the seven before them.
• Names belong to the agent, counts to the tenant. A check about organization-tier information reports how many, never which, so it can be shown to anyone who reads the agent.

What the engine leaves out at runtime

An assignment shown on the Tools or Skills page is not proof the model receives it. Several checks name what the engine leaves out at runtime, and why:

Each names the tools, skills, plugins or channels it affects.

The same verdict for every reader

The engine computes the whole list, configuration and runtime alike, with its own authority, so every reader sees the same checks and the same verdict on the same agent. A Viewer and an Owner no longer get different lists because one of them could not read the secrets or the dev sessions. Organization-tier facts appear as counts, as described above.

Reading the list requires analytics:read. A reader without it sees an empty Status block rather than an error, and the rest of the agent page works as usual.

The workspace Dashboard and the organization’s count above it read the same evaluation, which is what lets a number there be opened at the rows that produced it.

Silencing a check

A check that is true but not interesting on this agent can be silenced (dismissed). It needs agent:write, and the effect is per agent - the same check stays active everywhere else.

• A dismissal is not a delete. The check is still evaluated and still returned, marked as silenced, because a silenced check nobody can see or undo is a check that was removed. Silenced checks move to a collapsed footer that counts them, with a Restore control on each row.
• There is no expiry. A silenced check stays silenced until someone restores it.
• An optional note can record why.
• The verdict is computed on what is left. Silencing a broken check turns the page green. That is the point of the control, and the reason to leave the note.
• A dismissal holds at every tier above. Once silenced here, the check stops colouring this agent’s row in the workspace Dashboard and the organization’s count above that.

A caller with agent:read but not agent:write can see the controls, and a click fails with a message next to the button.

Two of the checks are about activity rather than configuration - an agent that has never answered, and one that has gone dormant. They are checks rather than a separate “worth a look” list precisely so they carry a destination and can be dismissed like everything else.

Cost and latency regressions

Two checks compare the agent with itself over a seven-day window, against the seven days immediately before it:

Both floors are there so a quiet agent never trips them on noise, which also means a genuinely low-traffic agent will never see these fire. Note that the averages count only calls that returned - a turn that died at the provider does not move the latency average. Failures are the other question, and they have their own checks.

Spend caps

With managed services, three checks report the agent’s spend caps: Spend cap reached ({period}) (broken) when committed spend in an agent-wide window has reached its cap, Near the spend cap ({period}) (warning) at 80% of it, and No spend cap (note) for an agent with no cap that made model calls in the last seven days. Caps per contact and per conversation raise no check.

Trying the agent

A Try button in the page header opens a chat drawer over the configuration, pinned to this agent - no agent picker, and the page behind it stays live and editable, so a prompt can be changed and re-tried without losing the thread. It keeps its conversation, its stream, and even an unsent draft as you move between sections.

A test chat is a real conversation. It writes to the agent’s conversations like any other channel, so it appears in Conversations, in analytics, and under the retention policy.

The Name, Description, and Icon are editable from the General section. The slug is not editable.

Tab: General

The General tab is the instance’s identity card.

Editable fields

• Icon - uploaded via the IconUpload widget (image, stored as a data URI).
• Name - display name, shown everywhere.
• Description - free-form, often used to tell similar instances apart.
• Status switch - toggles between active and inactive. The status switch lives on this General tab; the agents list does not expose it inline.

Read-only fields

• Slug - the immutable URL-safe identifier (shown disabled in the form). To change a slug, create a new instance and use export/import to copy the configuration over.

Slug rules

• Lowercase ASCII letters, digits, and hyphens only.
• Must start with a letter.
• Length: 2 to 64 characters.
• Reserved slugs (admin, api, health, v1) are rejected.

Who can edit

Editing General fields requires the agent:write permission on an agent the operator can reach; reading requires agent:read. Which agents an operator can reach depends on their role and, on managed-services deployments, on their workspace bindings. See Roles and permissions.

Exporting and importing

The Instances page supports two bulk actions:

• Export. Downloads a JSON bundle of one or more selected instances. The bundle carries configuration only: prompts, enabled tools, enabled skills (with version pins), behaviour flags, non-secret channel configuration, hooks, room configuration, event sources, and scheduled tasks. Every credential-like value is stripped - the export is safe to share.
• Import. Uploads a JSON bundle. Conflicting slugs are surfaced for confirmation; you can choose to overwrite or rename on the fly.

The knowledge base is not part of the bundle: it has its own export and import endpoints, so moving it is a deliberate, separate step.

Use export/import to move instance configuration between environments (staging to production) or to share a working configuration with a colleague. See Export and import an instance for the exact contents and the post-import steps.

Disabling and deleting

An instance has three operations on its lifecycle:

• Disable. Status flips to inactive. Channels stop. The instance is no longer visible in the OpenAI-compatible API’s /v1/models list. Conversations and history are kept.
• Re-enable. Status flips back to active. Channels do not auto-restart; you must start them manually.
• Delete. Permanently removes the instance and all its scoped data: conversations, messages, memories, audit logs for that instance, room configuration, and event sources. There is no undo. A confirmation dialog requires you to type the slug.

Tip. When in doubt, prefer disable over delete. Disabled instances cost nothing and can be restored.