Skip to content

Commit f2e1211

Browse files
apetraru-uipathapetraru-uipath
committed
feat: decorator guardrail implementation [AL-288]
Add stage parameter to pii_detection_guardrail and prompt_injection_guardrail decorators, matching the flexibility already available in deterministic_guardrail. pii_detection_guardrail defaults to PRE_AND_POST; prompt_injection_guardrail defaults to PRE and raises pydantic.ValidationError for POST or PRE_AND_POST (prompt injection is input-only). Fix _apply_llm_input_guardrail and _apply_guardrail_to_message_list: previously concatenated the full conversation history and tried to replace the joined text inside a single message, which silently failed in any multi-turn conversation. Now evaluates only the last HumanMessage (PRE/input) or last AIMessage (POST/output) — semantically correct and replacement works reliably. Replace _extract_text_from_messages with focused helpers: _get_last_human_message, _get_last_ai_message, _extract_message_text, _apply_message_text_modification. Add target_type parameter to _apply_guardrail_to_message_list so input and output graph-scope wrappers target the correct message type. PII decorator, joke-agent-decorator sample, BlockAction uses AgentRuntimeError. Fix _wrap_llm_with_guardrail: factory functions returning BaseChatModel were not wrapped (fell through StateGraph/dict branches). Also fix Pydantic setattr block on UiPathChat by using __class__ swap to a dynamic subclass instead of monkey-patching invoke/ainvoke. Fix BlockAction swallowed by bare except: split try/except so only guardrail API errors are suppressed; action exceptions (AgentRuntimeError) now propagate. Fix CompiledStateGraph not recognised: add _wrap_compiled_graph_with_guardrail and handle CompiledStateGraph return type from factory functions. Fix mypy errors in decorators.py: typed list[BaseMessage], CompiledStateGraph type params, type: ignore[valid-type, misc] for dynamic subclass, and type: ignore[method-assign] for CompiledStateGraph method patching. Add prompt_injection_guardrail decorator: _create_prompt_injection_guardrail, _apply_prompt_injection_guardrail, public prompt_injection_guardrail function; exported from guardrails/__init__.py; stacked on create_llm() in joke-agent-decorator/graph.py with BlockAction to block on detection. Reformat decorators.py for consistency. Middleware cleanup: delete monolithic middleware.py (duplicate of middlewares/ split files); update guardrails/__init__.py to import from .middlewares; update joke-agent/graph.py to use new split-file API (tool_names -> tools, optional scopes on PromptInjection, unconditional POST filter comment). Revert renames: restore LoggingSeverityLevel as proper int Enum (ERROR, INFO, WARNING, DEBUG) in actions.py; remove PromptInjectionValidatorType from enums.py; fix pii_detection.py docstring to use Entity+PIIDetectionEntity; export LoggingSeverityLevel from guardrails/__init__.py; update both samples to use LoggingSeverityLevel instead of AgentGuardrailSeverityLevel. Manual refinements: updates to actions.py, decorators.py, enums.py, models.py, middlewares/pii_detection.py, guardrails/__init__.py, and joke-agent/graph.py. Remove joke-agent/.agent/REQUIRED_STRUCTURE.md; further manual edits to joke-agent/graph.py. Refactor decorators.py into decorators/ package (pii.py, prompt_injection.py, deterministic.py, _base.py) with tool-level guardrail support: - Split monolithic decorators.py into decorators/ subpackage - Add _wrap_tool_with_guardrail using __class__ swap (Pydantic-safe) - Add deterministic_guardrail decorator (TOOL scope, local rules, no API call) - Extend pii_guardrail to support BaseTool and optional tools= kwarg - Extend _detect_scope to return GuardrailScope.TOOL for BaseTool instances - Export deterministic_guardrail and RuleFunction from guardrails/__init__.py - Update joke-agent-decorator/graph.py to demonstrate all three decorator types on analyze_joke_syntax tool (3x @deterministic_guardrail + @pii_guardrail) - Add local CustomFilterAction to joke-agent-decorator sample Tool guardrail fixes and sample updates: - _base.py: unwrap LangGraph tool-call envelope (args) for rule evaluation; rewrap modified args so super().invoke() receives valid input; handle ToolMessage/Command in _extract_output for POST-stage deterministic rules. - joke-agent-decorator: Agent PII uses LogAction(WARNING) with custom message; README aligned with current guardrails and verification scenarios. Deps and lockfiles: pyproject.toml updates (root and joke-agent-decorator); remove samples/joke-agent-decorator/uv.lock and samples/joke-agent/uv.lock; uv.lock at repo root updated. Refactor _base.py: remove unnecessary casts in _evaluate_rules; catch only ValueError (JSONDecodeError is subclass); extract _apply_guardrail_to_message_list, _apply_guardrail_to_input_messages, _apply_guardrail_to_output_messages and use them in _wrap_stategraph_with_guardrail, _wrap_compiled_graph_with_guardrail, and _wrap_function_with_guardrail to reduce cognitive complexity. Made-with: Cursor Enable enabled_for_evals override across decorators and middlewares for PII, prompt injection, and deterministic guardrails (default true, user-overridable), plus docs/sample updates for the new parameter. Fix mypy errors in pii_detection.py and prompt_injection.py: rebind guardrail to a typed non-optional local variable so mypy can narrow the type inside nested class closures. Made-with: Cursor Fix _wrap_compiled_graph_with_guardrail: output guardrail (POST stage) was never applied — invoke/ainvoke discarded the graph output without running _apply_guardrail_to_output_messages. Now captures the output and evaluates it, matching the behaviour of _wrap_stategraph_with_guardrail. Update pyproject.toml and uv.lock. Fix double POST guardrail application on StructuredTool: remove ainvoke override from _GuardedTool in deterministic.py and pii_detection.py. StructuredTool.ainvoke delegates to self.invoke via run_in_executor, so the guardrail chain in invoke already runs once; the ainvoke override caused a second POST application, producing "words++++" instead of "words++". Fix LogAction double-logging: replace print()+logger.log() with a single logger.log() call using the guardrail name as context prefix. Fix _evaluate_rules violation message: include guardrail name instead of positional index so errors read "Rule <name> detected violation" rather than "Rule 1 detected violation". Pass guardrail_name through _apply_pre/_apply_post call sites in deterministic.py. Fix AgentRuntimeError swallowed in guardrail middleware/decorator except handlers: add explicit except AgentRuntimeError: raise before the generic except Exception in pii_detection decorator (_apply_pre, _apply_post), pii_detection middleware (_wrap_tool_call_func, _check_messages), and prompt_injection middleware (_check_messages) so BlockAction errors propagate instead of being silently logged.
1 parent 9f99874 commit f2e1211

