Skip to content

feat(guardrails): send the scope, stage and action of agent-defined guardrail checks [AL-696] - #1992

Merged
andreizdrali-uipath merged 7 commits into
mainfrom
feat/al-696-guardrail-governance-context
Nov 17, 2026
Merged

andreizdrali-uipath merged 7 commits into
mainfrom
feat/al-696-guardrail-governance-context

Conversation

@andreizdrali-uipath

@andreizdrali-uipath andreizdrali-uipath commented Nov 13, 2026 •

Copy link
Copy Markdown
Contributor

Part of AL-696.

What

evaluate_guardrail takes optional scope, execution_stage and action_type keyword arguments and sends them as top-level fields to /agentsruntime_/api/execution/guardrails/validate, next to guardrailName and terminationMode:

{ "validator": "pii_detection", "guardrailName": "PII Detection", "scope": "Tool", "executionStage": "preExecution", "actionType": "Escalate", ... }
Argument Values
scope GuardrailScope: Agent, Llm, Tool
execution_stage preExecution, postExecution
action_type Block, Filter, Log, Escalate

Without them the body is byte-identical to today.

Why

For a built-in guardrail an agent defines, the Agents guardrail service publishes the guardrailEvaluation span, but the request doesn't say what the check guards, when, or what the agent does on a violation. The span then can't carry the uipath_governance.* contract (hook, mode, action_applied) that centralized (AI Trust Layer) checks already carry.

The SDK sends what the caller knows about the check, not governance strings (review); the service maps them for its span (UiPath/Agents#7004).

Rollout

Tests

TestGuardrailCheckContext: sent camelCase when supplied, keys absent when not. test_guardrails_service.py 61 passed; ruff, ruff format, mypy clean.

🤖 Generated with Claude Code

…rdrail checks [AL-696]

The guardrail service publishes the evaluation span of a built-in check an
agent defines, but the request does not say where in the run the check guards
or what the agent does on a violation. So the span cannot carry the
uipath_governance.* contract (hook, mode, action_applied) that centralized
guardrail checks already carry.

evaluate_guardrail takes an optional GuardrailGovernanceContext (hook, mode,
version, action_on_violation) and sends it as a camelCase "governance" object.
Without it the request body is unchanged. uipath-platform 0.3.7 -> 0.3.8.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are identified for the optional guardrail governance-context support.

No open issues 🎉

What changed in this PR

Adds optional governance context to the UiPath SDK’s guardrail validation requests so the backend can annotate evaluation spans with the agent’s governance decision. Request bodies remain unchanged when context is omitted.

Changes:

  • Introduces and exports GuardrailGovernanceContext, and forwards it through evaluate_guardrail.
  • Adds tests for camelCase serialization and omission when no context is supplied.
  • Bumps uipath-platform to 0.3.8 and updates both lockfiles.
File Description
packages/​uipath/​uv.lock Updates the platform package version to 0.3.8.
packages/​uipath-platform/​uv.lock Aligns the platform lockfile with version 0.3.8.
packages/​uipath-platform/​tests/​services/​test_guardrails_service.py Tests governance serialization and omission.
packages/​uipath-platform/​src/​uipath/​platform/​guardrails/​guardrails.py Defines the governance context model and wire-field alias.
packages/​uipath-platform/​src/​uipath/​platform/​guardrails/​_guardrails_service.py Accepts optional governance context and includes it in validation requests.
packages/​uipath-platform/​src/​uipath/​platform/​guardrails/​__init__.py Exports the new public model.
packages/​uipath-platform/​pyproject.toml Bumps the platform package version to 0.3.8.

Review effort: Balanced

…s [AL-696]

Review: hook, mode and the action on a violation make sense outside
governance, so the /validate request should not wrap them in a governance
object. evaluate_guardrail takes hook, mode and action_on_violation and sends
them as top-level hook, mode and actionOnViolation, next to guardrailName and
terminationMode. GuardrailGovernanceContext is gone; the backend stamps the
contract version itself.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
andreizdrali-uipath added a commit to UiPath/uipath-langchain-python that referenced this pull request Nov 16, 2026
…lain fields [AL-696]

Review: hook, mode and the action on a violation make sense outside
governance, so evaluate_guardrail takes them as plain keyword arguments
(UiPath/uipath-python#1992) instead of a GuardrailGovernanceContext.

- governance.py keeps the scope/stage -> hook and action -> decision mapping;
  guardrail_check_context() builds a GuardrailCheckContext (hook, mode,
  action_on_violation) that the node splats into evaluate_guardrail.
- The subgraph passes each node check_context= instead of governance=.
- Fakes of evaluate_guardrail take the SDK's new keywords.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@andreizdrali-uipath andreizdrali-uipath changed the title feat(guardrails): send the governance decision with agent-defined guardrail checks [AL-696] feat(guardrails): send the hook and action of agent-defined guardrail checks [AL-696] Nov 16, 2026
andreizdrali-uipath and others added 3 commits November 17, 2026 11:44
…-696]

Review: the runtime should send what it knows about a check, not
uipath_governance strings; the guardrail service maps them for its span.

evaluate_guardrail takes scope (GuardrailScope), execution_stage
(preExecution or postExecution) and action_type (Block, Filter, Log or
Escalate) instead of hook, mode and action_on_violation, and sends them as
scope, executionStage and actionType, each only when given.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
main published 0.3.8 in #1994, so this change needs its own version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@andreizdrali-uipath andreizdrali-uipath changed the title feat(guardrails): send the hook and action of agent-defined guardrail checks [AL-696] feat(guardrails): send the scope, stage and action of agent-defined guardrail checks [AL-696] Nov 17, 2026
andreizdrali-uipath added a commit to UiPath/uipath-langchain-python that referenced this pull request Nov 17, 2026
…lain fields [AL-696]

Review: hook, mode and the action on a violation make sense outside
governance, so evaluate_guardrail takes them as plain keyword arguments
(UiPath/uipath-python#1992) instead of a GuardrailGovernanceContext.

- governance.py keeps the scope/stage -> hook and action -> decision mapping;
  guardrail_check_context() builds a GuardrailCheckContext (hook, mode,
  action_on_violation) that the node splats into evaluate_guardrail.
- The subgraph passes each node check_context= instead of governance=.
- Fakes of evaluate_guardrail take the SDK's new keywords.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
andreizdrali-uipath and others added 2 commits November 17, 2026 16:44
main published 0.3.9 in #1929 without the guardrail check fields, so
this change needs the next version.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
@sonarqubecloud

Copy link
Copy Markdown

@andreizdrali-uipath
andreizdrali-uipath merged commit e8242e9 into main Nov 17, 2026
186 checks passed
@andreizdrali-uipath
andreizdrali-uipath deleted the feat/al-696-guardrail-governance-context branch November 17, 2026 15:24
andreizdrali-uipath added a commit to UiPath/uipath-langchain-python that referenced this pull request Nov 17, 2026
…lain fields [AL-696]

Review: hook, mode and the action on a violation make sense outside
governance, so evaluate_guardrail takes them as plain keyword arguments
(UiPath/uipath-python#1992) instead of a GuardrailGovernanceContext.

- governance.py keeps the scope/stage -> hook and action -> decision mapping;
  guardrail_check_context() builds a GuardrailCheckContext (hook, mode,
  action_on_violation) that the node splats into evaluate_guardrail.
- The subgraph passes each node check_context= instead of governance=.
- Fakes of evaluate_guardrail take the SDK's new keywords.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

test:uipath-integrations test:uipath-langchain Triggers tests in the uipath-langchain-python repository

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants