feat(guardrails): resolve BYOG by validator name only [AL-510]

[apetraru-uipath]

What changed?

The Agents backend now enforces BYOG validator-name uniqueness per tenant and no longer accepts a connection id at validation nor persists one in the agent (UiPath/Agents#5959, AL-510): the name alone resolves the configuration, and the Integration Service connection is taken from it server-side — an admin rebind is always honored. This PR removes the now-dead connection id from the langchain BYOG surface. Counterpart of UiPath/uipath-python#1840 (platform side); the two are independent — no release-ordering coupling.

• UiPathByoGuardrailMiddleware — the connection_id kwarg is removed and the middleware no longer sets byo_connection_id on the guardrail. The docstring's "validator names are only unique per connection" advice — now factually wrong — is replaced with the per-tenant rule.
• Sample joke-agent-bring-your-own-guardrail — references the configuration by BYOG_VALIDATOR_NAME alone; BYOG_CONNECTION_ID is gone.
• docs/guardrails.md, both BYOG sections — examples and the middleware parameter table lose connection_id; the "> Always pass the connection id" callout becomes "the name is the identity"; discovery copies ByoValidatorName only.
• Tests — middleware, decorator-adapter and parity suites assert the name-only wire contract. The parity scenario additionally pins that no connection id rides along, written tolerantly (getattr/.get) so it passes with uipath-platform releases both before and after the field removal — the floor stays >=0.2.14.
• Version — 0.15.3 (0.15.2 is published on PyPI).

Version-skew safety: published uipath-langchain 0.14.18–0.15.2 still send byoConnectionId; the server ignores unknown fields, and the platform model keeps extra="allow", so every old/new combination keeps working. This PR only stops producing the field.

How has this been tested?

• tests/guardrails/middlewares/test_byo.py — name-only construction; wire dump asserts byoConnectionId is None/absent.
• tests/guardrails/test_byo_validator.py — ByoValidator name-only through @guardrail (tool / plain function / reuse).
• Parity scenario 12 (test_byog_agent_block, both flavors) — identical block contract + name-only wire contract.
• Full suite green; ruff check, ruff format --check, mypy clean; uv lock --check clean; BYOG doc fences compile.
• Live E2E on alpha (AdminStudioTest) with the validator name alone against the real BYOG harmful-content configuration: benign topic → both flavors evaluate, joke returned; harmful topic → agent-scope guardrail logs, LLM-scope guardrail blocks with the vendor verdict "Harmful content detected: Violence (severity 4)" — proving the server resolves the configuration and its IS connection from the name only.

Are there any breaking changes?

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

UiPathByoGuardrailMiddleware(connection_id=...) from 0.14.18–0.15.2 now raises TypeError. The parameter shipped days ago (July 30) and the server already ignores the field it fed — deliberate hard removal in agreement with the backend change rather than a deprecation shim.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

This PR updates the BYOG (Bring Your Own Guardrail) surface in uipath-langchain to align with the backend change that resolves BYOG configurations by validator name only (unique per tenant), removing the now-dead connection_id from middleware, samples, docs, and tests.

Changes:

• Removed connection_id from UiPathByoGuardrailMiddleware and stopped emitting byoConnectionId on the wire.
• Updated docs and the BYOG sample to use validator name as the sole identifier.
• Updated tests (middleware, decorator path, and parity scenario) to assert the name-only contract and tolerate platform versions where the legacy field may be absent.

Reviewed changes

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

Show a summary per file

File	Description
uv.lock	Bumps locked package version to 0.15.3.
pyproject.toml	Bumps project version to 0.15.3.
src/uipath_langchain/guardrails/middlewares/byo.py	Removes connection_id kwarg and no longer sets byo_connection_id on the guardrail payload.
docs/guardrails.md	Updates BYOG documentation to remove connection_id and describe name-only identity.
samples/joke-agent-bring-your-own-guardrail/README.md	Updates sample instructions to use validator name only.
samples/joke-agent-bring-your-own-guardrail/graph.py	Removes BYOG_CONNECTION_ID and uses ByoValidator(name) / middleware name-only wiring.
tests/guardrails/test_byo_validator.py	Updates decorator-path tests to construct ByoValidator with name only and assert name-only contract.
tests/guardrails/middlewares/test_byo.py	Updates middleware tests to remove connection-id assertions and tolerate legacy field absence/None.
tests/cli/test_guardrails_in_langgraph.py	Updates BYOG parity scenario to assert name-only wire contract.
tests/cli/mocks/parity_agent_middleware.py	Updates parity middleware mock agent to remove connection_id usage.
tests/cli/mocks/parity_agent_decorator.py	Updates parity decorator mock agent to remove connection_id usage.

Suppressed comments (1)

src/uipath_langchain/guardrails/middlewares/byo.py:90

• The docstring says to read BYOG parameter IDs from uip agent guardrails list, but BYOG configs are listed via uip agent guardrails list --byo (as referenced a few lines above). Updating this keeps the CLI guidance consistent.

        validator_parameters: Optional list of validator parameters. BYO
            parameter schemas are connector-defined, so values are passed
            through as-is; read the ids and allowed values from the
            validator's ``Parameters`` in ``uip agent guardrails list``.

[sonarqubecloud]

Quality Gate passed

Issues
0 New issues
0 Accepted issues

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

See analysis details on SonarQube Cloud