18 files changed

Lines changed: 1941 additions & 17 deletions

File tree

‎pyproject.toml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,6 @@
11
[project]
22
name = "uipath-langchain"
3-
version = "0.9.9"
3+
version = "0.9.10"
44
description = "Python SDK that enables developers to build and deploy LangGraph agents to the UiPath Cloud Platform"
55
readme = { file = "README.md", content-type = "text/markdown" }
66
requires-python = ">=3.11"

‎samples/joke-agent-decorator/README.md‎

Lines changed: 197 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,197 @@
1+
# Joke Agent (Decorator-based Guardrails)
2+
3+
A simple LangGraph agent that generates family-friendly jokes based on a given topic using UiPath's LLM. This sample demonstrates all three guardrail decorator types — PII, Prompt Injection, and Deterministic — applied directly to the LLM, agent, and tool without a middleware stack.
4+
5+
## Requirements
6+
7+
- Python 3.11+
8+
9+
## Installation
10+
11+
```bash
12+
uv venv -p 3.11 .venv
13+
source .venv/bin/activate # On Windows: .venv\Scripts\activate
14+
uv sync
15+
```
16+
17+
## Usage
18+
19+
Run the joke agent:
20+
21+
```bash
22+
uv run uipath run agent '{"topic": "banana"}'
23+
```
24+
25+
### Input Format
26+
27+
```json
28+
{
29+
"topic": "banana"
30+
}
31+
```
32+
33+
### Output Format
34+
35+
```json
36+
{
37+
"joke": "Why did the banana go to the doctor? Because it wasn't peeling well!"
38+
}
39+
```
40+
41+
## Guardrails Overview
42+
43+
This sample achieves full parity with the middleware-based `joke-agent` sample using only decorators. The table below shows which scope each guardrail covers:
44+
45+
| Decorator | Target | Scope | Action |
46+
|---|---|---|---|
47+
| `@prompt_injection_guardrail` | `create_llm` factory | LLM | `BlockAction` — blocks on detection |
48+
| `@pii_detection_guardrail` | `create_llm` factory | LLM | `LogAction(WARNING)` — logs and continues |
49+
| `@pii_detection_guardrail` | `analyze_joke_syntax` tool | TOOL | `LogAction(WARNING)` — logs email/phone |
50+
| `@deterministic_guardrail` | `analyze_joke_syntax` tool | TOOL (PRE) | `CustomFilterAction` — replaces "donkey" with "[censored]" |
51+
| `@deterministic_guardrail` | `analyze_joke_syntax` tool | TOOL (PRE) | `BlockAction` — blocks jokes > 1000 chars |
52+
| `@deterministic_guardrail` | `analyze_joke_syntax` tool | TOOL (POST) | `CustomFilterAction` — always-on output transform |
53+
| `@pii_detection_guardrail` | `create_joke_agent` factory | AGENT | `LogAction(WARNING)` — logs agent-level PII |
54+
55+
## Guardrail Decorators
56+
57+
### LLM-level guardrails
58+
59+
Stacked decorators on a factory function. The outermost decorator runs first:
60+
61+
```python
62+
@prompt_injection_guardrail(
63+
threshold=0.5,
64+
action=BlockAction(),
65+
name="LLM Prompt Injection Detection",
66+
enabled_for_evals=False, # default is True
67+
)
68+
@pii_detection_guardrail(
69+
entities=[PIIDetectionEntity(PIIDetectionEntityType.EMAIL, 0.5)],
70+
action=LogAction(severity_level=LoggingSeverityLevel.WARNING),
71+
name="LLM PII Detection",
72+
)
73+
def create_llm():
74+
return UiPathChat(model="gpt-4o-2024-08-06", temperature=0.7)
75+
76+
llm = create_llm()
77+
```
78+
79+
### Tool-level guardrails
80+
81+
`@deterministic_guardrail` applies local rule functions — no UiPath API call. Rules receive the tool input dict and return `True` to signal a violation. `@pii_detection_guardrail` at TOOL scope evaluates via the UiPath guardrails API.
82+
83+
```python
84+
@deterministic_guardrail(
85+
rules=[lambda args: "donkey" in args.get("joke", "").lower()],
86+
action=CustomFilterAction(word_to_filter="donkey", replacement="[censored]"),
87+
stage=GuardrailExecutionStage.PRE,
88+
name="Joke Content Word Filter",
89+
enabled_for_evals=False, # default is True
90+
)
91+
@deterministic_guardrail(
92+
rules=[lambda args: len(args.get("joke", "")) > 1000],
93+
action=BlockAction(),
94+
stage=GuardrailExecutionStage.PRE,
95+
name="Joke Content Length Limiter",
96+
)
97+
@deterministic_guardrail(
98+
rules=[], # empty rules = always apply (unconditional transform)
99+
action=CustomFilterAction(word_to_filter="words", replacement="words++"),
100+
stage=GuardrailExecutionStage.POST,
101+
name="Joke Content Always Filter",
102+
)
103+
@pii_detection_guardrail(
104+
entities=[
105+
PIIDetectionEntity(PIIDetectionEntityType.EMAIL, 0.5),
106+
PIIDetectionEntity(PIIDetectionEntityType.PHONE_NUMBER, 0.5),
107+
],
108+
action=LogAction(severity_level=LoggingSeverityLevel.WARNING),
109+
name="Tool PII Detection",
110+
)
111+
@tool
112+
def analyze_joke_syntax(joke: str) -> str:
113+
...
114+
```
115+
116+
### Agent-level guardrail
117+
118+
```python
119+
@pii_detection_guardrail(
120+
entities=[PIIDetectionEntity(PIIDetectionEntityType.EMAIL, 0.5)],
121+
action=LogAction(
122+
severity_level=LoggingSeverityLevel.WARNING,
123+
message="PII detected from agent guardrails decorator",
124+
),
125+
name="Agent PII Detection",
126+
enabled_for_evals=False, # default is True
127+
)
128+
def create_joke_agent():
129+
return create_agent(model=llm, tools=[analyze_joke_syntax], ...)
130+
131+
agent = create_joke_agent()
132+
```
133+
134+
### Custom action
135+
136+
`CustomFilterAction` (defined locally in `graph.py`) demonstrates how to implement a custom `GuardrailAction`. When a violation is detected it replaces the offending word in the tool input dict or string, logs the change, then returns the modified data so execution continues with the sanitised input:
137+
138+
```python
139+
@dataclass
140+
class CustomFilterAction(GuardrailAction):
141+
word_to_filter: str
142+
replacement: str = "***"
143+
144+
def handle_validation_result(self, result, data, guardrail_name):
145+
# filter word from dict/str and return modified data
146+
...
147+
```
148+
149+
## Rule semantics (`@deterministic_guardrail`)
150+
151+
- A rule with **1 parameter** receives the tool input dict (`PRE` stage).
152+
- A rule with **2 parameters** receives `(input_dict, output_dict)` (`POST` stage).
153+
- A rule returns `True` to signal a **violation**, `False` to **pass**.
154+
- **All** rules must detect a violation for the guardrail to trigger. If any rule passes, the guardrail passes.
155+
- **Empty `rules=[]`** always triggers the action (useful for unconditional transforms).
156+
157+
## `enabled_for_evals` override
158+
159+
All decorator guardrails accept `enabled_for_evals` (default `True`). Set it to `False`
160+
when you want runtime guardrail behavior but do not want that guardrail enabled for eval scenarios.
161+
162+
## Verification
163+
164+
To manually verify each guardrail fires, run from this directory:
165+
166+
```bash
167+
uv run uipath run agent '{"topic": "donkey"}'
168+
```
169+
170+
**Scenario 1 — word filter (PRE):** the LLM includes "donkey" in the joke passed to `analyze_joke_syntax`. `CustomFilterAction` replaces it with `[censored]` before the tool executes. Look for `[FILTER][Joke Content Word Filter]` in stdout.
171+
172+
**Scenario 2 — length limiter (PRE):** if the generated joke exceeds 1000 characters, `BlockAction` raises `AgentRuntimeError(TERMINATION_GUARDRAIL_VIOLATION)` before the tool is called.
173+
174+
**Scenario 3 — PII at tool and agent scope:** supply a topic containing an email address:
175+
176+
```bash
177+
uv run uipath run agent '{"topic": "donkey, test@example.com"}'
178+
```
179+
180+
Both the agent-scope and LLM-scope `@pii_detection_guardrail` decorators log a `WARNING` when the email is detected. The tool-scope `@pii_detection_guardrail` logs when the email reaches the tool input.
181+
182+
## Differences from the Middleware Approach (`joke-agent`)
183+
184+
| Aspect | Middleware (`joke-agent`) | Decorator (`joke-agent-decorator`) |
185+
|---|---|---|
186+
| Configuration | Middleware class instances passed to `create_agent(middleware=[...])` | `@decorator` stacked on the target object |
187+
| Scope | Explicit `scopes=[...]` list | Inferred automatically from the decorated object |
188+
| Tool guardrails | `UiPathDeterministicGuardrailMiddleware(tools=[...])` | `@deterministic_guardrail` directly on the `@tool` |
189+
| Custom loops | Not supported (requires `create_agent`) | Works in any custom LangChain loop |
190+
| API calls | Via middleware stack | Direct `uipath.guardrails.evaluate_guardrail()` |
191+
192+
## Example Topics
193+
194+
- `"banana"` — normal run, all guardrails pass
195+
- `"donkey"` — triggers the word filter on `analyze_joke_syntax`
196+
- `"donkey, test@example.com"` — triggers word filter + PII guardrails at all scopes
197+
- `"computer"`, `"coffee"`, `"pizza"`, `"weather"`

0 commit comments

Comments
 (0)