{"_id":"@agentdeploy-io/edge-sdk","_rev":"2-a079fdd22b1f5656c1b81ec4bf52450c","name":"@agentdeploy-io/edge-sdk","dist-tags":{"latest":"0.1.1"},"versions":{"0.1.0":{"name":"@agentdeploy-io/edge-sdk","version":"0.1.0","keywords":["agentdeploy","cloudflare-agents","ai-agents","edge","durable-objects","workers"],"license":"MIT","_id":"@agentdeploy-io/edge-sdk@0.1.0","maintainers":[{"name":"agentdeploy-io","email":"tomirl2020@gmail.com"}],"dist":{"shasum":"5948a8ddf2f12396caeb8a5c512f79141aa31ae7","tarball":"https://registry.npmjs.org/@agentdeploy-io/edge-sdk/-/edge-sdk-0.1.0.tgz","fileCount":12,"integrity":"sha512-sUKQLkxy/QglXhLDA/67wxnAcJ7h77oZCTY3xT6bqnSWwOXPulP7ars3YVvaqCrbD8Kpt5IKRdWJWXqSzd62GA==","signatures":[{"sig":"MEQCIGlpcoIB7gOJ87cxBIt5h+TohQfbYJHbTbEbWeC2MmMOAiAPxSVhDmaKZcwpqLs+5CfYehKy4V1kPajAmhggRnXoKA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":56646},"main":"./src/index.ts","type":"module","types":"./src/index.ts","module":"./src/index.ts","engines":{"node":">=18"},"exports":{".":{"types":"./src/index.ts","import":"./src/index.ts"}},"gitHead":"a1f3261df378e1aaca8a56a6cefd8a1c88035e8b","scripts":{"build":"tsc","typecheck":"tsc --noEmit"},"_npmUser":{"name":"agentdeploy-io","email":"tomirl2020@gmail.com"},"_npmVersion":"11.4.2","description":"Build AI agents on Cloudflare's edge with AgentDeploy billing, telemetry, and gateway integration.","directories":{},"_nodeVersion":"22.14.0","dependencies":{"ai":"^6.0.0","zod":"^4.0.0","agents":"^0.18.0","@ai-sdk/openai":"^1.0.0","@cloudflare/ai-chat":"^0.9.0","@agentdeploy-io/agents":"^0.1.0","@ai-sdk/openai-compatible":"^1.0.46"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.0","@cloudflare/workers-types":"^4.0.0"},"_npmOperationalInternal":{"tmp":"tmp/edge-sdk_0.1.0_1787173986649_0.7003528304789637","host":"s3://npm-registry-packages-npm-production"}},"0.1.1":{"name":"@agentdeploy-io/edge-sdk","version":"0.1.1","description":"Build AI agents on Cloudflare's edge with AgentDeploy billing, telemetry, and gateway integration.","license":"MIT","type":"module","main":"./src/index.ts","module":"./src/index.ts","types":"./src/index.ts","exports":{".":{"types":"./src/index.ts","import":"./src/index.ts"}},"scripts":{"build":"tsc","typecheck":"tsc --noEmit"},"engines":{"node":">=18"},"keywords":["agentdeploy","cloudflare-agents","ai-agents","edge","durable-objects","workers"],"dependencies":{"@agentdeploy-io/agents":"^0.1.0","@ai-sdk/openai":"^1.0.0","@ai-sdk/openai-compatible":"^1.0.46","@cloudflare/ai-chat":"^0.9.0","agents":"^0.18.0","ai":"^6.0.0","zod":"^4.0.0"},"devDependencies":{"@cloudflare/workers-types":"^4.0.0","typescript":"^5.7.0"},"_id":"@agentdeploy-io/edge-sdk@0.1.1","gitHead":"e9bc5095c80ec7bdfa2145a383a820370961d84b","_nodeVersion":"22.14.0","_npmVersion":"11.4.2","dist":{"integrity":"sha512-6HnM5ktvc2uGZ9IGL4SSeEcB8W0Ca2mEudwNr6MlB5DfiYkyGXe7AwhisfupBXzR6MZxYlKmYCaxSso0Z3nzsQ==","shasum":"1e125a7839eed4988c25204262049a272c574ffb","tarball":"https://registry.npmjs.org/@agentdeploy-io/edge-sdk/-/edge-sdk-0.1.1.tgz","fileCount":12,"unpackedSize":59374,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCtZXB00CSKxJA8rsT2ntvOpjwCh5fNlB6Q93mRfaf/lQIhAMVFi16jEJSRh/LpUkVvNrUDqKX/MYfpTOFJMrOIDsVY"}]},"_npmUser":{"name":"agentdeploy-io","email":"tomirl2020@gmail.com"},"directories":{},"maintainers":[{"name":"agentdeploy-io","email":"tomirl2020@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/edge-sdk_0.1.1_1787260671253_0.8129538665495513"},"_hasShrinkwrap":false}},"time":{"created":"2026-08-19T21:13:06.462Z","modified":"2026-08-20T21:17:51.646Z","0.1.0":"2026-08-19T21:13:06.817Z","0.1.1":"2026-08-20T21:17:51.494Z"},"license":"MIT","keywords":["agentdeploy","cloudflare-agents","ai-agents","edge","durable-objects","workers"],"description":"Build AI agents on Cloudflare's edge with AgentDeploy billing, telemetry, and gateway integration.","maintainers":[{"name":"agentdeploy-io","email":"tomirl2020@gmail.com"}],"readme":"# @agentdeploy-io/edge-sdk\n\nBuild AI agents on Cloudflare's edge with AgentDeploy billing, telemetry, and gateway integration.\n\n## Quick Start\n\n```bash\nnpm install @agentdeploy-io/edge-sdk agents @cloudflare/ai-chat ai zod\n```\n\n## Create a Chat Agent\n\n```typescript\nimport { createChatAgent, createHandler } from \"@agentdeploy-io/edge-sdk\";\n\nexport const Assistant = createChatAgent({\n  name: \"assistant\",\n  systemPrompt: \"You are a helpful assistant. Be concise and accurate.\",\n  maxSteps: 10,\n});\n\nexport default createHandler(Assistant);\n```\n\n## Add Tools\n\n```typescript\nimport { createChatAgent, createHandler, defineTool } from \"@agentdeploy-io/edge-sdk\";\nimport { z } from \"zod\";\n\nconst checkInventory = defineTool({\n  description: \"Check product inventory by SKU\",\n  inputSchema: z.object({ sku: z.string() }),\n  execute: async ({ sku }) => {\n    const res = await fetch(`https://api.example.com/inventory/${sku}`);\n    return res.json();\n  },\n});\n\nconst createOrder = defineTool({\n  description: \"Create a new order for a customer\",\n  inputSchema: z.object({\n    sku: z.string(),\n    quantity: z.number().int().positive(),\n    customerEmail: z.string().email(),\n  }),\n  needsApproval: true,\n  execute: async (input) => {\n    return { orderId: \"ord_\" + Date.now(), status: \"confirmed\" };\n  },\n});\n\nexport const CommerceAgent = createChatAgent({\n  name: \"commerce\",\n  systemPrompt: \"You are a sales assistant. Help customers check inventory and place orders.\",\n  tools: { checkInventory, createOrder },\n  maxSteps: 10,\n});\n\nexport default createHandler(CommerceAgent);\n```\n\n## Scheduled Agents\n\n```typescript\nimport { createAgent, createHandler } from \"@agentdeploy-io/edge-sdk\";\n\nexport const Monitor = createAgent({\n  name: \"monitor\",\n  onStart() {\n    // Schedule health checks every 5 minutes\n    this.scheduleEvery(\"*/5 * * * *\", \"healthCheck\");\n  },\n  async onSchedule(task) {\n    if (task.name === \"healthCheck\") {\n      const res = await fetch(\"https://api.example.com/health\");\n      const data = await res.json();\n      this.setState({ lastCheck: data, checkedAt: new Date().toISOString() });\n    }\n  },\n});\n\nexport default createHandler(Monitor);\n```\n\n## MCP Integration\n\n`createChatAgent()` connects to configured MCP servers automatically and merges\ntheir tools with your local ones:\n\n```typescript\nimport { createChatAgent, createHandler } from \"@agentdeploy-io/edge-sdk\";\n\nexport const ResearchAgent = createChatAgent({\n  name: \"research\",\n  systemPrompt: \"You are a research assistant with access to web scraping and database tools.\",\n  mcpServers: [\n    {\n      transport: {\n        type: \"sse\",\n        url: \"https://mcp.agentdeploy.io/sse\",\n        headers: { \"Authorization\": \"Bearer mcp_key_here\" },\n      },\n    },\n  ],\n  maxSteps: 15,\n});\n\nexport default createHandler(ResearchAgent);\n```\n\nFor manual control (e.g. inside a `createAgent()` lifecycle hook), use\n`connectMcp(agent, servers)` / `disconnectMcp(agent, name?)`:\n\n```typescript\nimport { createAgent, createHandler, connectMcp } from \"@agentdeploy-io/edge-sdk\";\n\nexport const Monitor = createAgent({\n  name: \"monitor\",\n  async onStart() {\n    const tools = await connectMcp(this, [\n      { transport: { type: \"sse\", url: \"https://mcp.example.com/sse\" } },\n    ]);\n    // tools — AI SDK tools you can pass to useGateway()/streamText()\n  },\n});\n\nexport default createHandler(Monitor);\n```\n\n## Secret Access\n\n```typescript\nimport { createAgent, createHandler, useSecrets } from \"@agentdeploy-io/edge-sdk\";\n\nexport const PaymentAgent = createAgent({\n  name: \"payments\",\n  async onRequest(request) {\n    const secrets = useSecrets<{ STRIPE_SECRET_KEY: string }>(this.env);\n    // secrets.STRIPE_SECRET_KEY — typed, throws if missing\n    const stripe = Stripe(secrets.STRIPE_SECRET_KEY);\n    // ...\n  },\n});\n\nexport default createHandler(PaymentAgent);\n```\n\n## Multi-Agent Routing\n\n```typescript\nimport { createChatAgent, createHandler } from \"@agentdeploy-io/edge-sdk\";\n\nexport const Support = createChatAgent({\n  name: \"support\",\n  systemPrompt: \"You handle customer support questions.\",\n});\n\nexport const Sales = createChatAgent({\n  name: \"sales\",\n  systemPrompt: \"You help customers with purchases.\",\n});\n\nexport const Billing = createChatAgent({\n  name: \"billing\",\n  systemPrompt: \"You handle billing inquiries.\",\n});\n\nexport default createHandler(Support, Sales, Billing);\n// Each agent accessible at /agents/support, /agents/sales, /agents/billing\n```\n\n## API Reference\n\n### `createAgent(config)`\nCreates a general-purpose Durable Object agent.\n\n| Option | Type | Description |\n|---|---|---|\n| `name` | `string` | Agent name for routing (/agents/:name/:instance) |\n| `onStart` | `function` | Called on first invocation (or wake from hibernation) |\n| `onRequest` | `function` | HTTP request handler (non-WebSocket) |\n| `onConnect` | `function` | Called on WebSocket connection |\n| `onMessage` | `function` | Called on WebSocket message |\n| `onClose` | `function` | Called on WebSocket close |\n| `onSchedule` | `function` | Scheduled task handler |\n| `tools` | `Record<string, AgentDeployTool>` | Tools the agent can call via `this.callTool()` |\n| `mcpServers` | `McpServerConfig[]` | External tool servers |\n\nInside lifecycle hooks you get `this.state`, `this.setState()`, `this.env`,\n`this.sql\\`...\\``, `this.schedule()`, `this.scheduleEvery()`,\n`this.getSchedules()`, `this.cancelSchedule()`, and `this.callTool()`.\n\n### `createChatAgent(config)`\nCreates a chat agent with streaming, message persistence, and tool calling.\n\n| Option | Type | Description |\n|---|---|---|\n| `name` | `string` | Agent name for routing |\n| `systemPrompt` | `string \\| function` | System prompt (function receives `AgentContext`) |\n| `model` | `string?` | Model hint (platform may override) |\n| `tools` | `Record<string, AgentDeployTool>` | Available tools |\n| `mcpServers` | `McpServerConfig[]` | External tool servers |\n| `maxSteps` | `number?` | Max tool-call rounds (default: 10) |\n| `temperature` | `number?` | Sampling temperature (provider default if omitted) |\n| `maxTokens` | `number?` | Max completion tokens (provider default if omitted) |\n| `onBeforeChat` | `function?` | Called before each chat message is processed |\n| `onAfterChat` | `function?` | Called after chat completes with token usage |\n\n### `defineTool(def)`\nDefines a typed tool with Zod schema validation and telemetry.\n\n```typescript\nconst tool = defineTool({\n  description: \"Tool description\",\n  inputSchema: z.object({ /* ... */ }),\n  needsApproval: false, // set true to require approval before execution\n  execute: async (input, ctx) => { /* ... */ },\n});\n```\n\n### `useGateway(modelName?, env?)`\nReturns an AI SDK model that routes through AgentDeploy's gateway. Used\ninternally by `createChatAgent()`; useful for direct LLM access in scheduled\nagents or custom tools.\n\n### `gatewayUrl()`\nReturns the raw gateway base URL for custom `fetch` calls.\n\n### `gatewayHeaders()`\nReturns the deployment headers (`X-AD-Deployment`) for manual gateway calls.\n\n### `useSecrets<T>(env)`\nTyped access to deployment secrets. Throws a descriptive error when a required\nsecret is missing (in local dev it warns instead, so you can iterate without\nsetting up `.dev.vars`).\n\n### `hasSecret(env, key)`\nChecks whether a secret is configured without throwing.\n\n### `getSecret(env, key, fallback?)`\nGets a secret value, returning a fallback when it's not configured.\n\n### `connectMcp(agent, servers)`\nConnects to MCP servers and returns their tools merged as AI SDK tools.\n`createChatAgent()` calls this automatically when `mcpServers` is set.\n\n### `disconnectMcp(agent, name?)`\nDisconnects from MCP servers (all, or one by name).\n\n### `createHandler(...agentClasses)`\nCreates the worker fetch handler with agent routing, `/health` and `/info`\nendpoints, CORS handling, and a 404 response for unknown routes.\n\n## How It Works\n\n1. You write agents using the SDK's `createAgent()` / `createChatAgent()`\n2. The `@agentdeploy-io/cli` bundles your code with esbuild into a single ESM module\n3. The platform's renderer injects `AD_DEPLOYMENT_ID`, `AD_MODEL`, `AD_GATEWAY_BASE_URL` constants\n4. The deploy pipeline auto-detects Durable Object classes and configures bindings + migrations\n5. All LLM calls route through the AgentDeploy gateway for billing and token metering\n\n## License\n\nMIT\n","readmeFilename":"README.md"}