Core concepts
Understand agents, policies, decisions, traces, and the limits of enforcement.
Agents and organizations
An organization owns its agents, policies, API keys, and evidence. Select the correct workspace before configuring a key or policy. An agent represents an application or service; its name is unique within that organization.
Use the same agent name in your SDK configuration and policy scope. SDK ingestion can discover an agent, but registering it first makes the intended scope clear. Agent creation is subject to workspace limits.
Policies
A policy combines a detector type, configuration, an enabled state, and a scope. It applies to all agents in the organization or a selected set.
| Mode | When a finding or a failed required check occurs |
|---|---|
warning | Evaluation can allow the operation while returning findings or diagnostics. |
blocking | Evaluation denies the operation. The application or supported interceptor must stop it. |
A policy edit creates a version. Record the versions returned by evaluation when comparing a retest. The policies request field is a list of detector types, not policy IDs; omit it for normal configured-policy evaluation. The API reference explains the explicit-selection behavior.
Decisions and completion are separate
Request → applicable policies → detectors → allowed + violations + completion
↓
your application decides what to releaseevaluation_status | Meaning |
|---|---|
complete | The selected evaluations completed. Inspect findings and the decision. |
degraded | Some coverage is reduced or incomplete. Inspect errors. |
unavailable | A selected check could not run. |
not_configured | No applicable check ran. Enable and scope a policy. |
For a required check, release content only when allowed is true, status is complete, errors is empty, and policies_evaluated is greater than zero. An allowed warning decision can still contain findings.
Evaluation depth
The API accepts mode: "thorough" or "fast". This field is distinct from policy warning/blocking and Node's wrapper behavior. The current direct-evaluation route uses the same policy selection for both depth values; fast is not a documented shortcut that skips required checks or guarantees lower latency. Prompt Injection also has its own config.detection_mode setting.
Traces and spans
A trace groups an interaction. Spans describe model, tool, retrieval, and other work within it. Direct evaluation normally records an evaluation trace; no_trace disables that recording. Supported pre-call SDK checks use no_trace and need separately configured instrumentation for model-call traces.
A parent trace() groups instrumented work; it does not instrument every operation automatically. Model token counts and other attributes depend on the instrumentor. Tracing covers export, privacy, and shutdown.
What enforcement can stop
A supported input check happens before a model request. To stop unsafe generated content, evaluate a buffered answer before returning it. To stop a side-effecting tool, authorize it before execution. Checking a recorded tool span or a tool's result happens too late to prevent that tool from running.
See enforcement, streaming, and data handling.