Design: self-serve 'Harness' identity composer (bundle grants + token + install prompt + usage)

[ZdenekSrotyr]

Problem

Today, provisioning a machine/service consumer of Agnes (an external bot, a custom user-built AI agent, a CI integration — anything that isn't a human analyst logging in via Google/email) is an admin-only, CLI-driven process: create a group, add a service user, grant resources one by one via /admin/access, mint a PAT via agnes auth token create, hand-write setup instructions. There's no self-serve, guided flow for an analyst who wants to compose "a bundle of stuff for my own AI agent/bot" without going through an admin.

Naming note

Do not call this "Agent" in the UI — that word is already taken by the Store content type (a Claude Code subagent .md definition, see #865) and by "agent surfaces" (web chat/Slack/Telegram/MCP/CLI) in existing docs. Use "Harness" instead — it matches the product's own tagline ("Agnes — AI Harness") and reads unambiguously as "an external AI tool/bot that consumes Agnes," distinct from both existing senses of "agent."

Proposed flow (from user description)

1. User clicks something like "New harness" and names it (e.g. "my agent 1").
2. A catalog picker shows everything grantable — data packages, Store/marketplace skills, Store agents, possibly MCP connections — and the user attaches a subset.
3. Saving the harness bundles the selection, mints a token, and returns an install prompt (text the user pastes into their external agent/bot's startup so it self-installs Agnes access).
4. The user can later view usage — which of the attached resources the harness actually used, how much, etc. — on a per-harness dashboard.
5. Version pinning (confirmed in follow-up discussion): when a harness is created, it should freeze the current version of each attached resource rather than always tracking "latest." The owner gets an explicit "upgrade to latest" action per resource (or in bulk) rather than silently receiving new versions on next sync.

Why this is mostly reuse, not new infrastructure

Piece	Existing primitive to reuse
Catalog of grantable things	ResourceType enum + list_blocks delegates in app/resource_types.py — same data that powers /admin/access today
Bundle + identity	New lightweight concept: a "harness" = a hidden system group + a dedicated service user, created implicitly
Token	Existing PAT mint path (agnes auth token create --ttl … --raw), surfaced via a UI button instead of CLI
Install prompt	app/web/setup_instructions.py already renders this kind of "paste this into your client" content for human analysts — parameterize for a harness identity
Usage tracking	audit_log already supports per-user queries (count_for_user, etc. in src/repositories/audit.py) — filter by the harness's service-user id
Version pinning	Store entities already have version_no / version_history / promote_to_version (per-entity, owner-controlled "live" pointer) and curated marketplaces already have a ref (tag/SHA) pin (per-marketplace, admin-controlled). Both are global pins, not per-consumer. This needs a new per-harness join (e.g. harness_resource_pins(harness_id, resource_type, resource_id, pinned_version_no)) so a harness can freeze independently of what other installers/consumers see.

Open design question

Self-serve permission boundary: when a non-admin user creates a harness, can they only attach resources they themselves already have access to (safe, no new admin surface), or should they be able to request access to things they don't have yet (which would need an approval step, similar to the Store guardrails moderation queue)? This should be settled before implementation starts.

Related

• Add an Agent authoring domain to Studio #865 — Store agent Studio authoring domain (distinct, narrower scope; that's about publishing a subagent definition as content, this is about provisioning a consuming identity)

[ZdenekSrotyr]

Resolved the open design question: a self-serve harness can only be granted resources the creating user already has access to themselves. No new approval/admin surface in v1 — if broader "request access I don't have" support is wanted later, that's a separate follow-up, not part of this scope.

[ZdenekSrotyr]

Nav placement decision: for now, Harnesses gets its own global, top-level primary nav link (alongside Home/Chat/Marketplace/Data Packages/Library/Memory) — not tucked under /me/*, not in the Admin dropdown. Self-serve access rule from the earlier discussion still applies (a user can only attach resources they themselves already have access to); this comment is about where the nav link lives, not who can use it.

This is explicitly an interim placement. A broader nav reorganization is being discussed separately — likely consolidating into top-level sections like "My Stack" (which already exists as a tab inside /marketplace), "Catalogue", and something like "My Agents · Harnesses". Don't design this ticket's nav integration to be permanent; keep it simple to relocate once that larger redesign lands.

[ZdenekSrotyr]

Motivating use case: keboola/pr-reviewer-bot

This design thread started from a concrete integration question, not a hypothetical. pr-reviewer-bot (org-wide agentic PR reviewer) already has a precedent for pulling external content into its own agent: a cf-kit:<plugin>:<skill> reference syntax that team-authored POLICY.md files can use, resolved at review time by cloning keboola/cf-claude-code-kit into the Docker image at build time (pinned via a CF_KIT_REF build arg) and inlining the referenced SKILL.md body into the reviewer agent's system prompt (app/policy/cf_kit.py in that repo).

A Harness is the general-purpose version of exactly this pattern: instead of a bespoke build-time git clone hardcoded to one upstream repo, pr-reviewer-bot (or any other external harness) would create a Harness in Agnes, attach the skills/agents/data it needs, get a PAT, and consume /marketplace.zip (or .git) the same way an analyst's Claude Code does today — reusing existing distribution infrastructure instead of reinventing per-consumer plumbing. Per-team scoping (different pr-reviewer-bot profiles seeing different skill sets) maps naturally to one Harness per team/profile, each with its own grant set.

This should inform the "install prompt" deliverable: it needs to work not just as a human-facing "paste this into your Claude Code" block, but as something that translates into a non-interactive fetch step (Dockerfile build arg, CI secret, etc.) for a service consumer — the two have different constraints (a human can run an interactive OAuth-ish flow once; a build pipeline needs a pre-minted, headless-suitable credential, which is already how Agnes's existing PAT --ttl flow works — see docs/HEADLESS_USAGE.md).

Governance/versioning precedent (external research)

Researched during this design thread, not previously captured:

• Closest existing precedent: wshobson/agents — a multi-harness agent marketplace (single Markdown/YAML source generated into harness-native artifacts for Claude Code, Codex, Cursor, OpenCode, Copilot, Gemini CLI). Its explicit gap: no team-based access control, no per-org customization, no real versioning strategy. That gap is exactly what Agnes's RBAC + grants + version_no machinery already covers — validates building this as an extension of existing primitives rather than inventing a new generic multi-harness generator.
• No cross-vendor standard exists for the actual artifact (system prompt + tool allowlist + model choice). AGENTS.md (Linux Foundation, widely adopted) only standardizes project-level context, not portable subagent bundles — every harness still defines its own subagent schema. Conclusion: build Harness on Agnes's own schema; don't wait for or design around a cross-harness standard that doesn't exist yet.
• Governance pattern to model: Devin's Knowledge Base — team-local by default, explicit "Promote to Enterprise" action gates when something becomes canonical/shared, rather than admin review gating every day-to-day edit. Suggests: a user's own Harness content stays freely editable by them; promoting a Harness-attached Store agent/skill into the curated (group-RBAC) marketplace tier should be a distinct, explicit action — not automatic just because a Harness exists.
• Why centralize at all (real pain, not speculation): enterprises report agent inventory/ownership failure (projected 150,000+ agents at Fortune 500s by 2028, only 13% report adequate governance) and permission/prompt drift when teams independently rebuild the same agent with different tool permissions each time. This is the grounding for why Harness's RBAC reuse (vs. a bare "upload a bundle somewhere") matters.