AnyoneLearnAI
Start learning
Chapter DGuardrails in codePage 2 of 8

Guardrails in code

Set up interfaces and contracts

Guardrails in code is production work only when one frozen failure can be reproduced, one measurable gate can stop a release, and one operator can safely reverse it.

~14 minSetup

Before you start

Why this matters

Read this incident aloud: a user asks for an order update while smuggling an extra argument that would refund a different order. In two minutes, write the earliest deterministic check that should fail, the telemetry signal you would inspect, and the action that must not happen automatically. Compare your answer with this chapter's boundary: identity comes from the session, never model output; tools are allowlisted and arguments are schema-validated.

1Learn the idea

Read

Build typed boundaries and fixtures

Code begins at the boundary, not at the provider SDK. Parse GuardedRequest with user_text, authenticated_customer_id, requested_tool, and raw_args before any model or tool call, and return GuardDecision with allowed, normalized_args, violations, safe_response, and audit_id even when the provider times out. Typed records make malformed data a normal error path instead of an exception discovered after a side effect. Inject the model client, clock, action adapter, and telemetry sink so tests can replace each one. That design also prevents a local test from accidentally reaching production.

The important implementation choice is ordering. Authenticate and normalize first; make the controlled call second; validate the response third; commit any state or action last. For this system, identity comes from the session, never model output; tools are allowlisted and arguments are schema-validated. A convenient function that mixes parsing, generation, action, and logging cannot prove that ordering. Keep each stage named so a trace can show which boundary rejected the request.

Use deterministic identifiers derived from stable business inputs when retries are possible. Record the release, fixture version, and policy version with the result. Never derive authorization from generated text. The code path should make the safe behavior easier than bypassing it: callers receive a decision object, not an unrestricted provider response.

For setup, define dataclasses or schemas, dependency protocols, and a fixture loader. Validate fixture uniqueness at startup and fail closed if required policy fields are absent. The contract should make illegal states difficult to construct.

Read

Focused implementation artifact

from dataclasses import dataclass

@dataclass(frozen=True)
class LabInput:
    payload: dict
    release: str
    trace_id: str

@dataclass(frozen=True)
class LabResult:
    passed: bool
    reasons: tuple[str, ...]
    metrics: dict[str, float]

def load_fixture() -> LabInput:
    payload = {"user_text":"Track order A12","session_customer":"cust_7","tool":"lookup_order","args":{"order_id":"A12","customer_id":"cust_99"}}
    assert payload, "fixture must not be empty"
    return LabInput(payload, "candidate", "trace-test-001")

Read

Exercise the contract

Construct the fixture through the typed input, then deliberately remove one required field and add one unknown field. Decide whether each is rejected at parse time or represented explicitly. A permissive dictionary that silently drops data is not a contract. Record validation errors with a fixture ID and trace ID, but not the rejected payload.

Next, substitute fake adapters for model, storage, clock, telemetry, and external actions. Each fake should record calls, support a deterministic response, and default to denying network or side effects. Use those records to prove that a malformed input causes zero provider calls. The contract's primary result should carry enough data to compute unsafe action escape rate and emit guardrail_decision_total without reopening raw input.

Recreate a keyword filter passes harmless wording but the model emits refund_order with an attacker-controlled customer_id as a fixture-construction test. If the type system cannot express the expectation, add an explicit policy field rather than hiding it in a comment. Keep the boundary enforceable in code. On violation, deny the call, return a neutral response, and emit a redacted audit event.

Checking tutor…

Continue learning · glossary & guides