feat: support ByoValidator (BYOG) on the decorator path [AL-512]

[apetraru-uipath]

What changed?

Decorator-flavor Bring Your Own Guardrail (BYOG) support — the counterpart to UiPathByoGuardrailMiddleware shipped in #1013.

ByoValidator re-export

• Exported from uipath_langchain.guardrails and the .guardrails.decorators shim as a plain import. uipath-platform is floored at >=0.2.14 — the release that ships ByoValidator (feat: add ByoValidator for Bring Your Own Guardrail (BYOG) [AL-512] uipath-python#1833, now merged and published) — so the guarded getattr(..., None) fallback this PR previously carried is gone, along with the sample's ImportError guard and the conditional test skips.
• No new adapter machinery — @guardrail(validator=ByoValidator("…", connection_id="…"), action=…) works through the existing LangChainGuardrailAdapter, with scope inferred from the decorated target (tool → TOOL, LLM factory → LLM, agent factory → AGENT).

Adapter hardening

• The LLM/agent wrappers previously swallowed evaluator exceptions with a bare except Exception: return (4 sites in _langchain_adapter.py). They now log a WARNING with the guardrail name and traceback while staying fail-open, so a misconfigured BYOG configuration (PROVIDER_ERROR, removed/disabled config, BYOG not enabled) is visible instead of silent.

Parity suite: BYOG scenario (middleware vs decorator)

• Both parity mock agents (tests/cli/mocks/parity_agent_{middleware,decorator}.py) gain the same "Agent BYOG Detection" guardrail — AGENT scope, PRE, BlockAction; wired through UiPathByoGuardrailMiddleware on one side and ByoValidator + @guardrail on the other, with identical placeholder validator name / connection id.
• New scenario 12, test_byog_agent_block in tests/cli/test_guardrails_in_langgraph.py, runs for both flavors and asserts two parity dimensions: the identical AgentRuntimeError block contract on a failing verdict, and — the BYOG-specific part — that both flavors deliver the same byo wire contract to the guardrails service (validator_type="byo", byoValidatorName, byoConnectionId). The guardrail objects are captured outside the mock so a mismatch fails the test rather than being swallowed by a fail-open path.

Docs & sample: ONE sample, both flavors in one agent

• The two BYOG samples are merged into samples/joke-agent-bring-your-own-guardrail: a single agent guarded twice from the same BYOG configuration — UiPathByoGuardrailMiddleware logs on AGENT scope (PRE_AND_POST, LogAction) while ByoValidator + @guardrail on a create_llm() factory blocks on LLM scope (PRE, BlockAction). On a harmful topic you see both actions in sequence: the agent guardrail logs the violation, then the LLM guardrail aborts the run before the model is invoked. samples/joke-agent-byog-decorator/ is removed.
• docs/guardrails.md: BYOG section under the decorator pattern. The admin prerequisite and discovery steps are cross-referenced to the middleware BYOG section rather than repeated verbatim — only the decorator-specific notes (parameters naming, no static stage restriction, error semantics) are spelled out.
• Discovery uses uip agent guardrails list --byo, whose entries carry ByoValidatorName (→ validator_name), ByoConnectionId (→ connection_id) and the full connector-defined Parameters schema. Updated in both BYOG doc sections, the sample README and the sample's code comments.
• No solution binding for the BYOG connection (review feedback): the connection is resolved server-side from the BYOG configuration, so the sample ships no bindings.json and the docs no longer point ByoConnectorKey at a connection binding.
• All identifiers are placeholders (my-harmful-content-guardrail, my-byog-guardrail-connection, public uipath-azure-contentsafety-guardrails connector key); the Azure Content Safety parameter example ships commented out to keep the sample vendor-neutral.

Leftovers cleaned up from the #1013 review

• Tenant-specific values removed from tests. The earlier placeholder sweep covered docs and samples but missed the test suites: tests/guardrails/test_byo_validator.py and tests/guardrails/middlewares/test_byo.py still hard-coded a real validator name and connection GUID. Both now use the same placeholders as the samples. The second file came from feat: add UiPathByoGuardrailMiddleware (BYOG) [AL-512] #1013 and is already on main, so this PR touches it.
• Scopes/stages claim and the uip agent guardrails list discovery command were corrected here in the previous round, matching what landed in feat: add UiPathByoGuardrailMiddleware (BYOG) [AL-512] #1013.
• Docs deduplication after feat: add UiPathByoGuardrailMiddleware (BYOG) [AL-512] #1013 merged: two ### Bring Your Own Guardrail (BYOG) sections now exist in one document, so the identical admin-prerequisite and discovery paragraphs were collapsed into a cross-reference.

Release

• Version bump to 0.14.20 with uv.lock synced (0.14.19 was taken by feat(tools): add internal HTTP request tool #1008 and is published on PyPI). The lock also moves uipath-platform 0.2.12 → 0.2.14 for the raised floor.

How has this been tested?

• tests/guardrails/test_byo_validator.py — 10 tests, all running, no skips: adapter evaluator-error logging across all four LLM/agent PRE/POST wrappers (message names the guardrail, traceback attached), and ByoValidator through @guardrail on a tool, a plain function, and reused across two targets — asserting the byo guardrail with byoValidatorName/byoConnectionId reaches evaluate_guardrail. Previously 3 of these skipped on CI behind skipif ByoValidator is None; with the floor at uipath-platform>=0.2.14 they now execute against the published package.
• Parity suite, scenario 12 — test_byog_agent_block runs for BOTH flavors: each parity mock agent gains an "Agent BYOG Detection" guardrail (AGENT scope, PRE, BlockAction; middleware via UiPathByoGuardrailMiddleware, decorator via ByoValidator), and the test asserts they deliver the same byo wire contract to the service (validator_type="byo", byoValidatorName, byoConnectionId — captured outside the mock so fail-open paths can't swallow a mismatch) and raise the identical AgentRuntimeError block contract. All 12 parity scenarios × 2 flavors green.
• Full suite green; ruff check, ruff format --check, mypy clean; uv lock --check clean.
• Verified the re-export resolves without the guard: ByoValidator imports from both entry points, is present in both __all__s, and builds a guardrail with validator_type="byo" carrying the expected byoValidatorName/byoConnectionId.
• All three python fences across both BYOG doc sections compile-checked; the merged sample's graph.py parses and its JSON manifests validate.
• Live E2E on alpha (AdminStudioTest) against a real BYOG harmful-content configuration, running the merged sample (local uipath-langchain + published uipath-platform 0.2.14):
  • benign topic → both flavors evaluate in one run (agent PRE, LLM PRE per model call, agent POST — all 200) → joke returned ✅
  • harmful topic → [GUARDRAIL] [BYOG Harmful Content] Failed logged by the agent-scope middleware, then Guardrail [BYOG LLM Harmful Content] blocked execution → AgentRuntimeError before chat/completions ✅ (vendor verdict: Harmful content detected: Violence (severity 4))

Behaviour note for reviewers: @guardrail on a factory function evaluates the factory's own (empty) arguments once at import time — so a run shows one guardrail call before START in addition to the runtime evaluations. This is pre-existing platform behaviour for any factory-decorated guardrail (it also affects the existing joke-agent-decorator sample), not something introduced here, and is deliberately left as is. LLM-scope guardrails evaluate once per model call (twice in a two-turn ReAct run).

Are there any breaking changes?

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

Additive: one re-export plus docs, sample and test coverage. Two things a reviewer should note as deliberate: the adapter now emits a WARNING on paths that previously failed silently, and the uipath-platform floor moves 0.2.12 → 0.2.14 (within the existing <0.3.0 range), which is required for ByoValidator to exist.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Adds decorator-path Bring Your Own Guardrail (BYOG) support by re-exporting ByoValidator when available in the installed uipath SDK, hardens the LangChain adapter to log evaluator failures (still fail-open), and documents/illustrates usage with tests and a new sample.

Changes:

• Guarded re-export of ByoValidator from uipath_langchain.guardrails and uipath_langchain.guardrails.decorators (falls back to None on older uipath versions).
• Adapter hardening: LLM/agent guardrail evaluation exceptions are now logged at WARNING with traceback instead of being silently swallowed.
• Adds docs, sample project, and unit tests for BYOG decorator usage and the new warning logs.

Reviewed changes

Copilot reviewed 12 out of 12 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
tests/guardrails/test_byo_validator.py	Adds tests for adapter exception logging and conditional BYOG decorator wiring when ByoValidator exists.
src/uipath_langchain/guardrails/decorators/init.py	Adds guarded ByoValidator re-export via getattr(...) and includes it in __all__.
src/uipath_langchain/guardrails/_langchain_adapter.py	Logs WARNING with traceback on evaluator exceptions in LLM/agent PRE/POST application helpers.
src/uipath_langchain/guardrails/init.py	Adds guarded ByoValidator re-export and exposes it publicly via __all__.
samples/README.md	Adds the new BYOG decorator sample to the samples index.
samples/joke-agent-byog-decorator/uipath.json	Adds sample project UiPath packaging/runtime configuration.
samples/joke-agent-byog-decorator/README.md	Documents how to configure and run the BYOG decorator sample.
samples/joke-agent-byog-decorator/pyproject.toml	Adds the sample’s Python project metadata and dependencies.
samples/joke-agent-byog-decorator/langgraph.json	Declares the LangGraph entrypoint for the sample.
samples/joke-agent-byog-decorator/graph.py	Implements the sample agent guarded with ByoValidator using @guardrail.
samples/joke-agent-byog-decorator/bindings.json	Declares the Integration Service connection binding used by the BYOG config.
docs/guardrails.md	Adds a BYOG section under decorator-based guardrails and links the new sample.

[valentinabojan]

To remove this comment once the TODO is solved

[valentinabojan]

Same here

[valentinabojan]

We don't have stage constraints in the connector. We left full flexibility - the connector allows all stages(by not enforcing them in any way) and the guardrail user is in charge to select the stage.

[valentinabojan]

There is no need for the connection details to end up in bindings, for byog.

[apetraru-uipath]

Done in eb878f6 — the sample no longer ships a bindings.json (its only resource was the BYOG connection binding), and the docs/README no longer point ByoConnectorKey at a connection binding. Both now state the connection is resolved server-side from the BYOG configuration, with the agent sending only the validator name + connection id.

[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