Skip to main content

Quick Start

Get your first SDK-based edge agent from scaffold to marketplace in under 15 minutes.

Prerequisites​

  • Node.js 18+ installed
  • An AgentDeploy seller account
  • The @agentdeploy/cli installed:
npm install -g @agentdeploy/cli

Step 1: Scaffold your agent​

ad init --template chat-agent my-first-agent
cd my-first-agent
npm install

This creates a complete project:

my-first-agent/
├── .agentdeploy/
│   └── config.json       # AgentDeploy project config
├── src/
│   ├── server.ts          # Your agent entry point
│   └── tools.ts           # Tool definitions
├── package.json
├── tsconfig.json
├── wrangler.jsonc
└── .gitignore

Step 2: Write your agent​

Open src/server.ts — you'll see the generated agent:

import { createChatAgent, createHandler } from "@agentdeploy/edge-sdk";

export const MyAgent = createChatAgent({
  name: "my-first-agent",
  systemPrompt: `You are a helpful AI assistant built on AgentDeploy.
Be concise, accurate, and friendly.`,
  maxSteps: 10,
});

export default createHandler(MyAgent);

Let's add a tool. Edit src/tools.ts:

import { defineTool } from "@agentdeploy/edge-sdk";
import { z } from "zod";

export const getJoke = defineTool({
  description: "Tell a random programming joke",
  inputSchema: z.object({}),
  execute: async () => {
    const jokes = [
      "Why do programmers prefer dark mode? Because light attracts bugs.",
      "How many programmers does it take to change a light bulb? None — that's a hardware problem.",
      "A SQL query walks into a bar, walks up to two tables and asks: 'Can I join you?'",
    ];
    return { joke: jokes[Math.floor(Math.random() * jokes.length)] };
  },
});

Now wire it into your agent in src/server.ts:

import { createChatAgent, createHandler } from "@agentdeploy/edge-sdk";
import { getJoke } from "./tools.js";

export const MyAgent = createChatAgent({
  name: "my-first-agent",
  systemPrompt: `You are a fun AI assistant. Use the getJoke tool when asked for a joke.`,
  tools: { getJoke },
  maxSteps: 10,
});

export default createHandler(MyAgent);

Step 3: Run locally​

ad dev

This wraps wrangler dev — your agent runs at http://localhost:8787. The SDK provides:

  • /agents/my-first-agent/<instance> — WebSocket endpoint for chat streaming
  • /health — Platform health check (auto-generated by createHandler)
  • /info — Agent metadata

Test the chat endpoint:

curl http://localhost:8787/health
# {"status":"ok","deploymentId":"local-dev","agents":["MyAgent"]}

Step 4: Login and deploy​

# Authenticate (get your API key from Dashboard > Settings > API Keys)
ad login --api-key ad_live_xxxxxxxxxx

# Deploy to AgentDeploy
ad deploy

The deploy command:

  1. Bundles your TypeScript with esbuild into a single ESM module
  2. Uploads to the platform as a new edge version
  3. Validates for security and compatibility (auto-detects Durable Object classes, SDK imports, compatibility flags)
  4. Publishes the version to the marketplace

You'll see output like:

  [1/5] Bundling with esbuild...
         ✓ Bundle size: 412.3 KB
  [2/5] Uploading version 0.1.202501201430...
         ✓ Version ID: ver_abc123
  [3/5] Validating...
         ✓ Validation passed
  [4/5] Publishing...
         ✓ Published
  [5/5] Provisioning new deployment...

Step 5: Security scan​

If you also connect a GitHub repo, the platform runs 5 security scanners:

  1. gitleaks — hardcoded secrets detection
  2. semgrep — static analysis (SAST)
  3. osv-scanner — dependency vulnerabilities
  4. LLM scanner — prompt injection detection
  5. Permission scoper — Cloudflare permission analysis

You need a C rating or higher to appear on the marketplace.

For CLI-only deployments (no GitHub), the platform validates your bundled code against the same security rules during the upload step.

Step 6: Buyers deploy your agent​

When a buyer purchases your template and deploys it:

  1. They pick a hosting plan (Starter, Pro, or Business)
  2. The platform deploys your agent to Cloudflare's global network
  3. Durable Object bindings, SQLite migrations, and compatibility flags are auto-detected
  4. LLM calls route through the gateway for billing/metering
  5. The buyer gets a live URL for their agent

You earn:

  • 70% of the template purchase price
  • 25% of their monthly hosting subscription (proportional to deployments)
  • 10% of token overage markup

See Revenue Share for the full breakdown.

Next steps​