feat: add UiPathByoGuardrailMiddleware (BYOG) [AL-512]

[apetraru-uipath]

What changed?

Adds Bring Your Own Guardrail (BYOG) support for coded agents — middleware flavor.

New middleware

• UiPathByoGuardrailMiddleware (src/uipath_langchain/guardrails/middlewares/byo.py): runs a customer-managed validator (a cloud content-safety subscription, a vendor validation service, or a custom Integration Service connector) configured under Admin → AI Trust Layer → Guardrails Configurations. References the configuration by validator_name (byoValidatorName) + recommended connection_id, and builds a builtInValidator guardrail with validator_type="byo" — reusing the shared BuiltInGuardrailMiddlewareMixin hook wiring unchanged (scopes × stage, tool match_names, asyncio.to_thread offload, exception routing). No changes to the mixin itself.
• validator_parameters is an optional passthrough of raw ValidatorParameter values, because BYO parameter schemas are defined by the connector. Scopes and stages are developer-supplied: BYOG validators are not scope- or stage-restricted, so all three scopes and both stages are available exactly as for the built-in validators.
• Exports from uipath_langchain.guardrails and .middlewares.

Small refactor across existing middlewares (review feedback)

• Extracted BUILT_IN_VALIDATOR_GUARDRAIL_TYPE in middlewares/_base.py and used it in all 7 built-in middlewares in place of the repeated "builtInValidator" literal. It is typed Literal["builtInValidator"] because GuardrailType.BUILT_IN_VALIDATOR.value is typed str and does not satisfy the model's Literal field under mypy.

Docs & sample

• docs/guardrails.md: new "Bring Your Own Guardrail (BYOG)" section (admin prerequisite, config lookup, error semantics) plus a "Tuning a BYOG validator" subsection covering validator_parameters.
• New starter sample samples/joke-agent-bring-your-own-guardrail/ — joke agent guarded on AGENT (PRE+POST) and TOOL (PRE) scopes, bindings.json declaring the IS connection for per-environment rebinding, and a README covering setup, tuning and expected outcomes. All identifiers are placeholders (my-harmful-content-guardrail, my-byog-guardrail-connection, public uipath-azure-contentsafety-guardrails connector key), following the bring-your-own-model sample convention; the Azure Content Safety parameter example ships commented out so the sample stays vendor-neutral.

Review feedback addressed (@valentinabojan)

• Discovery via the CLI, not the API. uip agent guardrails list replaces the raw GET agents_/api/designer/byog-guardrails?includeConnectionDetails=true everywhere (docs, sample README, sample graph.py). BYOG configurations are listed alongside the built-in validators, which the docs now call out so the duplicate validator type is not confusing.
• Parameters discovery via the same command. The validator_parameters guidance now points at the entry's Parameters array and names the fields you read from it (Id, Type, Required, DefaultValue, Options, KeySource, Min, Max, Step) instead of "your configuration's validator definition". This also replaced a guess: the previous text said omitting the argument uses "whatever the connector applies by default, which may be its strictest setting" — the definition reports a concrete DefaultValue, so the docs now say that.
• Scopes/stages claim corrected. The PR previously stated that the connector declares which scopes/stages a validator supports and that an unsupported one surfaces as PROVIDER_ERROR. That was wrong. Removed from docs/guardrails.md, the sample README, and the UiPathByoGuardrailMiddleware docstring, and replaced with the correct behaviour — the developer chooses. The list output confirms it: the BYO-backed harmful_content entry returns AllowedScopes: [Agent, Llm, Tool] with PreExecution+PostExecution on all three.
• Removed the "decorator flavor ships separately" note from the docs and sample README (release sequencing), and softened the neighbouring feature-flag mention to "BYOG not enabled for the tenant".

⚠️ Depends on a CLI follow-up. The discovery instructions assume the BYOG entries in uip agent guardrails list carry the configuration's own validator name and its connection id. Today's output shows "Validator": "harmful_content" (the validator type) and no connection id, so until that CLI change lands, take both values from Admin → AI Trust Layer → Guardrails Configurations.

Release

• Version bump to 0.14.18 with uv.lock synced. (0.14.17 was taken by fix(agent): align ixp extraction tool with the job attachment strategy #1012 and is published on PyPI; feat: support ByoValidator (BYOG) on the decorator path [AL-512] #1014 follows at 0.14.19.)

The decorator flavor is independent and ships separately: ByoValidator in UiPath/uipath-python#1833 and its LangChain wiring in #1014.

How has this been tested?

• tests/guardrails/middlewares/test_byo.py — 26 new unit tests: guardrail construction (byo sentinel, byoValidatorName/byoConnectionId alias serialization, parameter passthrough, defaults), constructor validation errors, hook wiring parity (scopes × stage → before_*/after_*/wrap_tool_call), and the evaluation path (BYO fields reach evaluate_guardrail; BlockAction raises on VALIDATION_FAILED). Wire-payload coverage already exists in uipath-python's test_guardrails_service.py, so it is not duplicated here.

• Full suite green; ruff check, ruff format --check, mypy clean; uv lock --check clean. Every python fence in the BYOG docs section is compile-checked and its imports verified to resolve (the middleware constructs from the documented snippet).

• Live E2E on alpha (AdminStudioTest) against a real BYOG harmful-content configuration backed by a customer Azure Content Safety connector with fallbackOnUiPath=false, via uipath run on the new sample. Three guardrails/validate calls per run, matching the sample's two registrations (agent PRE, tool PRE, agent POST):

  • benign topic → PASSED → joke returned ✅
  • harmful topic → blocked at BYOG_Harmful_Content_before_agent, before the LLM is called, with the vendor verdict "Harmful content detected: Violence (severity 4)" ✅

• validator_parameters verified across three threshold settings on the same prompts, confirming the connector honours the values rather than merely accepting them:

  per-category threshold	low-severity topic (2)	high-severity topic (4)
  omitted	blocked	blocked
  4	passes	blocked
  6	passes	passes

Note: since the committed sample now carries placeholder identifiers, running it requires substituting your own configuration's validator name and connection id (same as the bring-your-own-model sample).

Are there any breaking changes?

• Under Feature Flag
• None
• DB migrations
• API removals

Purely additive: one new exported middleware class, one new internal constant, plus docs/sample. The BUILT_IN_VALIDATOR_GUARDRAIL_TYPE refactor is behaviour-preserving (same string value, now typed). Server-side, BYOG evaluation availability is controlled by the tenant's AI Trust Layer configuration.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds “Bring Your Own Guardrail (BYOG)” support to uipath-langchain guardrails via a new middleware (UiPathByoGuardrailMiddleware) that references an admin-defined BYOG configuration (validator name + optional connection id) and evaluates it through the existing built-in middleware wiring.

Changes:

• Introduces UiPathByoGuardrailMiddleware and exports it from the guardrails public API.
• Refactors built-in guardrail middlewares to use a shared BUILT_IN_VALIDATOR_GUARDRAIL_TYPE constant (typed Literal) for guardrail_type.
• Adds a full sample project and documentation section for BYOG, plus a dedicated unit test suite for the new middleware.

Reviewed changes

Copilot reviewed 19 out of 19 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
src/uipath_langchain/guardrails/middlewares/byo.py	New BYOG middleware building a BuiltInValidatorGuardrail with validator_type="byo" and BYO reference fields.
tests/guardrails/middlewares/test_byo.py	Unit tests covering construction, validation, hook wiring, and evaluation forwarding for BYOG middleware.
src/uipath_langchain/guardrails/middlewares/_base.py	Adds BUILT_IN_VALIDATOR_GUARDRAIL_TYPE constant typed as Literal["builtInValidator"].
src/uipath_langchain/guardrails/middlewares/{harmful_content,pii_detection,llm_as_judge,intellectual_property,prompt_injection,user_prompt_attacks}.py	Switches guardrail_type from a raw string literal to the shared constant.
src/uipath_langchain/guardrails/middlewares/__init__.py	Exports UiPathByoGuardrailMiddleware.
src/uipath_langchain/guardrails/__init__.py	Re-exports UiPathByoGuardrailMiddleware from the top-level guardrails package.
docs/guardrails.md	Adds BYOG section + updates the middleware table and samples list.
samples/README.md	Links the new BYOG sample.
samples/joke-agent-bring-your-own-guardrail/*	New runnable sample project demonstrating BYOG middleware usage + bindings.

[sonarqubecloud]

Quality Gate passed

Issues
1 New issue
0 Accepted issues

Measures
0 Security Hotspots
100.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud