Skip to main content

Named agents

A named agent is a scoped configuration. You bind a subset of MCP servers, tools, and skills. You set the NHI tier, required permissions, model, system prompt, guardian id, and max iterations. The chat can target a configured agent from the composer.

A named agent is a scoped configuration​

The center cell is the agent identity: a name and a description. The eight surrounding cells are the scope axes. An agent with no binding rows behaves identically to the org-wide default. Fail-open.

Why create one​

A few examples:

  • Compliance agent. Scoped to read-only risk and audit tools. Required permissions: risks:read, audit:read. NHI tier 1 (constrained). A regular chatter can run it without fear of a write slipping through.
  • Refund agent. Scoped to a Zendesk MCP server and a refund-policy skill. Tools allow the refund tools, deny the delete tools. Max iterations capped low. The agent can resolve refunds within policy, nothing else.
  • Ops agent. Scoped to the ops MCP servers. NHI tier 2 (supervised) for the destructive tools. A higher tier for the autonomous runs. The agent can run ops, but the destructive calls still confirm-gate.

The scoping is per-conversation. Pick the agent from the composer's agent selector pill, and the run filters tools, servers, and skills to that agent's scope. The selector is sticky across turns until you change it or clear it back to the org-wide default.

The nine axes​

  1. MCP servers. The server ids this agent may call. Empty means no restriction (the org-wide catalog). Non-empty means allowlist, only these servers.
  2. Tools. Per-tool allow or deny. Deny wins on conflict. Empty means no tool restriction.
  3. Skills. The skill ids this agent may invoke. Empty means no restriction. Non-empty means allowlist.
  4. NHI tier. Tier 0 (observe), tier 1 (constrained), tier 2 (supervised), tier 3 (autonomous). The bound non-human identity's privilege tier gates which tools the agent can reach.
  5. Required permissions. RBAC permissions a caller must hold to run this agent. Empty means any authenticated caller in the org can run it.
  6. Model. An optional inference model override. Absent means the loop default.
  7. System-prompt override. Prepended to the loop's base system prompt. Give the agent a persona or task framing.
  8. Guardian id. An optional guardian bundle id for receipt-minting lineage.
  9. Max iterations. An optional loop iteration cap. Overrides the org default when lower.

The fail-open contract​

The resolved scope carries four sets: a tool allowlist, a tool denylist, a server allowlist, and a skill allowlist. An undefined set means no restriction in that dimension. A defined set means restrict to that set.

An agent with no binding rows returns all-undefined. The loop behaves identically to today. No filtering. Boot never crashes on the minimal posture.

An agent with bindings returns defined sets. Only the bound tools, servers, and skills surface. Deny wins. The enforcement happens in three places: the context assembler (what surfaces in the prompt), the bridge (what dispatches at runtime), and the external-SDK executor gate (what external tools reach). A forked continuation preserves the original run's agent scope. A forked continuation cannot escape the original agent's allowlists.

The agent selector in the composer​

A compact pill in the composer controls row. Shows the current agent (or "Org-wide default"). A popover lists configured agents plus an "Org-wide default" reset.

The tooltip when scoped: "Scoped to agent: name. The run filters tools, MCP servers, and skills to this agent's scope."

The tooltip when default: "Org-wide default agent (no scoping). Click to scope the run to a configured agent."

Gating: managing agents requires the agents:manage permission and the mcp_governance entitlement. Running an agent requires agent:run and the agent_run entitlement. The two are deliberately distinct so a regular chatter cannot mint or re-scope a named agent.

Where to go next​

  • Chat shell for the composer, the agent selector pill, and the settled turn anatomy.
  • Inline UI for the rich components a scoped agent can mount in a turn.
  • Receipts for the hash chain that records every step a scoped agent took.
Last updated on