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/delegate1. Create and publish an agent in Console
- Open Console → Build → Agents and click New Agent. Set a display name and a kebab-case
slug(for example,close-reconciliation). - Paste explicit numbered rules, escalation thresholds, and required output columns into System Instructions.
- Attach only the Knowledge Collections and Tools this specialist requires, and set Writes to
require-human-approval. - 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.
| Field | Type | Required | Behavior |
|---|---|---|---|
| slug | string (kebab-case) | Yes | Stable identifier used by @nunc/sdk, nunc_delegate_<slug>, and Slack @mentions (e.g. close-reconciliation). |
| systemPrompt | string | Yes | Domain charter, fiscal/reporting rules, escalation thresholds, and required output format. |
| knowledgeIds | string[] | No | Workspace knowledge collections the agent may query (Public, Company, or Workspace tiers). |
| tools | string[] | Yes | Allowlisted connectors or built-ins (e.g. sage_intacct, outlook, snowflake_sql). Intersected with caller PBAC. |
| writes | "block" | "require-human-approval" | "allow" | Yes | Default 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
| Error | Cause | Fix |
|---|---|---|
| 403 agent_tool_denied | The 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_published | The 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_required | The 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