diff --git a/docs.json b/docs.json index 59c0ebf..772dfd2 100644 --- a/docs.json +++ b/docs.json @@ -45,6 +45,7 @@ } }, "seo": { + "indexing": "all", "metatags": { "theme-color": "#F5F4F1", "color-scheme": "light dark", @@ -85,6 +86,14 @@ "use-cases/build-a-platform" ] }, + { + "group": "Compare", + "pages": [ + "learn/compare/control-what-an-agent-can-do", + "learn/compare/proofable-or-an-identity-provider", + "learn/compare/proofable-or-a-policy-engine" + ] + }, { "group": "Reference", "pages": ["agents/index", "proofs", "verification/index", "gates/index", "jobs"] diff --git a/learn/compare/control-what-an-agent-can-do.mdx b/learn/compare/control-what-an-agent-can-do.mdx new file mode 100644 index 0000000..7ca545c --- /dev/null +++ b/learn/compare/control-what-an-agent-can-do.mdx @@ -0,0 +1,77 @@ +--- +title: "How to control what an AI agent is allowed to do" +sidebarTitle: "Control an AI agent" +description: "How do you control what an AI agent is allowed to do? Set the limits on the agent, check them at the action boundary, and keep proof of each decision." +icon: shield-halved +--- + +# How do you control what an AI agent is allowed to do? + +You control an agent by giving it an owner and explicit limits, checking those limits at the moment of the action rather than at sign-in, and keeping a record of what was decided. The check must be able to refuse, and a refusal must stop the call. + +## The short answer + +An agent needs three things before it can be trusted with a real action: an identity that names the agent and the person or team behind it, a permission that says what it may access, spend or change, and a check that runs before the action and can stop it. Instructions in a prompt are not a limit, because the model can be talked out of them. A limit that runs in the caller cannot be. + +## Set the limits + +| Limit | What it does | +| --- | --- | +| Allowed actions | Only the listed actions can run | +| Denied actions | Always blocked, and a denial wins over an allowance | +| Human approval | Irreversible actions wait for a person | +| Spend cap | Caps how much the agent can pay | +| Expiry | Permission ends on the date you set | +| Revoke | Permission ends the moment you revoke it | + +A missing, expired or revoked permission grants nothing. [Control agent actions](/use-cases/control-agent-actions) covers each field with examples. + +## Check at the boundary + +The check belongs where the tool call happens, not in the prompt and not only in the logs afterwards. + +```text +Agent report-agent +Action Publish report +Authority Draft ✓ + Publish ✕ +Decision Blocked +``` + +```ts +import { evaluateRuntimeAction } from '@proofable/sdk/runtime-mount'; + +const decision = evaluateRuntimeAction(mount, 'publish_report', { irreversible: true }); +if (!decision.allowed) throw new Error(`${decision.code}: ${decision.message}`); +``` + +[First guarded action](/mcp/guarded-action) walks through the same call with every decision code. + +## Keep proof of each decision + +A limit you cannot demonstrate is hard to rely on. Each check can leave a proof that records which agent acted, which permission applied, and whether the call was allowed or refused, so the next system can check it without repeating the work. [Prove what happened](/use-cases/prove-what-happened) and [Reuse verification](/use-cases/reuse-verification) cover the record and its reuse. + +## Common ways this goes wrong + +- **The limit lives in the prompt.** A prompt instruction is advice. Keep the limit in the caller that owns the tool. +- **The check runs after the action.** A check in the logs describes what already happened. It has to run before. +- **The agent has no owner.** Without an owner there is nobody to hold responsible and nobody who can revoke. +- **Permission never expires.** An approval given once should not last forever without a decision. +- **A denial loses to an allowance.** When both match, the denial has to win, or the narrower rule is meaningless. + +## Where to go next + + + + Set each limit and load it where the tool runs. + + + Run one allow or deny decision end to end. + + + Name the agent and its owner. + + + When to keep your own engine and what to add. + + diff --git a/learn/compare/proofable-or-a-policy-engine.mdx b/learn/compare/proofable-or-a-policy-engine.mdx new file mode 100644 index 0000000..2a9e121 --- /dev/null +++ b/learn/compare/proofable-or-a-policy-engine.mdx @@ -0,0 +1,54 @@ +--- +title: "Proofable or a policy engine for agent authorization" +sidebarTitle: "Proofable or a policy engine" +description: "Which is better for authorizing an AI agent, a policy engine or Proofable? Keep your engine when the decision stays in your system." +icon: scale-balanced +--- + +# Which is better for authorizing an AI agent, a policy engine or Proofable? + +A policy engine is better when your own team owns both the rules and every caller, and a log inside your infrastructure is enough evidence. Proofable is better when the decision has to be checked before the action runs and confirmed afterwards by a system you do not control. + +## It depends + +Keep your policy engine if you already express your rules in it, one team owns both the rules and every caller, and a log inside your infrastructure is enough evidence. Add Proofable when the agent runs somewhere you do not own, when more than one party has to rely on the outcome, or when the evidence has to travel with the action. A policy engine decides; Proofable can supply the portable record that the decision was made under current permission. Teams that already have a policy engine usually keep it and add Proofable at the boundary, rather than replacing it. + +## What each one answers + +| Question | Policy engine | Proofable | +| --- | --- | --- | +| Is this action allowed by our rules? | Yes, that is its purpose | Yes, for the agent's identity, limits and current permission | +| Who is the agent and who owns it? | Only if you modelled it there | Part of the agent record | +| Does the decision survive leaving your system? | Your log, your infrastructure | A proof another party can check | +| Can the permission expire or be revoked? | If you build that | Built in, with an end date and revoke | +| Does a refused action stop the call? | Depends on your integration | The caller stops when the decision is not allowed | + +## Where they fit together + +A policy engine is the right owner of your own rules. Proofable does not ask you to move them. It checks the agent's limits at the action boundary and records the result, so the same decision can be appraised by a system that never saw your engine. + +```ts +import { evaluateRuntimeAction } from '@proofable/sdk/runtime-mount'; + +const decision = evaluateRuntimeAction(mount, 'publish_report', { irreversible: true }); +if (!decision.allowed) throw new Error(`${decision.code}: ${decision.message}`); +``` + +Your engine can still run before or after this check. [Standards and interoperability](/learn/standards) lists the authorization and attestation layers Proofable works beside, including AuthZEN and AARM. + +## Next + + + + Every limit an agent can carry. + + + Check once and reuse the result. + + + Keep a record of each decision. + + + The layers beside Proofable. + + diff --git a/learn/compare/proofable-or-an-identity-provider.mdx b/learn/compare/proofable-or-an-identity-provider.mdx new file mode 100644 index 0000000..5b19ba5 --- /dev/null +++ b/learn/compare/proofable-or-an-identity-provider.mdx @@ -0,0 +1,63 @@ +--- +title: "Proofable or an identity provider for agent access" +sidebarTitle: "Proofable or an IdP" +description: "Which is better for controlling what an AI agent may do, an identity provider or Proofable? Run both when identity is not the same as authority." +icon: scale-balanced +--- + +# Which is better for controlling an AI agent, an identity provider or Proofable? + +An identity provider is better if the only question you must answer is who an agent is. Proofable is better if you must also answer what that agent is allowed to do right now, and keep a record another system can check. + +## It depends + +Use your identity provider alone when every agent acts on behalf of a signed-in person, the provider already issues those tokens, and you do not need to bound or record the action. Use Proofable when an agent acts on its own schedule, when the permission has to be checked at the moment of the call rather than at sign-in, or when a third party must be able to confirm the decision afterwards. Many teams run both: the provider answers who signed in, and Proofable answers whether this specific action may run. One is not a replacement for the other. + +## What each one answers + +| Question at the action boundary | Identity provider | Proofable | +| --- | --- | --- | +| Who is the caller? | Yes, it issues the identity | Records the agent and the owner behind it | +| Who does the agent work for? | Only if the agent is the person | Yes, the owner is part of the agent's identity | +| May this action run right now? | Not its job | Yes, checked before the call | +| What happens when permission is missing? | Not its job | The call stops | +| Can a third party confirm the decision later? | Session and token logs | A proof the next system can check | + +## Where the check happens + +A provider decision is made when a session or token is issued. An action runs later, often from a schedule, and the permission may have changed in between. Proofable checks at the moment of the action, so a revoked or expired permission stops the next call even though the session is still valid. + +```text +Agent report-agent +Action Publish report +Authority Draft ✓ + Publish ✕ +Decision Blocked +``` + +## Running both + +You do not have to choose. Keep the provider for sign-in, and add Proofable for the authority decision: + +1. [Add Proofable](/mcp/setup) to your assistant or app. +2. [Give the agent limits](/use-cases/control-agent-actions): allowed actions, denied actions, spend cap, expiry. +3. [Check before the tool call](/mcp/guarded-action) and stop when the decision is not allowed. + +The identity proves who is asking. The permission decides whether the action runs. [Standards and interoperability](/learn/standards) covers how Proofable works beside OAuth, OIDC, AuthZEN and agent SSO without replacing them. + +## Next + + + + Set the limits an agent runs under. + + + Run one allow or deny decision end to end. + + + Give each agent an owner you can check. + + + Where Proofable sits beside existing standards. + + diff --git a/public/robots.txt b/public/robots.txt deleted file mode 100644 index 0435b2f..0000000 --- a/public/robots.txt +++ /dev/null @@ -1,8 +0,0 @@ -# Proofable public documentation is crawlable. -# Robots rules are discovery preferences, not an access-control boundary. - -User-agent: * -Allow: / - -# Sitemap (Mintlify auto-generates one at the hosted edge). -Sitemap: https://docs.proofable.me/sitemap.xml