Docs/Configure Private Agents
Private Agents & @nunc/sdkConsole Setup · MCP Delegate · SDK Reference

Configure Private Agents

Create specialist agents in Console with scoped instructions, knowledge, and least-privilege tools, then invoke them from Data Studio, Slack, external MCP clients (/mcp/delegate), or @nunc/sdk.

https://api.nunc.cloud/mcp/delegate

1. Create and publish an agent in Console

  1. Open Console → Build → Agents and click New Agent. Set a display name and a kebab-case slug (for example, close-reconciliation).
  2. Paste explicit numbered rules, escalation thresholds, and required output columns into System Instructions.
  3. Attach only the Knowledge Collections and Tools this specialist requires, and set Writes to require-human-approval.
  4. Test a sample prompt in the right-hand Playground, inspect the Guardian trace, and toggle Published to expose the agent across Studio, Slack, /mcp/delegate, and @nunc/sdk.
You are the Q4 Close Reconciliation Agent for Northstar Health.
1. Query read-only Sage Intacct GL entries and Snowflake bank settlements.
2. Flag any variance > $250 or missing invoice attachment.
3. Never modify posted ledger entries directly; propose a draft journal entry for human approval.
4. Output a Markdown summary table with: Account, Variance, Root Cause, and Approval ID.

2. Agent configuration fields & PBAC intersection

Invoking an agent never escalates caller permissions. At runtime, Nunc enforces effective_tools = agent.tools ∩ caller.pbac_permissions.

FieldTypeRequiredBehavior
slugstring (kebab-case)YesStable identifier used by @nunc/sdk, nunc_delegate_<slug>, and Slack @mentions (e.g. close-reconciliation).
systemPromptstringYesDomain charter, fiscal/reporting rules, escalation thresholds, and required output format.
knowledgeIdsstring[]NoWorkspace knowledge collections the agent may query (Public, Company, or Workspace tiers).
toolsstring[]YesAllowlisted connectors or built-ins (e.g. sage_intacct, outlook, snowflake_sql). Intersected with caller PBAC.
writes"block" | "require-human-approval" | "allow"YesDefault write gate mode. Use require-human-approval for ERP, CRM, email, or billing mutations.

3. Invoke from Claude / Cursor (MCP) or TypeScript (@nunc/sdk)

On /mcp/delegate, every published agent is exposed as nunc_delegate_<slug> alongside nunc_delegate, nunc_delegate_status, and nunc_delegate_stop:

MCP JSON-RPC call (/mcp/delegate):
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "nunc_delegate_close_reconciliation",
    "arguments": {
      "goal": "Reconcile October Bill.com payables against Sage Intacct GL 2000.",
      "workspace_id": "finance-close",
      "wait_seconds": 15
    }
  }
}
TypeScript SDK (@nunc/sdk):
import { NuncClient } from "@nunc/sdk";

const nunc = new NuncClient({
  tenantUrl: process.env.NUNC_TENANT_URL!,
  apiKey: process.env.NUNC_API_KEY!,
});

const session = nunc.asExternalUser("acct_northstar_42", {
  workspace: "finance-close",
  guardianPreset: "medium",
});

const run = await session.agents.run({
  agent: "close-reconciliation",
  prompt: "Reconcile October Bill.com payables against Sage Intacct GL 2000.",
  tools: ["sage_intacct", "bill_com", "snowflake_sql"],
  sandbox: { runtime: "python", network: "air-gapped" },
  writes: "require-human-approval",
});

console.log(run.status, run.output);

4. Troubleshooting

ErrorCauseFix
403 agent_tool_deniedThe agent manifest includes a tool the calling user is not permitted to use under PBAC.Grant the user or group access in Console -> Organization -> Access, or remove the tool from the agent.
404 agent_not_publishedThe agent is still in Draft state or the slug does not match.Open Console -> Build -> Agents, verify the slug, and toggle Published = ON.
409 approval_requiredThe agent attempted a mutating write while writes = require-human-approval.Approve or reject the pending write in Console -> Trust -> Security or your Slack approval channel.

Related: @nunc/sdk Reference · Workflows & Scheduled Playbooks