Skip to content
apomesh

Agent configuration

An agent in apomesh is configured, not hard-coded. Everything that makes one agent behave differently from another — its prompt, its tools, its skills, its supervision, its context budget, its coordination loop — lives in a definition the orchestrator binds a session’s root agent to when the session starts. There is no separate “agent class” to write; you author a definition and the substrate runs it.

The plane owns those definitions in two modes, and the split between them is the whole design:

  • A working definition you edit live. It lives in your tenant’s mutable catalog, and starting a session against it resolves its configuration now — so an edit changes what the next start sees. This is the surface for iterating on an agent’s shape.
  • A published agent — a locked, versioned, sealed snapshot. Publishing freezes a working definition at a version you can name, share across a trust boundary, and reproduce exactly, forever.

Both modes describe the same kind of thing — an agent’s configuration — so the rest of this page is one vocabulary (the manifest) seen from two angles.

The two modes

Section titled “The two modes”
One manifest, two homes: the mutable working catalog you launch live from, and the immutable published registry a start consumes sealed.

Mode 1 — the working catalog. A working definition is an AgentManifest held in your tenant’s AgentCatalog. It is mutable: you create or replace it, delete an authored one, or reset one back to its shipped seed. Starting a session against it resolves the configuration live at dispatch — a start request may override parts of it, and the manifest fills in the rest. Full control at launch is the point.

Mode 2 — the published registry. Publishing promotes a working definition to a pinned (name, version) in the AgentRegistry — and it is a sealing act. The registry resolves the manifest’s whole asset closure (every referenced skill, pinned to its published version; the strategy-configuration lock) and seals it into a PublishedAssetBundle stored with the record. A start from a published agent consumes that sealed bundle exclusively — later edits to your catalog never reach it.

Why the split exists. The two modes serve opposite needs. A working definition gives you live control — edit and re-run. A published agent gives you a deterministic, shareable shape — the same (name, version) resolves to the same sealed configuration every time, for you or for another tenant you have allowed, without drifting when you keep editing your catalog. That reproducibility is what lets a published agent be handed across a trust boundary. It is also, directionally, what a future federation-facing agent card would project from — an agent has to be a locked, fully-configured shape before a protocol boundary has anything stable to bind to. That projection is roadmap work, not shipped today.

What a manifest binds

Section titled “What a manifest binds”

At a glance, one manifest names the whole shape of an agent:

  • Prompt — an operator system/user prompt plus versioned, revisable prompt fragments (composed by the context plane).
  • Tools — per-capability tool selections, each carrying a realization preference resolved at dispatch.
  • Skills — default skills composed into the agent at start, and per-role skill sets for progressive disclosure.
  • Coordination loop — the strategy the session runs under, either a declared skeleton or an addressable strategy-configuration lock.
  • Generation defaults — model and model allowlist, sampling, reasoning effort, output limits.
  • Context budget — the compaction default for the agent’s working-memory runway.
  • Supervision & gating — supervisor strategy, HITL triggers, the confirm-before-dispatch flag, and the VMAO replan/coverage caps.
  • The per-role plane — per-role overrides (planner, worker, validator, synthesizer) for model, tools, skills, memory scope, budget, and generation.
  • Context & provenance — memory-scope / placement / project bindings, and a ManifestSource recording whether the definition is a shipped seed, a config import, or operator-authored.

What a manifest deliberately does not carry is any secret. Provider keys and tool credentials never ride a manifest or a published bundle — they live only in the per-tenant credential plane and are resolved server-side at the sandbox boundary.

The sub-pages

Section titled “The sub-pages”
  • Manifests & launch — mode 1 in depth: the manifest’s full binding surface, provenance and re-import semantics, what upsert validates, the per-role configuration plane, and the launch-time composition precedence that resolves a start request against a manifest.
  • Published agents — mode 2 in depth: the registry’s immutability and cross-tenant visibility contract, publish-time sealing of the asset closure, the sealed bundle at start, exposure policy, versioning, and the two shipped Deep Research shapes as worked examples.

Guarantees

Section titled “Guarantees”
  • Live where you want it, frozen where you need it. A working definition resolves live at every start; a published version never changes.
  • A published start is immune to catalog drift. It reads only its sealed bundle, so edits to your working catalog after publish cannot alter a running or future pinned session.
  • Cross-tenant visibility is explicit and opaque. Every published entry carries a visibility scope; the one cross-tenant read path is audited server-side, and a caller who may not see an entry gets the same not-found as a genuinely-absent one.
  • Seeds and operator edits stay distinct. A shipped seed can be reset to; an operator override is never silently clobbered by a re-import.

Where this shows up

Section titled “Where this shows up”