Agents

An agent names a flow entry point inside exactly one space — it is the thing external clients actually run. An agent cannot exist outside a space: the space is chosen at creation, and deleting the space deletes its agents. The record itself is deliberately light — a display name, the agentId slug, the run entry (startFlow + startNode), an active switch and timestamps.

Two identities matter and must not be confused: the generated row id is what admin pages address, while the agentId slug is what clients run by — and the same slug is what an Agent node's agentId setting names inside a flow. So there is just one human-facing id, the slug, used everywhere a flow or a client refers to the agent, and one row id used only by the admin console. Beyond identity, every agent carries two independent settings channels — runtime settings readable by your flow scripts, and partner-facing front settings delivered to partner sites — each capped at 1,000,000 characters. Agent lists stay fast no matter how large the settings grow.

Agent

A deployed flow entry registered inside one space. Fields: displayName, agentId (slug), startFlow, startNode, active, spaceId and timestamps. The flow itself is deployed to the space — the agent tells the platform where that flow starts.

agentId (slug)

The platform-wide-unique, kebab-case runtime identity — lowercase letters and single dashes only, no digits. Clients run the agent by this slug, never by the row id. Renaming it changes what a run request resolves to, immediately.

Row id vs slug

Admin pages address agents by the generated row id; running an agent uses the slug. Passing the row id where the slug is expected fails the run with agent not found in space.

Run entry

KeenAgents derives the flow entry point by dash-joining startFlow-startNode (for example MainFlow-Start). Both names are strict PascalCase with letters and digits only — a dash inside either name would corrupt the join, which is why dashes are forbidden.

Active flag

Boolean, defaults to true. KeenAgents refuses runs of an inactive agent — flipping the switch off takes an agent out of service without deleting it.

Agent Json Settings

The runtime channel: custom fields your flow scripts read at run time through the system/settings scripting resource. Saved on its own page, never delivered to partners.

Front Agent Settings

The partner channel: configures how the agent appears on the partner's site, delivered to partner integrations through the partner API and never exposed to scripts. A front save does not touch the agent record or the runtime settings.

• Display Name — required, 3–150 characters. The form only enforces non-empty + max 150, so a 1–2 character name passes the form and is refused on save.
• Agent ID — ^[a-z]+(-[a-z]+)*$: lowercase letters in single-dash-separated words, no digits, no leading/trailing/double dashes; 3–100 characters; unique across the entire platform. The input sanitizes as you type — uppercase is lowercased, digits and spaces never enter the field.
• Start Flow / Start Node — ^[A-Z][A-Za-z0-9]*$: strict PascalCase, letters and digits only, 3–60 characters each, no dashes — the run entry is derived by joining them with a dash, so an internal dash would corrupt it.
• Settings channels — max 1,000,000 characters each; the live counter in the editor mirrors exactly the limit enforced on save. Saving an empty value legitimately clears the settings.
• Settings write isolation — a general agent update can never modify settings: any settings value sent with it is ignored, and only the dedicated settings pages save them. This guarantees an agent edit can never accidentally overwrite a settings save.
• Field ids inside the settings — ^[a-z][a-z0-9]*(-[a-z0-9]+)*$ (kebab-case, digits allowed here, unlike the agent slug) and unique among the rows. Required is type-relative: 0 is a real number, false is a real boolean, but an untouched rich-text value (<p></p>) counts as empty.
• Per-space cap — an agent always belongs to exactly one space, and each space holds at most 10 agents (a per-space limit, not an organization-wide number). Past the cap a create is refused; need more, deploy into another space.
• Cascade — an agent belongs to exactly one space: deleting the space deletes its agents, and deleting an agent removes both of its settings sets with it. There is no orphaned-agent state and no undo.
• Errors — every failed agent operation returns a generic 406 Not Acceptable with no detail attached: a duplicate slug, an unknown id and a validation failure all look identical. This is deliberate — a probing caller learns nothing about what exists or why a request failed.

Both channels store a set of typed field rows — { displayName, fieldId, fieldType, required, value, valid }:

