Agent templates: Agents tab and registry

The Navin products (Navin Enterprise RAG Agent first, then Compliance & Audit, Customer Operations, Fraud and Business Analytics) reach the Manager as agent templates (Service Templates). A template describes a product: its name, publisher, version, status and the catalog service that installs it once published. It is not a catalog service by itself. The registry also lists the agents that have no template yet (planned or in development), so that the progress of the whole platform is visible.

The Agents tab of the Services page

The Services page of a cluster shows the Agents tab as soon as the registry holds at least one agent (address /services?tab=agents). The tab lists every agent of the platform, built or not, as cards grouped by sector: Banking, Insurance, Cross-industry, Industry and Retail. Inside a group, the agents that have a template come first, then the agents in development, then the planned ones.

• Header: a search box (accent-free, it also reads the status label), one filter per sector with its count, and three counters: agents, templates ready to validate, published.
• Card: icon and colour of the sector, short name (never the brand), one sentence, the version (once the agent has a template), a status (Published, Awaiting validation, In development or Planned) and the Deploy button. Details opens the full description, the reason the agent cannot be deployed, then the components, the catalog service and the documentation the agent has. The card of a planned agent is dashed.
• Published agent: Deploy opens the install wizard of the cluster with the catalog service already selected (/clusters/<cluster>/install?service=<service>). The installation then follows the usual path (machines, parameters, dependency review).
• Agent awaiting validation: an administrator sees the Validate and publish button next to Deploy (see below). Other users see Deploy disabled with the reason.
• Any other agent: the button is disabled and the reason is shown in the tooltip of the button and in the details. Nothing can be installed before the template is built, validated and published.

Agents are prepared by Navin and can be deployed only once validated and published. Every signed in user sees the tab; deploying needs the services:install permission on the cluster, like any installation; validating and publishing needs agent_templates:publish (administrator role).

Validating and publishing a template

Publishing is the decision of the customer: it is taken in the Agents tab, never by a manual copy into the catalog. On the card of an agent Awaiting validation, the administrator clicks Validate and publish; a dialog recalls the catalog service, the version and the components, then Publish:

1. The Manager reads the sources of the template (the product manifest named by source in the registry, relative to agent_sources_dir, and the service definition it points to).
2. It loads the whole catalog with that definition on a staging copy: every check of the catalog loader (schema, licence, modes, components, Jinja templates present, dependencies). A single problem refuses the publication (422 agent_template_invalid) and the dialog shows the list; nothing is written.
3. It copies services/<service>.yaml and templates/<service>/ into published_templates_dir (/var/lib/navin-manager/published-templates in a package), records the publication (version, who, when) and audits it (agent_template.publish). The catalog of catalog_dir is never modified.

The card turns Published at once and Deploy becomes active for every cluster. The details say who published the template and when, and offer Withdraw the publication: the service leaves the catalog of this Manager and the agent is awaiting validation again (agent_template.unpublish). The withdrawal is refused while an instance of the service is installed in a cluster (409 agent_template_in_use).

The button does not show when publishing is impossible, and the details give the reason: planned or in development agent (no template yet), sources absent from this Manager, service definition that does not follow the catalog schema (the product must fix it; the number of problems is given), or service already shipped with the catalog.

The registry

The registry is the directory navin-manager/agent-templates of a checkout, or /usr/share/navin-manager/agent-templates in a package (setting agent_templates_dir, variable NM_AGENT_TEMPLATES_DIR). It holds one YAML file per agent, validated against its schema.json at load: identifier (equal to the file name), name and description in French and English, publisher, sector, short name and summary (copied from the product manifest) and a status.

Status	Label	Meaning	Fields
planned	Planned	Specified, nothing built	no version, no catalog service, no components
in_development	In development	Being built, no template yet	as planned
prepared	Awaiting validation	Template built, never deployable	version, catalog service, documentation, sources and components required
published	Published	Validated by the customer	as prepared

The schema refuses a version, a service or components on an agent that has no template, and demands all of them on a prepared or published one. An invalid descriptor prevents the registry from loading and the problem is listed in the error. The server reads the registry again as soon as one of its files changes, so an agent added or edited shows up without a restart.

The Manager marks an agent published only when two conditions hold: its service exists in the loaded catalog (shipped catalog plus the templates published on this Manager) and the template was published, either by the release (registry status published) or by an administrator from the Agents tab. Every other agent carries the reason of its status ("Not published, awaiting validation", "Under development, no template to validate yet" or "Planned agent, not developed yet"). Publishing a template is an explicit decision of the customer: nothing is copied into the catalog before that validation.

The API

Reading is open to any signed in user like the stack catalog; publishing needs the agent_templates:publish permission:

Operation	Role
GET /api/v1/agent-templates	List of the templates (items, count), with published, reason, publication, publishable and publish_blocker
GET /api/v1/agent-templates/{template_id}	One template by identifier; 404 (agent_template_unknown) when unknown
POST /api/v1/agent-templates/{template_id}/publish	Validates and publishes the template on this Manager; 409 (agent_template_not_publishable, agent_template_sources_missing, agent_template_already_published) or 422 (agent_template_invalid, problems in details.problems)
DELETE /api/v1/agent-templates/{template_id}/publication	Withdraws the publication; 404 (agent_template_not_published) or 409 (agent_template_in_use)

The Python, TypeScript, Go and Java SDKs expose these operations in the agent_templates / agentTemplates group. Errors follow the normalized format of the Manager (error.code, error.message, error.message_i18n).