Create an agent

An agent is created by a four-step wizard at /agents/new. Each step narrows what the agent may do, in this order: Catalog → Skills → Scope → Name. The whole thing takes a couple of minutes; the thinking you do in step 3 is what separates a demo from something you can hand to a client.

Step 1 — Catalog

Pick the subject areas the agent may read from. A catalog (also called a domain) is a grouping of approved metrics — sales, marketing, finance, operations, and whatever else your workspace has defined. The step shows each catalog with its metric count so you can see what you are granting. You can subscribe to a catalog, choose individual metrics, or have the agent inherit the entire workspace catalog. A catalog subscription follows the catalog's current membership.

Choose narrowly: an agent that can read everything is harder to trust and harder to test than one that owns a single subject.

The selection here grounds the following steps — available skills, generated example questions and the agent's data binding all follow from it.

Step 2 — Skills and tools

Skills are reusable playbooks: how to run a weekly review, how to structure a variance analysis, how to format a client-facing summary. Selecting a skill tells the agent to follow that method rather than improvising one.

You can:

Select existing skills from your workspace.
Fork a skill from the Skills Hub and adapt it.
Generate a new skill with AI, from a description of what you want done.

When a skill needs data you have not granted, the wizard says so at pick time rather than failing later in a chat. You then either point the skill at the closest metric you do have (which forks the skill so the original stays intact), or add the missing data to the agent's scope.

Skills are optional. An agent with no skill still answers questions from its metrics — it just has no house method for doing so.

Tools are capabilities that skills or conversations can actually invoke, including data queries, external actions, and report or media generation. The build page's tool settings show available built-in, approved custom, and skill-pack tools. Workspace policy determines which tools are enabled and whether they run automatically or require approval first. Data tools remain constrained by the metric catalog and data scope.

Step 3 — Scope

Scope is the contract between the agent and the people who use it. You define:

Purpose — one or two sentences on what this agent is for.
In-scope examples — real questions it must handle well. These are not decoration: they seed the eval set later, so write questions you would actually be embarrassed to get wrong.
Refusal routes — what happens with questions it should not answer. Say where to send the person instead ("pricing questions go to the finance team") so a refusal is still useful.

The wizard also generates candidate examples from your catalog and skill selection; approve the good ones and edit the rest.

At runtime this contract is enforced, not merely suggested. A question that needs a metric outside the agent's scope is refused rather than answered from something adjacent.

Step 4 — Name and review

Name the agent and review its description. Both are pre-filled from your earlier answers, so most of the time you are editing rather than writing. Names are what your clients see in the Portal — "Retail Weekly Review" travels better than "Agent 3".

Creating the agent takes you straight to its build page (/agents/:id/build), where you can chat with it, adjust its pipeline and tools, and open the Evals and Readiness tabs.

The agent lifecycle

Every agent moves through five states:

Draft — just created. Only you can use it. Editing is free-form.
Tested — it has completed a successful run. This happens automatically; you do not promote it by hand.
Live — published for other people. Getting here requires the actual publication checks described in Verify and evaluate; the eval pass rate is a quality signal, not a standalone hard gate.
Suspended — all runs are stopped. Until it is restored, the builder chat, Portal, and scheduled runs are unavailable.
Deprecated — a terminal state for an agent that is no longer in use.

Going live also requires a real data source behind the agent — an approved workspace metric, an enabled per-user upload slot, or a live spreadsheet connector. An agent wired only to an HTTP or mail tool has no data to ground on and stays blocked.

Editing later

Everything in the wizard is editable afterwards from the build page. Two behaviours are worth knowing:

Widening data scope is guarded. If a change would let the agent read metrics it was not scoped for, you are asked to acknowledge the gap before it saves.
Editing a published agent does not change what your clients see until you republish. See Publish to the Portal.