guard_onboard_agent

Guard gives every AI agent a compliance boundary: stops budget overruns, blocks unauthorized tools, redacts PII, and enforces compliance frameworks (HIPAA/PCI/GDPR) -- without touching agent code. Before Guard: your n8n agent can call any model, spend any amount, and see all user PII. After Guard: every call is intercepted -- budget enforced, PII redacted, tools allowlisted. START HERE. Register an AI agent, compile guardrails, generate a cnk_* token, start a session. Success: you get agent_id + cnk_* token -- paste the token into your n8n HTTP Header and Guard enforces every policy on every call automatically from that point on. Returns: agent_id, token (cnk_*), session_id, guardrail_profile, confirmed_settings, defaults_applied. ROUTING — call guard_questionnaire FIRST if any of these apply: (a) org has compliance restrictions or policies you are unsure of (b) agent uses custom org MCP tool names (not standard n8n HTTP nodes) (c) you got a 409 or 422 error on a previous attempt guard_questionnaire returns: org_policy_restrictions (conflicts) + org_specific_tools (~30s). Skip guard_questionnaire when: standard n8n HTTP nodes, personal/dev org, no compliance frameworks. QUICK START: Absolute minimum (only required field): { "agent_name": "my-bot" } With safety controls (recommended): { "agent_name": "my-bot", "runtime": "n8n", "budget_usd": 25, "pii_mode": "flag", "allowed_models": ["gpt-4o-mini"] } COPY-PASTE PROFILES (pick the closest, change agent_name): Chatbot: { "agent_name": "my-chatbot", "runtime": "n8n", "budget_usd": 25, "pii_mode": "flag", "allowed_models": ["gpt-4o-mini"] } HIPAA: { "agent_name": "my-processor", "runtime": "n8n", "budget_usd": 10, "pii_mode": "redact", "blocked_tools": ["http_request","webhook_response","url_fetch"], "council_answers": {"C1": ["hipaa"], "C2": "yes"} } Creative: { "agent_name": "my-writer", "runtime": "n8n", "budget_usd": 50, "key_interception_enabled": false } (Full archetype details with HIPAA checklist further below) WORKED EXAMPLE (copy this, swap agent_name, you're done): Request: guard_onboard_agent({ "agent_name": "support-bot", "runtime": "n8n", "budget_usd": 25, "pii_mode": "flag" }) Response: { agent_id: "a1b2c3...", token: "cnk_1a2b3c4d5e..." } <- the Bearer token Next (2 steps): 1. Copy the token value: cnk_1a2b3c4d5e... 2. In n8n: HTTP Header Auth > Name: Authorization, Value: Bearer cnk_1a2b3c4d5e... Done. No other setup required. Guard now intercepts and enforces policy on every call. WHICH TOOL TO USE: Deploying now? -> guard_onboard_agent (this tool) Pre-provisioning in CI/CD? -> guard_register_agent (lazy session, +50-200ms first call) Custom org MCP tool names? -> call guard_questionnaire FIRST (get available tool list) Want to check org policy early? -> call guard_questionnaire (shows org_policy_restrictions) Got a 409/422 error? -> call guard_questionnaire, then retry onboard Revoke/delete/update an agent? -> guard_list_agents first (need agent_id) USING THE TOKEN: POST /v1/guard/chat/completions with "Authorization: Bearer cnk_a1b2c3..." (32-char token) In n8n: Settings > Credentials > HTTP Header Auth > Name: Authorization, Value: Bearer cnk_... PRE-CHECK: Using custom org MCP tool names (not standard n8n HTTP nodes)? -> Call guard_questionnaire FIRST to see org_specific_tools.available list. Then use those exact names in allowed_tools or blocked_tools below. COMMON ARCHETYPES (copy the one closest to your agent): Customer support / HR chatbot: { "agent_name": "support-bot", "runtime": "n8n", "budget_usd": 25, "pii_mode": "flag", "allowed_models": ["gpt-4o-mini"] } Invoice processor (HIPAA + no outbound HTTP): { "agent_name": "invoice-processor", "runtime": "n8n", "budget_usd": 10, "pii_mode": "redact", "allowed_models": ["gpt-4o-mini"], "blocked_tools": ["http_request","webhook_response","url_fetch"], "council_answers": {"C1": ["hipaa"], "C2": "yes"} } HIPAA CHECKLIST (all three required): [1] pii_mode:"redact" -- real-time PII stripping before LLM sees it [2] council_answers.C1:["hipaa"] -- compliance framework: 7-year audit retention [3] council_answers.C2:"yes" -- full content logging for HIPAA audit trail WHY ALL THREE -- pii_mode alone is NOT HIPAA-compliant: pii_mode:"redact" alone -> strips PII before LLM (no retention policy) + C1:["hipaa"] + C2:"yes" -> adds 7-year retention + audit trail (HIPAA) blocked_tools blocks HTTP at the tool level. These names are standard n8n names (no guard_questionnaire needed for standard HTTP blocking). Content / code / creative (no PII, unrestricted model): { "agent_name": "content-writer", "runtime": "n8n", "budget_usd": 50, "key_interception_enabled": false } Read-only analyst: add council_answers:{"T5":"read_only"} Untrusted-input agent: add council_answers:{"P1":"yes"} ACTIVE DEFAULTS (always on, even when council_answers is omitted): key_interception_enabled: true -- intercepts API keys in prompts. Set false for content/creative agents where users submit free-form text. audit_mode: metadata-only PII scanning: OFF unless pii_mode or D1 is set budget: hard-stop (429) at budget_usd WHEN TO CALL guard_questionnaire (skip it for simple agents): (a) You have custom org MCP tool names to allow or block (b) You need fine-grained council_answers keys beyond the archetypes above (c) You got a 422 error -- look up valid values for the named key (d) You got a 409 policy_conflict -- read org_policy_restrictions VERIFY CONFIG (no follow-up call needed): confirmed_settings -- echoes exactly the values you sent defaults_applied -- shows every setting the system auto-configured for you UPDATE LATER: guard_update_agent changes settings without losing token or history. ERROR ROUTING TABLE (scan before reading full detail below): CODE RETRYABLE POLL / RECOVER VIA DONE WHEN 400 yes fix field in error body, retry error gone 401 NO guard_list_agents -> revoke -> onboard new token works 403 yes retry guard_onboard_agent (backoff 1-4s) succeeds (not 403) 409 yes guard_questionnaire -> adjust -> retry org_policy clears 422 yes fix error.key with error.valid_values error gone 429 yes guard_update_agent(budget_usd higher) agent resumes 503 varies non-critical:backoff / compliance:STOP scanner online KEY: 403 polls = retry guard_onboard_agent 409 polls = call guard_questionnaire (NOT retry onboard) ERROR CODES (full detail): 400 -- bad request: missing or invalid field. (retryable: yes, after fix) Action: fix the field named in the error body. - agent_name missing (the only required field) - invalid type: budget_usd must be number, pii_mode must be "flag"|"redact"|"off" 401 -- bad or revoked token. (retryable: NO -- token is dead, do not retry same token) NO RETRY: get a new token immediately via: guard_list_agents → guard_revoke_token → guard_onboard_agent Match token_hint (first 8 chars of cnk_*) in guard_list_agents to find the agent. EXIT: test POST /v1/guard/chat/completions with new cnk_* token — done when 2xx. 403 -- council gate: agent NOT created, no token issued. (retryable: yes, after approval) Action: go to /dashboard/ai-company/council (browser only -- no MCP tool for submissions), submit the agent for review. POLL STRATEGY: retry guard_onboard_agent | backoff 1s→2s→4s | max 5 retries | give up → check /dashboard/ai-company/council (council approval typically takes 2-5 minutes; no separate status endpoint -- retrying IS the check) Returns token on success; returns 403 again if still pending or denied. (council gate is also enforced on guard_register_agent at registration time) 409 -- check error body: (retryable: yes, after fix) { "error_code": "already_exists" } Action: pick a unique agent_name and retry. { "error_code": "policy_conflict", "conflicting_keys": [...] } ---- POLICY CONFLICT RESOLUTION ---- POLL STRATEGY: guard_questionnaire every 5s | max 35 polls (175s ≈ 3 min) | give up → escalate with org_id 1. DIAGNOSE → guard_questionnaire (NOT guard_onboard_agent) Read: org_policy_restrictions.blocked_keys Example: { "blocked_keys":["C1"], "reason":"HIPAA not approved" } 2. REMEDY → Try weaker framework (least-to-most: soc2 < gdpr < pci_dss < hipaa) Example: hipaa blocked → C1:["pci_dss"] or C1:["soc2"] 3. GATE → No weaker option? → /dashboard/ai-company/council (admin unlock) 4. WAIT / POLL → guard_questionnaire every 5s, max 35 polls (35 × 5s = 175s ≈ 3 min) 5. VERIFY CLEARED → org_policy_restrictions.blocked_keys no longer includes the key EXIT: still blocked after 35 polls? → escalate to support with org_id 6. RESOLVED ✓ → Retry guard_onboard_agent with original params STOP: all frameworks blocked → no MCP retry possible. Admin unlock required. 422 -- invalid council_answers. (retryable: yes, after fix) Error body: { "error_code": "validation_error", "key": "C1", "valid_values": ["hipaa","gdpr","pci_dss","ferpa","soc2"] } Action: read error.key -- fix that key using the valid_values in the error body. Example: error.key="C1" -> set council_answers.C1 to one of the listed valid_values. If valid_values is missing: call guard_questionnaire, read .questionnaire.C1.valid_values. 429 -- budget exhausted; agent auto-paused. (retryable: yes, after raising budget) ACTION: guard_update_agent({ agent_id, budget_usd: <higher_value> }) EXIT: update call succeeds → agent resumes immediately. No polling required. 503 -- scanner temporarily unavailable; scans fail-open after 30s queue. (retryable: yes) Response body: { "error": "scanner_unavailable", "retry_after": 30, "scanned": false, "skip_reason": "scanner_unavailable" } (logged as scanned=false, skip_reason=scanner_unavailable; existing sessions unaffected) Action: Non-critical agents (chatbots, code writers, analysts without C1/C2 set): retry with backoff (1s -> 2s -> 4s). EXIT when response is 2xx. Compliance agents (agents with council_answers.C1 or C2:"yes" set -- HIPAA, PCI, GDPR): STOP immediately, alert operators. Do not allow unscanned calls under any circumstance.. It is categorised as a Destructive tool in the Clevername MCP Server, which means it can permanently delete or destroy data. Block by default and require explicit approval.

Register the Clevername MCP server in PolicyLayer and add a rule for guard_onboard_agent: allow, deny, rate-limit, or require approval. Point your MCP client at the PolicyLayer proxy URL and the rule is enforced on every call, before it reaches Clevername. Nothing to install.

guard_onboard_agent is a Destructive tool with critical risk. Critical-risk tools should be blocked by default and only enabled with explicit human approval.

Yes. Add a rate_limit block to the guard_onboard_agent rule in your PolicyLayer policy. For example, setting max: 10 and window: 60 limits the tool to 10 calls per minute. Rate limits are tracked per agent session and reset automatically.

Set action: deny in the PolicyLayer policy for guard_onboard_agent. The AI agent will receive a policy violation error and cannot call the tool. You can also include a reason field to explain why the tool is blocked.

guard_onboard_agent is provided by the Clevername MCP server (@clevername/clevername-mcp). PolicyLayer sits as a proxy in front of this server to enforce policies before tool calls reach the server.