{"_id":"@agentshieldhq/sdk","name":"@agentshieldhq/sdk","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@agentshieldhq/sdk","version":"1.0.0","description":"AgentShield — Deterministic Runtime Policy Engine for AI Agents. Intercept, evaluate, and govern every tool call.","main":"dist/index.js","types":"dist/index.d.ts","type":"module","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","default":"./dist/index.js"}},"scripts":{"build":"tsc","prepublishOnly":"npm run build","test":"vitest run","test:watch":"vitest","lint":"tsc --noEmit"},"license":"Apache-2.0","keywords":["ai","agent","policy","governance","shield","runtime","safety","agentshield","zero-trust","guardrails","tool-call","evaluation","langchain","openai","llm"],"repository":{"type":"git","url":"git+https://github.com/sharif418/agentshield.git","directory":"packages/sdk"},"homepage":"https://github.com/sharif418/agentshield#readme","sideEffects":false,"dependencies":{"@agentshieldhq/core":"^1.0.0"},"peerDependencies":{},"devDependencies":{"typescript":"^5","vitest":"^4.1.4"},"publishConfig":{"access":"public"},"gitHead":"f66e9ad4d9171818d6474a892fe586533f180fdf","_id":"@agentshieldhq/sdk@1.0.0","bugs":{"url":"https://github.com/sharif418/agentshield/issues"},"_nodeVersion":"25.6.1","_npmVersion":"11.9.0","dist":{"integrity":"sha512-glLZQsLDU5aUnUaybubLs90BK3hH15QEVLrgIHMvS4pH7vqdI8XxJp+nPw0NABzTC9kdi/v/cXtsBv0QEfe7jg==","shasum":"51dbc58a885ecac7cd2753102046844df5951624","tarball":"https://registry.npmjs.org/@agentshieldhq/sdk/-/sdk-1.0.0.tgz","fileCount":27,"unpackedSize":96689,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIC3nwCJc1f1oWPQqFErPW8BNRKjKQpyVYuFHI0lTv6v9AiBIWCwUWXM866OS0W7P6ej5Iuw1VI9z33UcfMXw3+KebA=="}]},"_npmUser":{"name":"sharif418","email":"m0hammadnasrullah326@gmail.com"},"directories":{},"maintainers":[{"name":"sharif418","email":"m0hammadnasrullah326@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_1.0.0_1777468339690_0.22655404523193834"},"_hasShrinkwrap":false}},"time":{"created":"2026-04-29T13:12:19.572Z","1.0.0":"2026-04-29T13:12:19.836Z","modified":"2026-04-29T13:12:20.080Z"},"maintainers":[{"name":"sharif418","email":"m0hammadnasrullah326@gmail.com"}],"description":"AgentShield — Deterministic Runtime Policy Engine for AI Agents. Intercept, evaluate, and govern every tool call.","homepage":"https://github.com/sharif418/agentshield#readme","keywords":["ai","agent","policy","governance","shield","runtime","safety","agentshield","zero-trust","guardrails","tool-call","evaluation","langchain","openai","llm"],"repository":{"type":"git","url":"git+https://github.com/sharif418/agentshield.git","directory":"packages/sdk"},"bugs":{"url":"https://github.com/sharif418/agentshield/issues"},"license":"Apache-2.0","readme":"# agentshield\n\n[![npm version](https://img.shields.io/npm/v/agentshield.svg)](https://www.npmjs.com/package/agentshield) [![license](https://img.shields.io/npm/l/agentshield.svg)](https://github.com/agentshield/agentshield/blob/main/LICENSE) [![TypeScript](https://img.shields.io/badge/TypeScript-5-blue.svg)](https://www.typescriptlang.org/)\n\nDeterministic runtime policy engine for AI agents. Intercept, evaluate, and govern every tool call your agents make.\n\n## Installation\n\n```bash\nnpm install @agentshieldhq/sdk\n```\n\n## Quick Start\n\n### Embedded Mode (No Server Needed)\n\nRun the policy engine entirely in-memory. Ideal for serverless functions, edge runtimes, or lightweight integrations.\n\n```typescript\nimport { AgentShield } from '@agentshieldhq/sdk';\n\nconst shield = new AgentShield({\n  mode: 'embedded',\n  policies: [\n    {\n      policyId: 'POL-001',\n      name: 'Block DROP on PostgreSQL',\n      agentRole: 'DataAgent',\n      resource: 'PostgreSQL',\n      action: 'DROP',\n      permissionLevel: 'BLOCK',\n      priority: 20,\n      enabled: true,\n    },\n    {\n      policyId: 'POL-002',\n      name: 'Require approval for writes',\n      agentRole: 'DataAgent',\n      resource: 'PostgreSQL',\n      action: 'WRITE',\n      permissionLevel: 'REQUIRE_APPROVAL',\n      priority: 10,\n      enabled: true,\n    },\n    {\n      policyId: 'POL-003',\n      name: 'Allow SELECT queries',\n      agentRole: 'DataAgent',\n      resource: 'PostgreSQL',\n      action: 'READ',\n      permissionLevel: 'ALLOW',\n      priority: 5,\n      enabled: true,\n    },\n  ],\n});\n\n// Evaluate a tool call\nconst result = await shield.evaluate({\n  agentRole: 'DataAgent',\n  toolName: 'PostgreSQL',\n  arguments: { query: 'DROP TABLE users' },\n});\n\nconsole.log(result.decision); // 'BLOCK'\nconsole.log(result.reason);   // 'Blocked by policy: Block DROP on PostgreSQL'\n```\n\n### Hosted Mode (Connects to Server)\n\nConnect to a running AgentShield server for centralized policy management, persistent storage, and audit trails.\n\n```typescript\nimport { AgentShield } from '@agentshieldhq/sdk';\n\nconst shield = new AgentShield({\n  mode: 'hosted',\n  serverUrl: 'https://agentshield.example.com',\n  apiKey: 'sk-...',\n});\n\nconst result = await shield.evaluate({\n  agentRole: 'DataAgent',\n  toolName: 'PostgreSQL',\n  action: 'DROP',\n  arguments: { query: 'DROP TABLE users' },\n});\n\nconsole.log(result.decision); // 'BLOCK'\nconsole.log(result.traceId);  // 'TRC-...'\n```\n\n### Convenience Factory\n\n```typescript\nimport { createAgentShield } from '@agentshieldhq/sdk';\n\nconst shield = createAgentShield({\n  mode: 'embedded',\n  policies: [/* ... */],\n  defaultAgentRole: 'DataAgent',\n  zeroTrust: true,\n});\n```\n\n## Managing Policies (Embedded Mode)\n\n```typescript\nconst shield = new AgentShield({\n  mode: 'embedded',\n  policies: [],\n});\n\n// Create a policy\nconst policy = await shield.createPolicy({\n  name: 'Block SQL DROP',\n  agentRole: 'DataAgent',\n  resource: 'PostgreSQL',\n  action: 'DROP',\n  permissionLevel: 'BLOCK',\n  priority: 20,\n});\n\n// Add or update a policy\nshield.addPolicy({\n  policyId: 'POL-004',\n  name: 'Allow reads',\n  agentRole: '*',\n  resource: 'PostgreSQL',\n  action: 'READ',\n  permissionLevel: 'ALLOW',\n  priority: 5,\n  enabled: true,\n});\n\n// List policies\nconst all = await shield.listPolicies();\nconst filtered = await shield.listPolicies({ agentRole: 'DataAgent' });\n\n// Get a specific policy\nconst p = await shield.getPolicy('POL-004');\n\n// Remove a policy\nshield.removePolicy('POL-004');\n\n// Replace all policies at once\nshield.setPolicies([/* new policy set */]);\n\n// Count\nconsole.log(shield.policyCount); // number | undefined\n```\n\n## Managing Policies (Hosted Mode)\n\nIn hosted mode, policy management delegates to the server via HTTP:\n\n```typescript\nconst shield = new AgentShield({\n  mode: 'hosted',\n  serverUrl: 'https://agentshield.example.com',\n  apiKey: 'sk-...',\n});\n\nawait shield.createPolicy({ name: 'New Policy', /* ... */ });\nawait shield.listPolicies({ enabled: true });\nawait shield.getPolicy('POL-001');\nawait shield.deletePolicy('POL-001');\n```\n\n## Execution Traces\n\n```typescript\n// Get a specific trace\nconst trace = await shield.getTrace('TRC-abc123');\n\n// List traces with filters\nconst traces = await shield.listTraces({\n  sessionId: 'SES-xyz',\n  agentRole: 'DataAgent',\n  evaluationResult: 'BLOCK',\n  limit: 50,\n  offset: 0,\n});\n```\n\n## Health Check\n\n```typescript\nconst isUp = await shield.isHealthy();\n```\n\n## API Reference\n\n### `AgentShield`\n\nMain SDK class providing a unified API for evaluating AI agent tool calls against governance policies.\n\n#### Constructor\n\n```typescript\nnew AgentShield(config: AgentShieldConfig)\n```\n\nThrows if `serverUrl` is missing in hosted mode.\n\n#### Methods\n\n| Method | Returns | Description |\n|---|---|---|\n| `evaluate(request)` | `Promise<EvaluateResult>` | Evaluate a tool call against active policies |\n| `createPolicy(params)` | `Promise<PolicyDefinition>` | Create a new policy |\n| `listPolicies(params?)` | `Promise<PolicyDefinition[]>` | List policies with optional filters |\n| `getPolicy(policyId)` | `Promise<PolicyDefinition \\| undefined>` | Get a policy by ID |\n| `deletePolicy(policyId)` | `Promise<boolean \\| void>` | Delete a policy by ID |\n| `getTrace(traceId)` | `Promise<Trace \\| unknown>` | Get a trace by ID |\n| `listTraces(params?)` | `Promise<Trace[] \\| unknown>` | List traces with optional filters |\n| `isHealthy()` | `Promise<boolean>` | Check health of client/engine |\n| `addPolicy(policy)` | `void` | Add or update a policy (embedded only) |\n| `removePolicy(policyId)` | `boolean` | Remove a policy (embedded only) |\n| `setPolicies(policies)` | `void` | Replace all policies (embedded only) |\n\n#### Properties\n\n| Property | Type | Description |\n|---|---|---|\n| `mode` | `'hosted' \\| 'embedded'` | Current operating mode |\n| `policyCount` | `number \\| undefined` | Number of stored policies (embedded only) |\n| `traceCount` | `number \\| undefined` | Number of stored traces (embedded only) |\n\n### `createAgentShield(config)`\n\nConvenience factory function that returns a new `AgentShield` instance.\n\n### `HostedClient`\n\nLow-level HTTP client for the AgentShield server. Used internally by `AgentShield` in hosted mode. Available for direct use if needed.\n\n```typescript\nimport { HostedClient } from '@agentshieldhq/sdk';\n\nconst client = new HostedClient('https://agentshield.example.com', 'sk-...');\nawait client.evaluate({ agentRole: 'Agent', toolName: 'Tool' });\n```\n\n### `EmbeddedEngine`\n\nIn-memory policy engine. Used internally by `AgentShield` in embedded mode. Available for direct use if needed.\n\n```typescript\nimport { EmbeddedEngine } from '@agentshieldhq/sdk';\n\nconst engine = new EmbeddedEngine(policies, /* zeroTrust: */ true);\nconst result = engine.evaluate({ agentRole: 'Agent', toolName: 'Tool' });\n```\n\n## Types\n\n### `AgentShieldConfig`\n\n```typescript\ninterface AgentShieldConfig {\n  serverUrl?: string;           // Server URL (hosted mode)\n  apiKey?: string;              // API key for authentication\n  mode: 'hosted' | 'embedded'; // Operating mode\n  policies?: Policy[];          // Initial policies (embedded mode)\n  defaultAgentRole?: string;    // Default agent role for evaluate()\n  defaultSessionId?: string;    // Default session ID\n  zeroTrust?: boolean;          // Default deny when no match (default: true)\n  fetch?: typeof fetch;         // Custom fetch (edge runtime, etc.)\n}\n```\n\n### `PolicyCreateParams`\n\n```typescript\ninterface PolicyCreateParams {\n  policyId?: string;            // Auto-generated if omitted\n  name: string;\n  description?: string;\n  agentRole: string;\n  resource: string;\n  action: string;\n  permissionLevel: Decision;\n  conditionRules?: string | Record<string, unknown>;\n  priority?: number;            // Default: 0\n  enabled?: boolean;            // Default: true\n}\n```\n\n### `PolicyListParams`\n\n```typescript\ninterface PolicyListParams {\n  agentRole?: string;\n  resource?: string;\n  permissionLevel?: Decision;\n  enabled?: boolean;\n}\n```\n\n### `TraceListParams`\n\n```typescript\ninterface TraceListParams {\n  sessionId?: string;\n  agentRole?: string;\n  evaluationResult?: Decision;\n  toolName?: string;\n  limit?: number;\n  offset?: number;\n}\n```\n\nAll core types (`Decision`, `Policy`, `EvaluateRequest`, `EvaluateResult`, `ConditionRule`, `MatchedPolicy`, `Trace`) are re-exported from `@agentshieldhq/core`. See the [core package documentation](https://www.npmjs.com/package/@agentshieldhq/core) for full type definitions.\n\n## Re-exported Core Functions\n\nThe SDK re-exports all evaluation functions from `@agentshieldhq/core` for advanced usage:\n\n```typescript\nimport {\n  evaluatePolicies,\n  evaluateConditions,\n  inferAction,\n  enrichArgsFromQuery,\n  getMatchingActions,\n} from '@agentshieldhq/sdk';\n```\n\nSee [@agentshieldhq/core](https://www.npmjs.com/package/@agentshieldhq/core) for documentation on these functions.\n\n## Related Packages\n\n- **[@agentshieldhq/core](https://www.npmjs.com/package/@agentshieldhq/core)** — Low-level evaluation engine (used internally)\n- **[@agentshieldhq/langchain](https://www.npmjs.com/package/@agentshieldhq/langchain)** — LangChain callback handler integration\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-c56612f367ec1fcf5c319adf1e61557c"}