{"_id":"@agenr/sdk","name":"@agenr/sdk","dist-tags":{"latest":"0.1.0"},"versions":{"0.1.0":{"name":"@agenr/sdk","version":"0.1.0","description":"TypeScript SDK for the Agent Gateway Protocol (AGP) — let your AI agent interact with real-world businesses","license":"MIT","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsup","dev":"tsup --watch","clean":"rm -rf dist","typecheck":"tsc --noEmit","prepublishOnly":"bun run typecheck && bun run build"},"devDependencies":{"tsup":"^8.0.0","typescript":"^5.7.0"},"repository":{"type":"git","url":"git+https://github.com/agenr-ai/agenr.git","directory":"packages/sdk"},"homepage":"https://agenr.ai","keywords":["agp","ai-agents","agent-gateway","commerce","sdk","typescript","ai","llm"],"gitHead":"b6a3415f5f4e600005b25884bf3b5b66fb34de8f","_id":"@agenr/sdk@0.1.0","bugs":{"url":"https://github.com/agenr-ai/agenr/issues"},"_nodeVersion":"24.13.0","_npmVersion":"11.8.0","dist":{"integrity":"sha512-WYg6+iR7lPoWBUadWiRXx/m2j4Z6mSZLr5u+WDtdCQM3XBvFhjByFRvzk0eSxoydfKB28F9PRGFgKX/ZzjTDOw==","shasum":"91fa5b4dd2f65e7c078fdf7a7af1fef18810e69b","tarball":"https://registry.npmjs.org/@agenr/sdk/-/sdk-0.1.0.tgz","fileCount":9,"unpackedSize":57869,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCICnsT/vmQnn3ROrKwDDTBE2D++GijNbyuyT2g4r4spMPAiEA+9xg8bfyFM63WS3KKMR6Md4rIGnycathuGHJKa42qUs="}]},"_npmUser":{"name":"jdvmi00","email":"jimmartin@gmail.com"},"directories":{},"maintainers":[{"name":"jdvmi00","email":"jimmartin@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/sdk_0.1.0_1771021880272_0.18656037152007676"},"_hasShrinkwrap":false}},"time":{"created":"2026-02-13T22:31:20.125Z","0.1.0":"2026-02-13T22:31:20.422Z","modified":"2026-02-13T22:31:20.701Z"},"maintainers":[{"name":"jdvmi00","email":"jimmartin@gmail.com"}],"description":"TypeScript SDK for the Agent Gateway Protocol (AGP) — let your AI agent interact with real-world businesses","homepage":"https://agenr.ai","keywords":["agp","ai-agents","agent-gateway","commerce","sdk","typescript","ai","llm"],"repository":{"type":"git","url":"git+https://github.com/agenr-ai/agenr.git","directory":"packages/sdk"},"bugs":{"url":"https://github.com/agenr-ai/agenr/issues"},"license":"MIT","readme":"# @agenr/sdk\n\n[![npm version](https://img.shields.io/npm/v/@agenr/sdk)](https://www.npmjs.com/package/@agenr/sdk)\n[![license](https://img.shields.io/npm/l/@agenr/sdk)](https://github.com/agenr-ai/agenr/blob/master/LICENSE)\n\n**Connect your AI agent to any business in 3 lines of code.**\n\nThe TypeScript SDK for [Agenr](https://agenr.ai) -- the trust and commerce layer for AI agents. Discover what businesses offer, query their data, and execute real transactions through a single unified protocol ([AGP](https://github.com/agenr-ai/agenr/blob/master/docs/AGP-SPEC.md)).\n\n## Install\n\n```bash\nnpm install @agenr/sdk\n```\n\n## Quick Start\n\nNo signup required. Use the public demo key with the built-in Echo adapter:\n\n```ts\nimport { AgenrClient } from \"@agenr/sdk\";\n\nconst agenr = new AgenrClient({ apiKey: \"ak_test_public_demo\" });\n\n// What can this business do?\nconst capabilities = await agenr.discover(\"echo\");\n\n// Browse their catalog\nconst catalog = await agenr.query(\"echo\", { serviceId: \"catalog\" });\n\n// Place an order\nconst order = await agenr.execute(\"echo\", {\n  serviceId: \"order\",\n  items: [{ productId: \"echo-widget-1\", quantity: 2 }],\n});\n```\n\nThat's it. Same three methods work for any business connected to Agenr -- restaurants, retailers, SaaS platforms, anything with an adapter.\n\n## Execute Confirmation\n\nAgenr supports two levels of confirmation to keep humans in the loop before money moves.\n\n### Simple (open policy)\n\nWhen the server runs with `AGENR_EXECUTE_POLICY=open`, agents call `execute()` directly. If the adapter needs business-level confirmation (e.g. \"confirm your payment\"), it returns `pending_confirmation` with a token:\n\n```ts\nconst result = await agenr.execute(\"echo\", {\n  serviceId: \"order\",\n  items: [{ productId: \"echo-widget-1\", quantity: 2 }],\n});\n\nif (result.data?.status === \"pending_confirmation\") {\n  const confirmed = await agenr.execute(\"echo\", {\n    serviceId: \"order\",\n    items: [{ productId: \"echo-widget-1\", quantity: 2 }],\n    confirmationToken: result.data.confirmationToken,\n  });\n}\n```\n\n<details>\n<summary><strong>Full confirmation flow (confirm/strict policy)</strong></summary>\n\nWhen the server requires API-level confirmation (`AGENR_EXECUTE_POLICY=confirm`), agents must call `prepare()` first to get a confirmation token:\n\n```ts\nconst request = {\n  serviceId: \"order\",\n  items: [{ productId: \"echo-widget-1\", quantity: 2 }],\n};\n\n// 1. Prepare -- get API-level confirmation token\nconst prepared = await agenr.prepare(\"echo\", request);\n\n// 2. Execute with API confirmation token\nconst result = await agenr.execute(\"echo\", request, {\n  confirmationToken: prepared.confirmationToken,\n  idempotencyKey: \"order-echo-widget-1-x2\",\n});\n\n// 3. If adapter also needs confirmation, call execute again\nif (result.data?.status === \"pending_confirmation\") {\n  const confirmed = await agenr.execute(\n    \"echo\",\n    { ...request, confirmationToken: result.data.confirmationToken },\n    {\n      confirmationToken: prepared.confirmationToken,\n      idempotencyKey: \"order-echo-widget-1-x2-confirm\",\n    },\n  );\n}\n```\n\n</details>\n\n## Use with AI Agent Tools\n\nWire the SDK into any tool-calling framework:\n\n```ts\nconst agenr = new AgenrClient({ apiKey: process.env.AGENR_API_KEY });\n\nconst tools = [\n  {\n    name: \"discover_business\",\n    description: \"Discover what a business can do\",\n    handler: ({ businessId }) => agenr.discover(businessId),\n  },\n  {\n    name: \"query_business\",\n    description: \"Query business data (catalog, menu, availability)\",\n    handler: ({ businessId, request }) => agenr.query(businessId, request),\n  },\n  {\n    name: \"execute_action\",\n    description: \"Execute a business action (order, book, pay)\",\n    handler: ({ businessId, request, confirmationToken, idempotencyKey }) =>\n      agenr.execute(businessId, request, { confirmationToken, idempotencyKey }),\n  },\n];\n```\n\nOr skip the SDK and use the MCP server: [`@agenr/mcp`](https://www.npmjs.com/package/@agenr/mcp)\n\n## Configuration\n\n```ts\nconst agenr = new AgenrClient({\n  apiKey: \"ak_...\",           // from agenr.ai (or ak_test_public_demo for testing)\n  baseUrl: \"https://api.agenr.ai\",  // default; override for self-hosted\n  headers: { \"X-Custom\": \"value\" }, // extra headers on every request\n});\n```\n\n## API Reference\n\n| Method | Description |\n|---|---|\n| `discover(businessId)` | What can this business do? |\n| `query(businessId, request)` | Browse data (catalog, menu, availability) |\n| `execute(businessId, request, options?)` | Take action (order, book, pay) |\n| `prepare(businessId, request)` | Get API-level confirmation token |\n| `status(transactionId)` | Check transaction status |\n\n### ExecuteOptions\n\n```ts\ninterface ExecuteOptions {\n  confirmationToken?: string; // maps to x-confirmation-token header\n  idempotencyKey?: string;    // maps to idempotency-key header\n}\n```\n\n## Types\n\n```ts\nimport type {\n  AgenrConfig,\n  AgpOperation,      // \"discover\" | \"query\" | \"execute\"\n  AgpResponse,       // { id, operation, businessId, status, data, ... }\n  AgpTransaction,    // same as AgpResponse\n  ExecuteOptions,    // { confirmationToken?, idempotencyKey? }\n  PrepareResponse,   // { confirmationToken, expiresAt, summary }\n  TransactionStatus, // \"pending\" | \"succeeded\" | \"failed\"\n} from \"@agenr/sdk\";\n```\n\n## Error Handling\n\n```ts\nimport { AgenrError } from \"@agenr/sdk\";\n\ntry {\n  await agenr.execute(\"echo\", { serviceId: \"order\" });\n} catch (err) {\n  if (err instanceof AgenrError) {\n    err.statusCode;    // HTTP status\n    err.message;       // error message\n    err.transactionId; // transaction ID (if available)\n    err.response;      // raw response payload\n  }\n}\n```\n\n## Links\n\n- [Agenr](https://agenr.ai) -- homepage\n- [AGP Spec](https://github.com/agenr-ai/agenr/blob/master/docs/AGP-SPEC.md) -- protocol reference\n- [MCP Server](https://www.npmjs.com/package/@agenr/mcp) -- plug into Claude, Cursor, or any MCP client\n- [GitHub](https://github.com/agenr-ai/agenr)\n\n## License\n\nMIT\n","readmeFilename":"README.md","_rev":"1-e16edf4c1dc528add96f2190c587e3a7"}