Metadata Field Policy

Metadata Field Policy

Evaluate field-level conditions against the metadata object passed on each intercept call. Combine rules with AND/OR logic to build precise, data-driven policies, such as blocking high-notional trades or flagging specific tickers.

Info

ℹ️ How it works: When you call /enforce/intercept with a metadata object, the engine evaluates every active metadata policy against those fields. Rules can reference any key in the metadata object with numeric or string comparisons.

Supported Operators

Operator	Type	Example
> < >= <=	Numeric	notional_usd > 100000
== !=	String / Numeric	ticker == "TSLA"
contains not_contains	String	strategy contains "pre-earnings"
exists not_exists	Presence	insider_flag exists

Example: Block High-Risk Financial Transactions

requests.post(f"{BASE}/enforce/policies", headers=HEADERS, json={
    "name": "High-Risk Financial Transactions",
    "policy_type": "metadata",
    "decision": "block",
    "action_types": ["execute_trade", "wire_transfer", "fund_transfer"],
    "conditions": {
        "operator": "AND",          # ALL rules must match to trigger
        "rules": [
            {"field": "notional_usd", "operator": ">",       "value": 100000},
            {"field": "strategy",     "operator": "contains", "value": "pre-earnings"}
        ]
    }
})

Example: OR Logic, Flag Any Large or Sensitive Action

{
    "name": "Sensitive Trade Escalation",
    "policy_type": "metadata",
    "decision": "escalate",
    "conditions": {
        "operator": "OR",           # ANY rule matching triggers the policy
        "rules": [
            {"field": "notional_usd", "operator": ">=", "value": 500000},
            {"field": "ticker",       "operator": "==", "value": "GME"},
            {"field": "insider_flag", "operator": "exists"}
        ]
    }
}

Intercept Call with Metadata

result = requests.post(f"{BASE}/enforce/intercept", headers=HEADERS, json={
    "action_type": "execute_trade",
    "action_content": "Buy $4.2M block of TSLA ahead of earnings",
    "agent_id": "agent_trading_01",
    "metadata": {
        "ticker":       "TSLA",
        "notional_usd": 4200000,
        "strategy":     "pre-earnings",
        "order_type":   "market"
    }
}).json()

# → decision: "block"
# → reasoning: "All metadata conditions met [metadata.notional_usd > 100000; ...]"

Info

SDK auto-extract: When using the @guard decorator or XybernToolkit , numeric and string keyword arguments are automatically extracted as metadata and evaluated against metadata policies, no manual metadata construction needed.