From 5da208c0c5002139353110cc79733c223e4edeea Mon Sep 17 00:00:00 2001 From: Lev Neiman Date: Thu, 2 Apr 2026 12:46:37 -0700 Subject: [PATCH 1/2] docs: collapse action enums from 5 to 3 (deny, steer, observe) Update all documentation to reflect the consolidated action types. Legacy values allow/warn/log are now normalized to observe on input. --- concepts/controls.mdx | 14 +++++++------- concepts/evaluators/built-in-evaluators.mdx | 2 +- concepts/overview.mdx | 2 +- core/reference.mdx | 8 ++++---- examples/agent-control-demo.mdx | 4 ++-- examples/deepeval.mdx | 2 +- examples/langchain-sql.mdx | 6 +++--- examples/steer-action-demo.mdx | 17 ++++++++--------- integrations/crewai.mdx | 2 +- integrations/langchain.mdx | 2 +- integrations/strands.mdx | 4 ++-- 11 files changed, 31 insertions(+), 32 deletions(-) diff --git a/concepts/controls.mdx b/concepts/controls.mdx index dbd7292..a755a6d 100644 --- a/concepts/controls.mdx +++ b/concepts/controls.mdx @@ -282,18 +282,18 @@ Fields: - `decision`: The enforcement action to take - - `"allow"` - Continue execution (useful for allowlist controls) - - `"deny"` - Hard stop execution (blocks the request) - `"steer"` - Provides corrective guidance to help agents satisfy control requirement - - `"warn"` - Log a warning but continue execution - - - `"log"` - Log the match for observability only + - `"observe"` - Record the match for audit and observability without blocking execution - `metadata`: Optional additional context (JSON object) + + Legacy action values `allow`, `warn`, and `log` are still accepted on input but are automatically normalized to `observe`. + + ### Important: "Deny Wins" Semantics Agent Control uses "deny wins" logic: if **any** enabled control with a `deny` action matches, the request is blocked regardless of other control results. This ensures fail-safe behavior. @@ -308,12 +308,12 @@ Agent Control uses "deny wins" logic: if **any** enabled control with a `deny` a } ``` -### Example 2: Warn without blocking +### Example 2: Observe without blocking ```json { "action": { - "decision": "warn" + "decision": "observe" } } ``` diff --git a/concepts/evaluators/built-in-evaluators.mdx b/concepts/evaluators/built-in-evaluators.mdx index 3dc7cba..1d525dc 100644 --- a/concepts/evaluators/built-in-evaluators.mdx +++ b/concepts/evaluators/built-in-evaluators.mdx @@ -217,7 +217,7 @@ pip install agent-control-evaluators[galileo] } } -// Flag potential hallucinations (warn but allow) +// Flag potential hallucinations (observe, non-blocking) { "name": "galileo.luna2", "config": { diff --git a/concepts/overview.mdx b/concepts/overview.mdx index 16ccc31..a56a700 100644 --- a/concepts/overview.mdx +++ b/concepts/overview.mdx @@ -144,7 +144,7 @@ An **Action** defines what happens when a control matches. 2. **Steer second** — if any `steer` control matches (and no deny), steering context is returned. -3. **Allow/warn/log** — observability actions that do not block execution. +3. **Observe** — non-blocking observability action that does not affect execution. ## Learn more diff --git a/core/reference.mdx b/core/reference.mdx index 8fea6f1..46ad728 100644 --- a/core/reference.mdx +++ b/core/reference.mdx @@ -70,9 +70,9 @@ Controls → Agents |--------|----------| | `deny` | Block the request/response, raise `ControlViolationError` | | `steer` | Raise `ControlSteerError` with steering context for correction and retry | -| `allow` | Permit execution (no effect if a `deny` control also matches) | -| `warn` | Log a warning but allow execution | -| `log` | Silent logging for monitoring only | +| `observe` | Record the match for audit and observability without blocking execution | + +Legacy values `allow`, `warn`, and `log` are accepted on input but normalized to `observe`. Priority semantics: @@ -80,7 +80,7 @@ Priority semantics: 2. **Steer second** — if any `steer` control matches (and no deny), steering context is returned. -3. **Allow/warn/log** — observability actions that do not block execution. +3. **Observe** — non-blocking observability action that does not affect execution. You can read more in [Concepts](/concepts/overview) diff --git a/examples/agent-control-demo.mdx b/examples/agent-control-demo.mdx index 54c2c1a..3f33fab 100644 --- a/examples/agent-control-demo.mdx +++ b/examples/agent-control-demo.mdx @@ -104,7 +104,7 @@ Controls are defined on the server with: - Scope: When to check (step types, stages: pre or post) - Condition: What and how to check -- Action: What to do (allow, deny, steer, warn, log) +- Action: What to do (deny, steer, observe) Example from `setup_controls.py`: @@ -160,7 +160,7 @@ Controls can be updated on the server without code changes: - Enable or disable controls - Update patterns and rules -- Change enforcement decisions (deny to warn) +- Change enforcement decisions (deny to observe) - Add new controls to existing agents ## Configuration diff --git a/examples/deepeval.mdx b/examples/deepeval.mdx index 8bbcfb9..b6fa2f5 100644 --- a/examples/deepeval.mdx +++ b/examples/deepeval.mdx @@ -480,7 +480,7 @@ You can create specialized evaluators for specific use cases: 3. **Configuration**: Pydantic models provide type-safe, validated configuration 4. **Registration**: The `@register_evaluator` decorator handles registration automatically 5. **Integration**: Evaluators work seamlessly with agent-control's policy system -6. **Control Logic**: `matched=True` triggers the action (deny/allow), so invert when quality passes +6. **Control Logic**: `matched=True` triggers the action (deny/observe), so invert when quality passes ## Troubleshooting diff --git a/examples/langchain-sql.mdx b/examples/langchain-sql.mdx index 55566e2..93d5738 100644 --- a/examples/langchain-sql.mdx +++ b/examples/langchain-sql.mdx @@ -135,7 +135,7 @@ The SQL is evaluated using the `sql` evaluator: - Parses the query - Checks for blocked operations (DROP, DELETE, etc.) - Validates LIMIT clauses -- Returns deny/allow decision +- Returns deny/observe decision ### 4. Fail-Safe Error Handling @@ -200,11 +200,11 @@ Agent Control Server ↓ SQL Evaluator Execution ↓ -DENY (blocks DROP) or ALLOW (safe query) +DENY (blocks DROP) or PASS (safe query) ↓ Back to Decorator ↓ -Raise ControlViolationError (DENY) or Execute (ALLOW) +Raise ControlViolationError (DENY) or Execute (PASS) ``` ## Files diff --git a/examples/steer-action-demo.mdx b/examples/steer-action-demo.mdx index 8ac5999..73a66b6 100644 --- a/examples/steer-action-demo.mdx +++ b/examples/steer-action-demo.mdx @@ -1,18 +1,17 @@ --- title: Steer Action Demo -description: Banking transfer agent showcasing allow, deny, warn, and steer actions. +description: Banking transfer agent showcasing observe, deny, and steer actions. --- A realistic AI banking agent that processes wire transfers with compliance controls, fraud detection, and approval workflows. ## What This Demonstrates -This example shows all three AgentControl action types in a real-world banking scenario: +This example shows the three Agent Control action types in a real-world banking scenario: -- Allow: Auto-approve simple, low-risk transfers - Deny: Hard-block compliance violations (OFAC sanctions, high fraud) -- Warn: Log suspicious activity without blocking (new recipients) - Steer: Guide agent through approval workflows (2FA, manager approval) +- Observe: Record suspicious activity for audit without blocking (new recipients) ## Understanding Steer Actions @@ -26,7 +25,7 @@ Key difference from deny: ## Demo Flow ```text -Request Transfer → Steer Triggered → Correct Issue → Retry Transfer → Allow Success +Request Transfer → Steer Triggered → Correct Issue → Retry Transfer → Success ``` ## Quick Start @@ -75,11 +74,11 @@ Expected: ## What You Will Learn -- When to use deny vs warn vs steer actions +- When to use deny vs steer vs observe actions - How to integrate human feedback (2FA, approvals) into agent workflows - How structured steering context enables deterministic agent workflows - Real-world compliance patterns (OFAC, AML, fraud prevention) -- The steer to correct to retry to allow lifecycle +- The steer → correct → retry lifecycle ## How It Works @@ -89,7 +88,7 @@ The agent uses AgentControl to gate wire transfers through five controls: |---|---|---| | OFAC Sanctions | Deny | Destination is sanctioned country | | High Fraud | Deny | Fraud score > 0.8 | -| New Recipient | Warn | Recipient not in known list | +| New Recipient | Observe | Recipient not in known list | | 2FA Required | Steer | Amount >= 10,000 without 2FA | | Manager Approval | Steer | Amount >= 10,000 without approval | @@ -141,7 +140,7 @@ Key fields: ## Files -- `setup_controls.py` - Creates the five banking controls (deny, warn, steer) +- `setup_controls.py` - Creates the five banking controls (deny, steer, observe) - `autonomous_agent_demo.py` - Interactive agent with deterministic steer handling ## Source Code diff --git a/integrations/crewai.mdx b/integrations/crewai.mdx index c99928e..8d6f64d 100644 --- a/integrations/crewai.mdx +++ b/integrations/crewai.mdx @@ -30,7 +30,7 @@ Add guardrails without refactoring existing CrewAI crews. The decorator wraps yo Keep CrewAI's built-in guardrails for response quality and agent behavior, while Agent Control handles hard security enforcement at tool boundaries. **4. Production-grade compliance** -Built-in evaluators for PII detection, unauthorized access prevention, and custom business logic with deny/allow/steer actions. +Built-in evaluators for PII detection, unauthorized access prevention, and custom business logic with deny/steer/observe actions. ### Common Use Cases diff --git a/integrations/langchain.mdx b/integrations/langchain.mdx index aed166d..7057f8e 100644 --- a/integrations/langchain.mdx +++ b/integrations/langchain.mdx @@ -30,7 +30,7 @@ Add guardrails without refactoring existing LangChain code. The decorator wraps Choose server-side execution for centralized controls and audit logs, or SDK-local execution for offline operation and lower latency. **4. Production-grade safety** -Built-in evaluators for SQL injection, regex patterns, PII detection, and custom business logic with deny/allow/steer actions. +Built-in evaluators for SQL injection, regex patterns, PII detection, and custom business logic with deny/steer/observe actions. ### Common Use Cases diff --git a/integrations/strands.mdx b/integrations/strands.mdx index 73a3498..f7b97c0 100644 --- a/integrations/strands.mdx +++ b/integrations/strands.mdx @@ -68,7 +68,7 @@ AgentControlPlugin (before/after each stage) ↓ Agent Control Server ↓ -Hard Block (deny) or Allow +Hard Block (deny) or Observe ``` **Steering Pattern:** @@ -94,7 +94,7 @@ Strands Agent ↓ ↓ Steering Plugin (hard blocks) ↓ ↓ - Guide() Allow/Deny + Guide() Observe/Deny ↓ LLM Retry ``` From 6c8ca9e5cc5654c2072e40d44e8feb7673034461 Mon Sep 17 00:00:00 2001 From: Lev Neiman Date: Thu, 2 Apr 2026 12:52:18 -0700 Subject: [PATCH 2/2] docs: remove backward compatibility notes for legacy action values --- concepts/controls.mdx | 4 ---- core/reference.mdx | 2 -- 2 files changed, 6 deletions(-) diff --git a/concepts/controls.mdx b/concepts/controls.mdx index a755a6d..acb6b71 100644 --- a/concepts/controls.mdx +++ b/concepts/controls.mdx @@ -290,10 +290,6 @@ Fields: - `metadata`: Optional additional context (JSON object) - - Legacy action values `allow`, `warn`, and `log` are still accepted on input but are automatically normalized to `observe`. - - ### Important: "Deny Wins" Semantics Agent Control uses "deny wins" logic: if **any** enabled control with a `deny` action matches, the request is blocked regardless of other control results. This ensures fail-safe behavior. diff --git a/core/reference.mdx b/core/reference.mdx index 46ad728..71fe51c 100644 --- a/core/reference.mdx +++ b/core/reference.mdx @@ -72,8 +72,6 @@ Controls → Agents | `steer` | Raise `ControlSteerError` with steering context for correction and retry | | `observe` | Record the match for audit and observability without blocking execution | -Legacy values `allow`, `warn`, and `log` are accepted on input but normalized to `observe`. - Priority semantics: 1. **Deny wins** — if any `deny` control matches, execution is blocked.