Agent bundles
An agent bundle is an agent definition shipped with the application rather than authored by a member in Agent Studio. Bundles are how Kaizen's defaults and its purpose-built agents reach a deployment.
What a definition contains
| Field | Purpose |
|---|---|
| Name and description | Identity in the picker and roster |
| Mode | search or chat — determines which surface it appears on |
| Persona | Instructions and tone |
| Capabilities / tool grants | The ceiling of what it may use |
| Knowledge scope | Collections or sources it retrieves over |
| Sharing scope | Private, direct, or all members |
A definition is configuration, not authority. Its tool list is a ceiling; its knowledge scope narrows the runner's access and never widens it.
What a definition must not contain
This is the rule that keeps agents uniform:
Agent-specific code may define only genuinely domain-specific persona, capability, tool-grant, or source-selection behavior.
Never in a definition or an agent-specific code path:
- streaming behavior,
- journal projection,
- retries or timeout salvage,
- durability or recovery,
- grounding instructions,
- lifecycle handling,
- policy, budgets, or approvals,
- error handling,
- audit,
- compression or compaction,
- task management,
- history search.
All of those are the shared pipeline's job. An agent that implements its own version creates a corner of the product where behavior silently differs — and boundary tests exist to catch exactly that.
Versioning
Editing an agent appends a version; it never overwrites. The API exposes version listing, diffing between two versions, restore, and rollback.
Consequences worth designing around:
- a shared agent's recipients see the latest version;
- a task pins an exact target version, so improving an agent never silently changes a scheduled job;
- an audit question of the form "what was this agent when it ran?" has an exact answer.
Mode scoping
Every agent declares its mode. A search agent never appears in the Chat
picker and vice versa.
The retrieval mechanism is shared, so the two surfaces can behave differently without creating competing document, chat, or Project search authorities. Do not add a per-surface retrieval path to an agent; change the parameters instead.
Shared capabilities arrive automatically
Do not declare these in a bundle — every eligible chat agent receives them from the common runtime:
conversation_history_search— authorized prior-work discovery,list_available_agents— the member-safe roster,- owner-scoped task inspection and management,
- the compression settings projection.
Their scope, timeouts, result limits, and access checks apply uniformly. A bundle that reimplements one of them is a bug.
Sharing scopes
| Scope | Set by |
|---|---|
| Private | The author |
| Direct share (use / duplicate / edit) | The author |
| All members | Admin only |
A bundled agent intended as a default is published deployment-wide; that remains an administrator decision even for shipped bundles.
A bundle agent is provisioned protected. Its owner is the synthetic
bundle:<slug> principal, which no signed-in member can ever match, so
protection is what keeps the agent readable: a protected agent shows its
composed tools, its granted packages, and its collection and prompt counts on
the agent card, while remaining non-editable for everyone except an
administrator. Without it the card would report an agent with no tools at all
even though the runtime still grants them.
Showing a package tool on that card does not admit it to a durable room. Each
bundled package manifest must separately classify the exact tool under the
closed collaboration policy. The Software Engineer bundle classifies
hypa_read, hypa_grep, hypa_find, and hypa_ls as actor-bound reads, so
they execute only as the initiating participant and return the ordinary
sanitized projection. hypa_shell remains outside the collaboration policy
and therefore absent from shared-room runs. Do not assign a broad class to an
entire package merely because one of its tools is safe.
Skill-only adapters
A bundle may vendor a reviewed skill without vendoring the upstream execution
environment. The Ontology Builder is the reference: its package records the
Skills Library source and version, contributes the adapted skill body, graph
scene metadata, and a declarative artifact contract, but declares no executable
package tools. Kaizen's existing search, query_document, artifact
create/update, and owner-scoped read_artifact / edit_artifact
implementations remain the runtime capabilities.
When adapting a skill this way, remove instructions for unavailable substrate rather than leaving dead commands in model context. State the replacement boundary explicitly, preserve the source/version in package metadata, and add a bundle test that proves the package has no unintended tool surface.
The protected Demo Builder follows the same skill-only package pattern with
a focused trusted-backend platform adapter. Its offline package contributes instructions and a
theme, declares empty tools, mcp, and artifact_contracts collections, and
uses Kaizen's existing retrieval and Artifact writes. The primary outputs are a
kind=code, language=json Demo Blueprint and a paired kind=markdown
presenter runbook. Updates target the exact existing Artifact IDs so Kaizen
appends versions to the same roots. Artifact writes return a model-visible
reference containing the stable root ID, immutable version, and SHA-256 content
digest. Demo Builder waits for that result before writing the dependent runbook
and copies the binding fields verbatim.
The bundle does not add a Demo Builder flag, route, database object, service,
worker, frontend surface, or credential store. Kaizen owns the exact
kamiwaza-sdk==1.2.0 dependency and the closed inspect_kamiwaza and
manage_kamiwaza_demo adapters. Those adapters belong to the platform tool
family and are not granted by this bundle or by agent posture. Admin policy,
member conversation selection, and the selected agent's read/write capability
ceiling narrow them uniformly for every chat agent.
The adapter builds a client only from the current validated forwarded envelope;
no API URL or header reaches the package runner or pi sidecar. Without that
envelope, the tools are not wired and the agent produces an operator plan with
no live-state claim.
Keep this split when extending the workflow. New control-plane operations need source-reviewed schemas, capability classification, safe projection, boundary tests, and documentation in Kaizen. Do not add a generic SDK method/body escape hatch to the package. The current write surface intentionally supports only workroom, catalog-extension, model-download, model-deployment, and catalog-dataset operations. It requires preview digests on apply, reuses exact state, permits only an explicitly reviewed compatible workroom update, derives internal endpoints, and exposes no delete. Apply calls stage an exact request behind the shared write guard; only the signed member action endpoint can revalidate and commit it through the SDK.
Reuse SDK seeding behavior as an in-process library primitive behind that
Kaizen-owned contract. Do not depend on kamiwaza-cli: it is an operator
application with its own context/authentication lifecycle and human command
surface. Do not import argparse command handlers as domain services or shell
out and parse their output.
The same boundary covers managed AWS S3 and Cloudflare R2 sources. A governed tool may return bounded, versioned coverage; the skill package never receives object-store credentials or direct network authority. Optional UAT output is a draft handoff for another system, not a runner, verdict, approval, or release gate.
Authoring agents
Two agents are treated specially: the Agent Builder and the Package Creator.
Their shared owner-scoped reads are list_studio_proposals and
get_package_proposal. Agent Builder additionally receives
get_agent_proposal, draft_agent, patch_agent_proposal,
resume_agent_proposal, and
submit_agent_proposal. Package Creator receives draft_package,
patch_package_proposal, patch_package_files, test_package, and
submit_package_proposal. These tools are registered only for the two
source-defined authoring agents, and only when conversational Studio authoring
is enabled.
The Package Creator handoff contains a proposal ID plus the reviewed package name and exact ref; it never contains a registry grant or approval. Agent Builder may persist that handoff as a same-owner dependency, but cannot submit or approve around it. Resume rechecks the approved proposal against the active registry before replacing the dependency with a package grant.
This authoring lane creates member proposals. It must not mutate a bundled agent definition or make a protected bundle member-editable. Demo Builder, Ontology Builder, Agent Builder, and Package Creator remain source-controlled; changes to their personas, grants, or bundled skills ship through the normal code-review and bundle-reconciliation path.
Do not grant studio tools to a general-purpose agent.
Delegation
invoke_agent is a tool like any other. Granting an agent the ability to
delegate does not opt any member in — sub-agent selection is per member and
per agent, and defaults to none.
A delegated turn inherits the caller's permissions and budgets and cannot exceed the calling agent's capability ceiling.
Testing a bundle
- Does it appear only on its declared mode's surface?
- Does it behave identically to a member-authored agent for everything the shared pipeline owns — streaming, retries, compaction, audit?
- Is every granted tool actually needed?
- Does it degrade correctly for a member whose permissions do not cover its knowledge scope? (Fewer results — not an error that reveals what is missing.)
- If it grants a dynamic platform server, does the exact server selector remain narrow, deployment-enabled, and harmless when discovery returns nothing?