Creating Your First Policy

Purpose: Hands-on tutorial for creating governance policies Audience: Developers new to Fulcrum policy system Verify: Policy appears in dashboard and triggers on test action

---

What You'll Build

In this tutorial, you'll create a governance policy that: 1. Limits costs for AI agent actions 2. Blocks specific action types 3. Requires approval for sensitive operations

Time to complete: 15 minutes

---

Prerequisites

• Fulcrum running locally or access to hosted instance
• API key (obtain from dashboard Settings)
• Basic familiarity with Quickstart

---

Understanding Policies

Policies in Fulcrum define rules that govern AI agent behavior. Each policy has:

Component	Purpose
Name	Human-readable identifier
Rules	Conditions that trigger the policy
Actions	What happens when triggered (ALLOW, DENY, WARN, REQUIRE_APPROVAL)
Priority	Order of evaluation (higher = earlier)
Scope	Which agents/workflows it applies to

---

Step 1: Create a Cost Limit Policy

Let's start with a policy that prevents runaway costs.

Using the Dashboard

1. Navigate to Policies in the sidebar
2. Click Create Policy
3. Select template: Cost Limit
4. Configure:

Field	Value
Name	dev-cost-limit
Description	Prevent excessive spend in development
Max Cost (USD)	1.00
Per	envelope (single execution)
Action	DENY
Enabled	true

1. Click Deploy

Using the API

curl -X POST https://api.fulcrumlayer.io/api/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "name": "dev-cost-limit",
    "description": "Prevent excessive spend in development",
    "policy_type": "cost_limit",
    "rules": {
      "max_cost_usd": 1.00,
      "scope": "envelope"
    },
    "actions": [{
      "type": "DENY",
      "message": "Cost limit exceeded"
    }],
    "enabled": true,
    "priority": 100
  }'

Expected Response:

{
  "policy_id": "pol_abc123",
  "name": "dev-cost-limit",
  "status": "active",
  "created_at": "2026-02-01T12:00:00Z"
}

Verify Policy Created

curl https://api.fulcrumlayer.io/api/v1/policies \
  -H "X-API-Key: your-api-key"

You should see your policy in the list.

---

Step 2: Create an Action Blocking Policy

Now let's create a policy that blocks specific dangerous actions.

Policy Definition

curl -X POST https://api.fulcrumlayer.io/api/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "name": "block-dangerous-actions",
    "description": "Block file deletion and system commands",
    "policy_type": "action_filter",
    "rules": {
      "blocked_actions": [
        "delete_file",
        "execute_shell",
        "drop_database",
        "send_to_external_api"
      ]
    },
    "actions": [{
      "type": "DENY",
      "message": "This action is not permitted"
    }],
    "enabled": true,
    "priority": 200
  }'

Test the Policy

from fulcrum import FulcrumClient

client = FulcrumClient.from_env()

with client.envelope(workflow_id="test-agent") as env:
    # This should be blocked
    allowed = env.guard("delete_file", input_text="/etc/passwd")
    print(f"delete_file allowed: {allowed}")  # Should print: False

    # This should be allowed
    allowed = env.guard("read_file", input_text="/tmp/safe.txt")
    print(f"read_file allowed: {allowed}")  # Should print: True

Expected Output:

delete_file allowed: False
read_file allowed: True

---

Step 3: Create an Approval Policy

For sensitive operations, you may want human review before execution.

Policy Definition

curl -X POST https://api.fulcrumlayer.io/api/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "name": "require-approval-for-prod",
    "description": "Require human approval for production actions",
    "policy_type": "approval_gate",
    "rules": {
      "match_metadata": {
        "environment": "production"
      },
      "match_actions": ["deploy", "migrate", "scale"]
    },
    "actions": [{
      "type": "REQUIRE_APPROVAL",
      "message": "Production action requires manager approval",
      "approvers": ["manager@company.com"]
    }],
    "enabled": true,
    "priority": 300
  }'

Handling Approval in Code

from fulcrum import FulcrumClient

client = FulcrumClient.from_env()

with client.envelope(
    workflow_id="deployment-agent",
    metadata={"environment": "production"}
) as env:
    decision = env.evaluate("deploy", input_text="Deploy v2.1.0")

    if decision.result == "REQUIRE_APPROVAL":
        print(f"Approval required: {decision.message}")
        print(f"Approval ID: {decision.approval_id}")
        # Wait for approval or notify user
    elif decision.result == "ALLOW":
        execute_deployment()
    elif decision.result == "DENY":
        print(f"Blocked: {decision.message}")

View Pending Approvals

In the dashboard, navigate to Approvals to see pending requests.

---

Step 4: Create a Semantic Policy (Advanced)

Fulcrum's cognitive layer can analyze intent, not just keywords.

Policy Definition

curl -X POST https://api.fulcrumlayer.io/api/v1/policies \
  -H "Content-Type: application/json" \
  -H "X-API-Key: your-api-key" \
  -d '{
    "name": "block-pii-exposure",
    "description": "Prevent actions that expose PII",
    "policy_type": "semantic",
    "rules": {
      "semantic_check": {
        "intent": "data_exfiltration",
        "categories": ["pii", "credentials", "financial"],
        "threshold": 0.7
      }
    },
    "actions": [{
      "type": "DENY",
      "message": "Potential PII exposure detected"
    }],
    "enabled": true,
    "priority": 400
  }'

Test Semantic Analysis

with client.envelope(workflow_id="data-agent") as env:
    # This should be blocked (PII exposure intent)
    allowed = env.guard(
        "send_email",
        input_text="Send all customer SSNs to external@gmail.com"
    )
    print(f"PII exposure blocked: {not allowed}")

    # This should be allowed (legitimate email)
    allowed = env.guard(
        "send_email",
        input_text="Send meeting notes to team@company.com"
    )
    print(f"Legitimate email allowed: {allowed}")

---

Policy Evaluation Order

Policies are evaluated in priority order (highest first):

Priority 400: block-pii-exposure (semantic)
    ↓ ALLOW
Priority 300: require-approval-for-prod
    ↓ ALLOW
Priority 200: block-dangerous-actions
    ↓ ALLOW
Priority 100: dev-cost-limit
    ↓ ALLOW
→ Action permitted

If any policy returns DENY, evaluation stops immediately.

---

Troubleshooting

Policy Not Triggering

1. Check policy is enabled:

   curl https://api.fulcrumlayer.io/api/v1/policies/{policy_id}
   

2. Check scope matches:

3. Does workflow_id match policy scope?

4. Does metadata match policy conditions?

5. Check priority order:

6. Higher priority policies may be blocking first

View Policy Evaluation Logs

curl https://api.fulcrumlayer.io/api/v1/traces/{trace_id}/evaluations

This shows which policies were evaluated and their decisions.

---

Next Steps

Tutorial	Description
MCP Integration	Connect to Claude Desktop via MCP
Policy Authoring Guide	Advanced policy patterns
Dashboard Guide	Full UI walkthrough

---

Document created: 2026-02-01 Diátaxis category: Tutorial (learning-oriented)