Manifests & launch

A working definition is an AgentManifest held in your tenant’s AgentCatalog. This page is mode 1 in depth: the manifest’s binding surface, how a definition’s provenance survives a re-import, what the catalog validates when you save one, the per-role configuration plane, and the precedence that resolves a start request against a manifest at launch. For the two-modes overview, start at Agent configuration.

What a manifest binds

A manifest is one operator-authored record that names the whole shape of an agent. Grouped by what each axis controls:

Axis	Binds
Identity	A stable manifest id, a display name, a description, tags.
Prompt	An operator system/user prompt, plus versioned, revisable prompt fragments — each fragment carries a monotonic version per label and server-stamped authorship.
Tools	Per-capability tool selections, each pairing a capability with a realization preference (native substrate tool, MCP-delegate round-trip, or provider-native server-side tool) resolved at dispatch.
Skills	Default skills composed into the agent at start, drawn from the tenant’s skill registry.
Coordination loop	Either a declared skeleton (SessionKind) or an addressable strategy-configuration lock that beats the skeleton when set — see Coordination loops.
Generation	A default model, an allowed-model list, and defaults for sampling, reasoning effort, max output tokens, and response format.
Context budget	A compaction default for the agent’s working-memory runway (the context plane).
Supervision & gating	A supervisor strategy, HITL triggers, a confirm-before-dispatch flag, and the two distinct VMAO caps (replan iterations and coverage iterations).
Per-role plane	Per-role overrides for planner, worker, validator, and synthesizer (below).
Context bindings	Memory scope, placement, and the procedural / semantic / episodic space bindings that anchor the agent’s memory.
Provenance	A ManifestSource recording where the definition came from (below).

Prompt fragment authorship is resolved server-side from the caller’s identity, never trusted from the request — the same rule the identity & authorization plane enforces everywhere. And no secret is ever a manifest field: credentials live only in the credential plane.

Provenance and re-import

Every manifest carries a ManifestSource that records its origin, in a fixed precedence — a shipped seed the substrate provides, a config import from a declarative bundle, or an operator-authored definition. The order is load-bearing: operator intent outranks a config import, which outranks a shipped seed.

That ordering is what makes re-import safe. Re-importing a config bundle drops the tenant’s prior config-imported rows and re-applies the incoming ones — but it skips any id an operator has since authored over. An operator override is never silently clobbered by a re-import; the import writes around it. The catalog operations reflect the same principle:

• Upsert creates or replaces a manifest.
• Delete removes an operator-authored manifest, but refuses to delete a shipped seed.
• Reset restores a shipped seed, discarding an operator override — the one operation that overwrites operator-authored state, and only as an explicit operator action, never as an import side effect.

Note

A working catalog is a seed baseline that each tenant diverges from: the list a tenant sees is the shipped seeds it has not deleted, minus the ones it shadowed, plus its own upserts.

What upsert validates

Saving a manifest validates its shape and its skill references — not every downstream binding:

• Structural — the id and display name must be non-empty, and each prompt fragment’s versions must be monotonic within its label.
• Skill references — every default skill id must resolve in the tenant’s skill registry; an unknown id is rejected at save time.

Tool selections are not checked against a tool catalog at save time — a tool realization is resolved at dispatch with warn-and-degrade: a preference the bound provider can’t honor falls back to a lower-fidelity realization rather than failing the save or the start. This keeps a manifest portable across providers whose tool surfaces differ, and it is the deliberate contrast with a published agent, where the whole asset closure is resolved and sealed up front (Published agents).

The per-role configuration plane

A session’s coordination loop runs a small set of roles — a planner, workers, validators, a synthesizer. The per-role plane lets a manifest tune each role independently instead of applying one uniform configuration to all of them. A manifest carries a default role config with an optional entry per role, and each entry overrides only the axes it sets:

Role axis	Controls
Model	The model that role’s dispatches use.
Tools	The role’s tool allowlist (empty inherits; a non-empty set overrides).
Skills	The role’s skill set — the substrate for progressive disclosure, so a validator sees a different toolset and instructions than a worker.
Memory scope	How much of the session’s memory the role may read.
Budget	A per-role resource ceiling.
Generation	Per-role sampling, reasoning effort, output limit, and response format.
Sharing	Episodic-memory sharing mode and the semantic-confer relevance floor.

The role plane is substrate-general vocabulary. Domain-specific tuning that isn’t one of these axes — for example Deep Research’s coverage-strictness or citation-strictness knobs — is not a role-config field; it rides the opaque per-session vertical-config carrier the substrate ferries but never interprets, and is owned by the vertical. See Deep Research for how a vertical reads its own config.

Launch-time composition

Starting a session against a catalog agent resolves its configuration live, folding the start request over the manifest over a substrate default. Each axis resolves independently, request-wins:

Rendering diagram…

Live launch resolves each axis request → manifest → default; the resolved values are then pinned to the session's first event.

• Model — the request’s model wins, else the manifest’s default model, else the role tier’s model. A request model must be in some catalog agent’s allowed-model list, or the start is rejected.
• Operator prompt — the request’s operator prompt wins, else the manifest’s (blank values are filtered out at both decode and use).
• Compaction — the request’s config wins, else the manifest’s, else the substrate’s compiled default.
• Coordination loop — resolved by a fixed precedence: an explicit strategy-configuration reference, then the manifest’s strategy lock, then an explicit session kind, then the manifest’s declared kind. The strategy plane owns this chain — see Coordination loops.
• Per-role config — a request’s per-role value merges over the manifest’s per-role default field by field, so a manifest role pin resolves with per-role specificity rather than being flattened by a uniform request value.

Because resolution runs at every start, editing the manifest changes what the next start composes. That live behavior is exactly what publishing removes.

What the console reflects

The operator console’s Configure & launch surface is a direct reflection of this plane: it opens the four coordination roles as tabs and exposes each role’s model, tools, skills, and generation knobs, building the same per-role config the launch fold consumes. Editing a manifest, its prompt fragments, its tool selections, and reviewing the revision trail all happen there — see the operator console.

Live resolution, then a pin

A live start resolves skills and generation defaults from the registry at start and then pins the resolved shape — the composed skills, the resolved coordination kind and strategy reference — into the session’s durable first event. A resume re-reads that pin instead of re-resolving, so a session recovered after a restart runs the same agent it started with, even if the working catalog changed underneath it in the meantime. The determinism mechanism is owned by the sessions plane — see Reconstruction & recovery.

Where this shows up

• Operate: the operator console is the manifest editor and the Configure & launch surface.
• Build: Deep Research is a worked configured agent, and the home of the vertical-config tuning that sits beside the role plane.
• Reference: apomesh-substrate-catalog owns the catalog primitive; apomesh-orchestrator owns the launch composition.