1. Pick the space — an agent cannot exist outside one. Arriving from a space's detail page pre-seeds the select via the ?space= URL parameter.
2. Type the Display Name; the Agent ID auto-fills as its kebab-cased form until you edit the ID by hand — after that the auto-follow stops for good, the slug is yours.
3. Enter Start Flow and Start Node — the run entry becomes StartFlow-StartNode (for example MainFlow-Start).
4. Submit. The same rules are validated in the form and again before the request leaves, and KeenAgents enforces slug uniqueness on save. On success the agent is immediately known across your organization and ready to run, the r_agent webhook notifies partner integrations, and the UI redirects to the new agent's detail page.
5. A client runs the agent by its slug: KeenAgents looks it up inside the requested space — not found in that space, or inactive, and the run is refused — then starts the flow at the derived entry.
6. Scripts inside the flow read the runtime settings as a flat {fieldId: value} map (valid rows only) through system/settings; front settings stay unreachable from scripts.

r_agent                   fires on agent create / update / delete AND on a runtime-settings save
r_agent_front_settings    fires ONLY on a front-settings save

delivery:  a notification POST {"synch-data":["<kind>"]} to every webhook URL your
           organization has configured; the body names WHAT changed, never the data —
           on receipt, fetch the fresh values through the API

• /agents — Agent Management landing, with cards leading to Create and List.
• /agents/list — space-scoped: a space picker at the top, and ?space=<id> in the URL is the source of truth (refresh, shared links and back/forward land on the same view); nothing is fetched until a space is chosen — there is deliberately no cross-space agent list. Columns: Display Name, Agent ID, Entry, Status (Active / Inactive) and a Visit link.
• /agents/create — the create form: required Space select, Display Name with slug-follow into Agent ID, input-level sanitization on the ID, and the PascalCase hint on Start Flow / Start Node.
• /agents/<id> — Agent Details: a cross-link card to the owning space, the Active switch (inactive agents are refused at run time), the Agent ID with copy-to-clipboard and the rename warning, Save gated on real changes (dirty check), and a two-step Delete (Delete → Confirm delete) returning to the space's agent list.
• /agents/<id>/json-settings and /agents/<id>/front-settings — one shared settings card per channel: the settings row builder (read-only row summaries; all editing happens in a Definition modal and a per-type Value modal), a valid/invalid badge, a live character counter ("N / 1,000,000 - allowed characters", red over the limit), and Update Settings enabled only when valid and under the limit and changed from the load-time baseline.
• /agents/<id> — a Rebuild Resource Cache button rebuilds this agent's served configuration on demand, a shortcut to the same action on the Cache page. It is gated by the cache permission (cache read, cache:w write), separate from the edit permission, so a cache manager can refresh it while an editor without cache rights never sees the button. You rarely need it — normal saves refresh the copy automatically. See Resource Cache.

The agent detail screen — display name, the agentId slug with copy, the run entry, the Active switch, and Save and Delete.

• The two settings channels are strictly isolated in both directions: front settings are never readable by flow scripts, runtime settings are never delivered to partner sites. A value on the wrong surface is silently invisible to its intended consumer.
• A front-settings save does not change the agent record, the runtime settings or the hasSettings flag — and it fires a different webhook kind. A partner watching only r_agent will never learn front settings changed.
• Consumers skip rows stamped valid: false. You can save a set containing invalid legacy rows (the editor blocks only new violations) — those rows simply never reach scripts or partners. If a field "isn't showing up" at run time, check its valid stamp first.
• Changing a field row's type in the definition modal resets that row's value to the new type's blank — the modal warns before you commit.
• Agent list responses never carry the settings themselves — only hasSettings: boolean, and it tracks the runtime channel only. The settings travel exclusively through their dedicated settings pages.
• The UI's minimum lengths are looser than the platform's on Display Name and Agent ID: a 1–2 character value passes the form but KeenAgents requires 3 and refuses with the generic 406.
• Clearing settings with an empty value never makes the agent look deleted — KeenAgents distinguishes "agent exists with no settings" from "unknown agent".