Policies

Policies are rules that describe which combinations of agents, tools and data your organization does not allow. For example: “confidential data must not be combined with tools that send data outside the company”. The service checks every agent and team against your policies whenever it, or anything it uses, changes.

Policies and guardrails complement each other:

	Policies	Guardrails
Check	The configuration of agents	Requests and answers during a conversation
When	When components, environments or deployments change	During every conversation
Based on	Metadata of components	A rule in plain language, classified by a language model
Result	A violation report	A blocked request or answer

How it works

flowchart LR
    T[Tool metadata] --> C[Combined metadata]
    X[Context metadata] --> C
    M[Model metadata] --> C
    A[Agent metadata] --> C
    E[Environment variables] -.->|fill placeholders| C
    C --> P{Policies}
    P -->|condition true| V[Violation]
    P -->|condition false| OK[No violation]

1. You describe each component with metadata, for example which data it handles and whether it communicates externally.
2. When a component changes, the service finds every deployment that uses it.
3. For each agent, it combines the metadata of the agent and everything it uses: tools, contexts and models. For teams, it combines the metadata of all agents in the team.
4. Placeholders such as ${REGION} are filled in from the deployment’s environments.
5. Every active policy is evaluated against the combined metadata. If a policy’s condition is true, it is reported as a violation.

Components that are not part of any deployment are not checked. They are checked as soon as they are added to one.

How metadata is combined

Value type	Rule
Lists	Combined, without duplicates
Objects	Merged key by key
Single values	One value overwrites the other. Avoid giving the same key different single values in components that are used together.

Example:

Tool:     { "data_classification": ["internal"], "external_communication": true }
Agent:    { "data_classification": ["public"], "security_level": "high" }
Combined: { "data_classification": ["internal", "public"], "external_communication": true, "security_level": "high" }

Violations

Violations do not block changes. The change is saved and the violations are reported, so that you can decide how to resolve them.

• When you create or update a component, the response contains a policy_violations list.
• GET /v1/violations returns the current violations of all agents and teams in your tenant.

{
  "policy_name": "confidential-external-data",
  "description": "Confidential data must not leave the organization through external tools",
  "deployment_id": "support-prod",
  "component": "agent/customer-support-agent",
  "reason": {
    "data_classification": ["internal", "confidential"],
    "external_communication": true
  }
}

reason contains only the metadata fields that the policy refers to.

To resolve a violation, for example:

• Replace the tool that causes it.
• Correct the metadata if it describes the component incorrectly.
• Adjust the policy if the rule is too strict.

Create a policy

Policy conditions use JSON Logic. Refer to metadata fields with {"var": "path.to.field"}.

POST ${RUNTIME_BASE_URL}/v1/policy
Content-Type: application/json

{
  "name": "confidential-external-data",
  "description": "Confidential data must not leave the organization through external tools",
  "conditions": {
    "and": [
      { "in": ["confidential", { "var": "data_classification" }] },
      { "==": [{ "var": "external_communication" }, true] }
    ]
  },
  "priority": 100,
  "is_active": true
}

Field	Description
name	Unique name. Letters, digits, dashes and underscores, 3 to 100 characters.
description	What the policy ensures. Shown in violations. Up to 500 characters.
conditions	JSON Logic expression. True means violation.
priority	1 to 1000, lower values first. Default: 100.
is_active	Inactive policies are not evaluated. Default: true.

Supported operators

Operator	Meaning	Example
var	Read a metadata field	{"var": "data.region"}
==, !=	Equal, not equal	{"==": [{"var": "external_communication"}, true]}
>, <	Greater, less than	{">": [{"var": "max_records"}, 1000]}
in	Value in list, overlap of two lists, or substring	{"in": [{"var": "region"}, ["us-east", "us-west"]]}
and, or, !	Combine or negate conditions	{"!": {"var": "approved"}}

If a field is missing, comparisons with ==, >, < and in are false, and != is true. Write conditions so that missing metadata does not hide a violation, or require the field with a separate policy.

Manage policies

All policy endpoints require the service operator role.

Operation	Request
Create	POST /v1/policy
List	GET /v1/policy
Get	GET /v1/policy/{name}
Check existence	HEAD /v1/policy/{name}
Update	PUT /v1/policy/{name} with the fields to change
Delete	DELETE /v1/policy/{name}
List all violations	GET /v1/violations

Best practices

• Agree on a metadata vocabulary first. Policies only work if all components use the same keys and values. See Metadata.
• One rule per policy. Small policies are easier to understand and to switch off.
• Write a clear description. It is what people see when a violation is reported.
• Introduce policies in a test deployment first, and check the reported violations before you rely on them in production.
• Review violations regularly with GET /v1/violations, for example before each release of your agents.