Overview

As AI agents become more capable, they also become more powerful and with that power comes responsibility.

An AI agent that can create invoices, deploy infrastructure, delete repositories, or send emails should not be allowed to perform every action without constraints.

Swytchcode provides a policy engine that allows you to define what an agent is allowed to do, when it is allowed to do it, and how API requests should be executed safely.

Policies are evaluated before every execution, giving you complete control over your application’s behavior without changing your application code.

---

Manage policies from the CLI

swy policy add               # interactive - prompts for target, condition, and action
swy policy list [--json]
swy policy remove <policy-id>
swy policy validate

These commands manage the rules in policies.json. They’re a different surface from swy audit policy, which is a read-only log of past violations - use swy policy list to see what rules are configured, and swy audit policy to see what those rules have actually blocked.

See the policies.json reference for the full schema, condition operators, and command details.

---

Why Policies Matter

Consider an AI agent connected to your production systems.

Without guardrails, a simple prompt like:

“Delete all GitHub repositories.”

could execute immediately if the necessary credentials are available.

With Swytchcode policies, you can define rules such as:

• Only allow repository operations for approved organizations.
• Block destructive operations in production.
• Prevent payments above a certain amount.
• Restrict requests outside business hours.
• Require specific request fields before execution.

Instead of trusting every generated request, your application evaluates every request against your policies before it reaches the provider.

---

The Swytchcode Trust Model

Swytchcode separates API execution into three distinct layers.

                    Developer / AI Agent
                            │
                            ▼
                   tooling.json
              "What can execute?"
                            │
                            ▼
                  policies.json
          "Should this request execute?"
                            │
                            ▼
                  manifest.json
           "How should it execute?"
                            │
                            ▼
                    Provider API

Each configuration file has a different responsibility.

File	Responsibility
tooling.json	Defines the trusted methods and workflows available to the project.
policies.json	Evaluates every request and blocks operations that violate your rules.
manifest.json	Configures authentication, endpoints, retries, timeouts, idempotency, and execution behavior.

Keeping these responsibilities separate makes policies easier to understand, maintain, and audit.

---

Request Lifecycle

Every request follows the same execution pipeline.

AI Agent
    │
    ▼
Generate Tool Call
    │
    ▼
Is the tool trusted?
(tooling.json)
    │
    ▼
Does the request satisfy policy rules?
(policies.json)
    │
    ▼
Resolve authentication
    │
    ▼
Apply execution policy
(manifest.json)
    │
    ▼
Execute API
    │
    ▼
Return Response

If a request fails any policy check, execution stops immediately before any network request is made.

---

policies.json example

Policies are defined in .swytchcode/integrations/policies.json.

A policy consists of four core parts:

• id - A unique identifier for the policy.
• target - The methods or workflows the policy protects.
• when - The condition that determines when the policy should apply.
• action - What happens when the condition evaluates to true.

A simple policy looks like this:

{
  "defaults": {
    "on_violation": "fail",
    "evaluation": "pre_execution"
  },
  "policies": [
    {
      "id": "star-repo-approval",
      "target": [
        "github.repo.star"
      ],
      "when": {
        "field": "name",
        "operator": "exists"
      },
      "action": {
        "type": "POLICY_BLOCKED",
        "message": "Starring repositories is blocked."
      }
    }
  ]
}

In this example:

• The policy is identified by star-repo-approval.
• It only applies to the github.repo.star method.
• Before execution, Swytchcode checks whether the name field exists in the request.
• If the condition matches, execution is blocked and the provided message is returned.

The complete policies.json schema, supported operators, and advanced examples are covered in the policies.json reference.

What Can Policies Protect?

Policies can validate any request before execution.

Some common use cases include:

Financial Protection

Prevent expensive or risky operations.

Examples:

• Block payments above a threshold.
• Restrict refunds above a specific amount.
• Block high-value transactions outright, and treat raising the limit as a reviewed change to policies.json rather than a runtime approval step - Swytchcode’s policy actions can only allow or block a request, there’s no built-in human-approval action type.

---

Production Safety

Protect production environments from accidental changes.

Examples:

• Block delete operations.
• Prevent infrastructure changes.
• Restrict deployment actions.

---

Authentication & Access

Ensure requests meet your organization’s security requirements.

Examples:

• Require authentication fields.
• Restrict operations to approved users.
• Allow requests only from trusted environments.

---

Business Rules

Enforce organization-specific policies.

Examples:

• Only allow company email domains.
• Restrict API usage to business hours.
• Limit operations by department or region.

---

API Protection

Prevent misuse of third-party APIs.

Examples:

• Limit request frequency.
• Prevent duplicate operations.
• Restrict access to specific providers.

---

Defense in Depth

Policies are only one layer of protection.

A production-ready AI application should combine multiple safety mechanisms.

Application Logic
        │
        ▼
Trusted Tools
        │
        ▼
Policy Validation
        │
        ▼
Authentication
        │
        ▼
Execution Policies
        │
        ▼
Provider API

Each layer reduces the likelihood of unintended or unsafe behavior.

---

Designing Effective Policies

Good policies are:

• Simple — Each policy should enforce a single rule.
• Predictable — Similar requests should always produce the same outcome.
• Explicit — Avoid relying on implicit assumptions.
• Reusable — Write policies that can protect multiple methods when appropriate.
• Version Controlled — Store policies alongside your application code.

Rather than creating one large policy with dozens of nested conditions, prefer multiple focused policies that are easier to understand and maintain.

---

Development vs Production

The same policy engine works in every environment.

During development, policies help catch mistakes before they reach external APIs.

In production, they become an additional security layer protecting critical systems and customer data.

A common workflow looks like this:

Local Development
        │
        ▼
Sandbox Testing
        │
        ▼
Policy Validation
        │
        ▼
Production Deployment

Testing policies in sandbox mode before deploying to production helps ensure your application behaves as expected.

---

Best Practices

• Keep policies under version control.
• Validate policies before deployment.
• Test new rules in sandbox environments.
• Prefer allowlists over blocklists whenever possible.
• Review policies whenever new integrations are added.
• Keep production and sandbox configurations separate.
• Enable idempotency for mutating APIs.
• Audit policy changes as part of your code review process.

---

Next Steps

Policy Rules

Learn how to write custom policies using conditions, operators, and actions to control tool execution.

Production Guardrails

Discover recommended safeguards for deploying AI agents safely in production environments.

Best Practices

Explore practical recommendations for designing maintainable, predictable, and secure policy configurations.

manifest.json

Understand how tooling.json, policies.json, and manifest.json work together to control trusted execution.