AgentGuard SDK Integration Guide

The AgentGuard SDK is installable middleware for protected HTTP routes. The developer contract is small:

1. Convert an incoming request into a Core decision with `verifyAgent()` or `verifyAgentEdge()`.
2. Serialize the response through `enforce()` or `enforceWithPolicy()`.
3. Emit the returned `TrafficEvent` to the dashboard stream when the Live Control Plane is enabled.

Install

```bash

npm install @agentguard/sdk

```

The repository package is already named `@agentguard/sdk`. Public npm install requires the packaging slice to remove `private: true`, add publish metadata, and run npm pack validation.

Minimal Protected Route

```ts

import { enforce, toFetchResponse, verifyAgent } from "@agentguard/sdk";

export async function handleProtectedArticle(request: Request): Promise<Response> {

const decision = verifyAgent(request, {

route: "/api/v1/content/posts/seam-debt-the-hidden-tax-on-multi-agent-handoffs/body",

action: "read",

resourceId: "seam-debt-the-hidden-tax-on-multi-agent-handoffs",

trustedOperators,

trustedDelegationPublicKeys,

requireDelegationSignature: true,

});

return toFetchResponse(enforce(decision, {

fullBody: await renderFullArticle(),

teaser: await renderArticleTeaser(),

}));

}

```

`verifyAgent()` builds the shared request context and calls Core. `enforce()` applies the shared HTTP behavior map.

| Outcome | HTTP status | Body mode |

| --- | ---: | --- |

| `allow` | 200 | Full body |

| `deny` | 200 | Teaser only |

| `priced` | 402 | Quote body |

| `queue` | 202 | Teaser only |

| `sandbox` | 200 | Teaser only |

| `throttle` | 429 | Teaser only plus `Retry-After` |

Pass the full body into `enforce()` and let the SDK select the body mode. Do not branch around enforcement in the route handler.

Trusted Headers

Incoming requests should use canonical AgentGuard headers:

| Header | Purpose |

| --- | --- |

| `x-agentguard-operator-id` | Claimed operator id resolved against server-side `trustedOperators`. |

| `x-agentguard-agent-id` | Agent id. |

| `x-agentguard-agent-name` | Display name. |

| `x-agentguard-signature` | Operator signature. |

| `x-agentguard-signed-at` | Timestamp bound into the signature. |

| `x-agentguard-delegation` | JSON or base64 JSON delegation proof. |

| `x-agentguard-request-rate` | Behavioral signal for Core. |

| `x-agentguard-prior-receipt-id` | Prior receipt for revocation paths. |

Do not trust request headers for keys, reputation, or delegation authority. Pin operator and delegation keys in server-side config or secrets.

Live Control Plane

Use `verifyAgentEdge()` for routes that feed the real dashboard and evaluate signed policy:

```ts

import {

createPolicyClient,

enforceWithPolicy,

toFetchResponse,

verifyAgentEdge,

} from "@agentguard/sdk";

const policyClient = createPolicyClient({

url: process.env.AGENTGUARD_POLICY_URL!,

trustedPolicySigners,

headers: { Authorization: `Bearer ${process.env.AGENTGUARD_POLICY_TOKEN!}` },

});

const policy = await policyClient.get();

const result = verifyAgentEdge(request, {

route,

action: "read",

resourceId,

trustedOperators,

trustedDelegationPublicKeys,

requireDelegationSignature: true,

policy,

trustedPolicySigners,

policyOwnerId: ownerId,

requestId,

});

await emitTrafficEvent(result.trafficEvent);

return toFetchResponse(enforceWithPolicy(result.decision, {

policyEvaluation: result.policyEvaluation,

fullBody,

teaser,

quote,

requestId,

}));

```

Validation

```bash

cd packages/agentguard-sdk

npm test

npm run typecheck

node tools/agentguard-smoke/run-smoke.mjs --no-install --only=sdk,swarm,proof

```

Production validation for the gated blog proof must include two curls against the same endpoint: unauthenticated/unverified returns teaser only, and verified delegated ChatGPT returns the full body plus receipt metadata.

Structured Answers