Skip to main content

​
Agent governance policies

A production agent needs four distinct governance controls, and Orbit ships one for each on different fields of the agent (or organization) record. Use them together: prompt guardrails bound what the agent says, budget caps bound what it spends, the model allowlist bounds which models it can resolve to, and the approval gate bounds who can promote a prompt change to production.

​
Prompt guardrails

Guardrails are part of the agent itself — set them under safety_config on create (POST /agents) or update (PUT /agents/:id). There is no separate guardrails endpoint.
  • prompt_injection — screens inbound user text for injection probes (prompt extraction, persona jailbreaks, encoding tricks) before the turn runs. An activated probe is refused instead of answered.
  • content_filter / harmful_content — blocks disallowed topic classes on the output.
  • blocked_topics — a tenant-defined denylist of subject matter (for example “refund policy changes”, “competitor pricing”). Anything in the list is refused.
  • pii_detection / pii_redaction — detects PII in inbound or outbound text and substitutes [REDACTED] before it is stored or shown.
  • pii_egress — scrubs the universal PII floor (email, phone, SSN, payment card) inside every tool call’s arguments at dispatch, so PII never leaves Orbit through a connector.
  • sensitive_words — a tenant-maintained word/phrase list that must never appear in output.
  • max_response_length — caps the assistant message length.
  • approval_required — suspends runs for human approval when set.
See Creating agents for the full safety_config field list, the Sensitive-words guardrail page for list management, and Guardrail effectiveness to measure how often each gate fires on live traffic.

​
Budget caps

Compose two families, both written per agent, that bound spend in two units: Dollar-denominated — hard caps the run refuses to cross:
  • max_cost_per_run_cents — aggregate cost of all LLM calls inside one run (one turn, tool-call iterations included).
  • max_cost_per_conversation_cents — lifetime cost of a conversation; probed before every LLM iteration, so a capped conversation refuses further turns.
Both accept 0–10000 cents; an exceeded cap ends the run with a final error event (COST_LIMIT / CONVERSATION_COST_CAP_REACHED). Full semantics in Agent cost controls. Token-denominated — a progressive ladder that steps the model down instead of hard-stopping:
  • config.token_budget — a per-conversation token allowance for this agent (1–1_000_000_000).
  • config.downgrade_ladder.daily_token_cap — the agent’s total tokens per UTC day.
  • config.downgrade_ladder.steps — up to ten { at_percent, model } rungs whose at_percent thresholds ascend strictly; each names an allowlisted model (see below). As daily utilization passes a threshold, new turns resolve to the cheaper model. A breached cap with no usable step reports the breach but keeps the primary model — an agent never resolves to an unvalidated id.
A bad shape (non-integer, out of bounds, unsorted thresholds, more than ten steps, or a non-allowlisted model) is rejected with 422 at create/update.

​
Model allowlists

Agent models resolve only from the served-Claude catalog. Every surface that names a model — the model field, config.model_fallbacks, config.model_routing, config.budget_downshift_model, and each downgrade_ladder.steps[].model — is checked against the allowlist:
  • Write boundaries (create/update agent, model-routing addresses) reject a non-allowlisted id with a 422 validation error.
  • Resolvers (model routing, fallback cascade, budget downshift, token-guardrail ladder) read with a defuse posture: a stored but no-longer-allowlisted override is ignored and the resolver falls back to a valid canonical model, logging a model_router.override_rejected metric. A stale override never routes a live turn to an unvalidated id.
Keep overrides pointed at the canonical served models; after a model retirement, an untouched legacy id on the agent row keeps working until you change it.

​
Separation-of-duties approvals

Saved agent versions move a prompt change from candidate to production through POST /agents/:id/versions/:vid/promote (or the prompt-rollback alias). By default anyone with write access may promote. Turn on the org gate so the operator who authored a version cannot also promote it — the author ≠ approver control SOC2/HIPAA change-management asks for on AI behaviour.
With the gate on:
  • The promoter must be a different authenticated user than the version’s author (the version row’s recorded creator). A self-promotion returns 403.
  • Auto-minted or API-key versions with no attributable author may be promoted — there is no identifiable self-promotion to block, and the audit row records the promoter.
  • Roles do not exempt anyone: an owner or admin who authored the version still cannot approve their own change.
  • Every promotion — allowed or blocked — lands in the agent audit chain, so the approval trail is reconstructable after the fact.
The gate is opt-in per organization and off by default; an org that never enables it sees no behaviour change. Pair it with Human-in-the-loop oversight for runtime approvals, which pauses sensitive tool calls for a human in the loop rather than gating prompt promotion.