How to Set Up Policy Guardrails for AI Agents with Swytchcode

Enabling a tool tells Swytchcode what an agent is capable of calling. A policy tells it what that agent is actually allowed to do with it. The two are separate layers on purpose: swy add controls capability, and swy policy controls the rules checked against every single call before it's allowed to run.

Why Guardrails Are Separate from Tool Access

It's tempting to think that enabling only the tools you trust is guardrail enough. In practice, "trusted" isn't binary. You might trust an agent to create draft records in a CRM but not to delete them. You might trust it to call a method in a sandbox but not the same method in production. You might want it to send emails, but only under a certain volume per hour. Policies let you express those narrower rules without having to withhold the tool entirely.

This is also why policy checks happen locally, at the CLI layer, before a request ever leaves your machine, rather than being enforced only after the fact. A blocked call never reaches the API at all, which is a meaningfully different guarantee than catching a mistake in a log after it's already happened.

What Kinds of Rules Policies Actually Cover

A few categories account for most of what guardrails are used for in practice:

• Rate limits. Cap how often a method can run in a given window, so an agent stuck in a loop, or simply overeager, can't quietly run up a bill or trip an upstream API's own rate limiting.
• Allowlists. Restrict a method to specific conditions, environment, account, or resource, rather than letting it run against anything it's technically capable of reaching. This is the difference between an agent that can call a delete method in a sandbox and one that can call it in production.
• Dry-run enforcement. Require a method to run in preview mode, showing what it would do without actually doing it, until you're confident enough to let it execute for real.
• A way to stop something mid-flight. Beyond preventing a single bad call, policies give you a way to intervene in a running process rather than only ever finding out afterward.

The common thread: none of these require withholding the tool entirely. An agent can still be capable of calling a destructive or expensive method; the policy is what decides when, where, and how often it's actually allowed to.

Managing Policies

Guard-policy rules live in policies.json and get evaluated before every swy exec call. You manage them through the swy policy command group rather than editing the file directly:

swy policy add
swy policy list [--json]
swy policy remove
swy policy validate

add walks you through creating a rule interactively. list shows what's currently active, with --json for a machine-readable version. remove takes a policy ID to delete one. validate checks the file against its schema, worth running any time you or a teammate has hand-edited it.

Reviewing What Got Blocked

Setting a policy is only half the picture; you also want to know when it actually stopped something. Past violations are viewable, read-only, through:

swy audit policy [--json] [-n N]
swy audit policy --info <id>

This is separate from managing the rules themselves. swy policy changes what's allowed; swy audit policy shows you the history of what wasn't.

A Reasonable Starting Point

If you're setting up guardrails for the first time, a workable approach is to start narrow and widen deliberately: enable only the specific methods an agent actually needs with swy add, rather than an entire integration at once, and add policy rules for anything with a real-world consequence, payments, deletions, external communications, before you add rules for lower-stakes actions. An allowlist restricting a risky method to a non-production environment, or a dry-run requirement on anything destructive, is usually a more useful first rule than a broad rate limit. Check swy audit policy periodically early on to see whether your rules are actually catching what you expect, and loosen or tighten from there.

Frequently Asked Questions

• What's the difference between enabling a tool and adding a policy for it? Enabling a tool with swy add determines whether an agent can call it at all. A policy adds a further rule that's checked on every single call, so you can allow a tool while still restricting how it's used.
• What kinds of rules can a policy actually enforce? Common categories include rate limits, allowlists scoped to a specific environment or condition, and dry-run enforcement that previews a call instead of executing it.
• Where do policy rules get evaluated? Locally, at the CLI layer, before a request leaves your machine. A call that violates a policy never reaches the actual API.
• How do I see what a policy has blocked? Run swy audit policy for a log of past violations, or swy audit policy --info <id> for full detail on one specific one. This is read-only; managing the rules themselves happens through swy policy.
• Can I edit policies.json directly instead of using swy policy? You can, but run swy policy validate afterward to check the file against its schema before relying on it.

Where to Go Next

• policies.json Reference: the full policy rule schema
• tooling.json, manifest.json, and policies.json Explained: how the policy file fits alongside the others
• Swytchcode CLI Commands: the complete command reference, including the full swy policy and swy audit groups
• swy exec Explained: what else happens in the same pipeline that checks policies