Skip to content

Build & Verify Your Agent with AI — copy-paste prompts

Your hosted agent needs a small integration layer so AgentDukaan can hand it buyers and so it runs safely. You can write it by hand (see the Deployment Guide) — or paste one of the prompts below into an AI coding assistant (Claude, Cursor, Copilot, ChatGPT) together with your agent's code and let it do the work.

  • Prompt 1 — Build: adds the AgentDukaan integration to your agent.
  • Prompt 2 — Check: audits an existing agent and tells you if it's ready to upload.
  • Prompt 3 — Self-test: generates a local script that proves your signing + endpoint work before you submit.

Each prompt is self-contained — it includes the full contract, so the assistant doesn't need to read anything else. The authoritative spec is the Webhook & Callback Contract; this page just packages it for an AI.

How to use

  1. Open your agent's repository in your AI assistant (or paste your main files).
  2. Copy a prompt below into the chat.
  3. Replace every […] placeholder (your language/framework, how your agent is triggered, etc.).
  4. Review the generated code, set the env vars, and test (Prompt 3, or the Test webhook button on your listing).
  5. Deploy, confirm the webhook is green, and submit for QA.

You need two values from your listing: your webhook secret (provisioned per listing) and the API base URL (https://api.agentdukaan.in). Put them in env vars — never hard-code them.

What "compatible" means (the contract in 6 lines)

  1. A public HTTPS endpoint that receives a signed buyer_configured notification.
  2. It verifies the signature (HMAC-SHA256 of the raw body with your webhook secret) and replies 2xx within 10s.
  3. On that event it pulls the buyer's credentials from a signed GET …/config call — secrets are never pushed.
  4. It holds those credentials in memory only — never writes them to a database, file, or logs.
  5. It reports each billable run (and stops on 429), so run limits and analytics work.
  6. When a credential is wrong at runtime, it asks the buyer to fix it via request-config.

Prompt 1 — Add AgentDukaan integration to my agent

You are integrating my existing agent with the AgentDukaan marketplace. Add the
integration layer described by the contract below. Do not change my agent's core
logic — only add what's needed to receive buyers, fetch their credentials, run,
and report runs.

MY STACK: [e.g. Node + Express / Python + FastAPI / Go]
HOW MY AGENT IS TRIGGERED PER BUYER: [e.g. a function run(config) / a cron loop / on inbound message]
MY AGENT CODE: [paste it, or it's open in this repo]

=== AGENTDUKAAN CONTRACT (ground truth — do not invent anything beyond this) ===

CONFIG / SECRETS
- Two env vars: AGENTDUKAAN_WEBHOOK_SECRET (per-listing secret) and
  AGENTDUKAAN_API_URL (e.g. https://api.agentdukaan.in). Never hard-code them.

SIGNING
- Callback signature (for steps 2–5): hex HMAC-SHA256 of the exact string
  `${subscriptionId}.${ts}` using AGENTDUKAAN_WEBHOOK_SECRET, where ts is the
  current time in MILLISECONDS. Send headers:
    X-AgentDukaan-Ts:  <ts>
    X-AgentDukaan-Sig: <hex hmac>
  ts must be within 5 minutes of the server clock.

1) RECEIVE NOTIFICATION  (AgentDukaan -> me)
- Expose ONE public HTTPS POST route (my "webhook endpoint").
- Verify the inbound signature BEFORE trusting the body: header X-AgentDukaan-Sig
  must equal hex HMAC-SHA256 of the RAW request body bytes (not the re-serialised
  JSON) using the secret. Use a timing-safe compare. Reject with 401 if it fails.
- Respond 2xx within 10 seconds; do heavy work AFTER responding. (Delivery is
  retried 3x with backoff; a non-2xx shows the buyer "provider not reached".)
- Body shape:
    event: "buyer_configured"
    subscriptionId: string        // identifies this buyer — key everything by this
    buyerId, listingId: string
    tier: { name, priceINR, runLimitPerMonth?, features? }
    config: { ... }               // NON-sensitive settings only (no secrets here)
    sensitiveFields: string[]     // ids of the secrets I must fetch in step 2
    credentialsUrl: string        // the GET /config URL for this subscription
    ts: number
- On event "buyer_configured": fetch credentials (step 2), cache them IN MEMORY
  keyed by subscriptionId, then (re)provision my agent for that buyer. I will get
  another "buyer_configured" whenever the buyer rotates/fixes a key — re-fetch then.

2) FETCH CREDENTIALS  (me -> AgentDukaan)   [pull model]
- GET {AGENTDUKAAN_API_URL}/api/subscriptions/{subscriptionId}/config
  (or just use the credentialsUrl from the webhook), with the signing headers above.
- Response: { success: true, data: { config: { ...full config incl. sensitive values... } } }
- HOLD THE RESULT IN MEMORY ONLY. Never write fetched secrets to a database,
  file, or log line. After a restart, re-fetch (don't persist).

3) REPORT A RUN  (me -> AgentDukaan)
- Each time my agent does a billable unit of work for a buyer:
  POST {AGENTDUKAAN_API_URL}/api/subscriptions/{subscriptionId}/run  with the signing headers.
- Response: { success: true, data: { allowed: boolean, remaining: number } }
- HTTP 429 (RUN_LIMIT_EXCEEDED) => the buyer hit their monthly limit; stop serving
  that buyer until the next period.

4) HEARTBEAT (optional)  (me -> AgentDukaan)
- POST {AGENTDUKAAN_API_URL}/api/subscriptions/{subscriptionId}/heartbeat with the
  signing headers, e.g. hourly. Does not consume a run. Lets the dashboard show
  "running" vs "idle".

5) ASK THE BUYER TO FIX A CREDENTIAL  (me -> AgentDukaan)
- If a buyer's key fails at runtime (e.g. their provider returns 401):
  POST {AGENTDUKAAN_API_URL}/api/subscriptions/{subscriptionId}/request-config
  with the signing headers and JSON body:
    { "fields": ["<wizard field id, e.g. openai_api_key>"], "message": "Your OpenAI key returned 401." }
  AgentDukaan flags the subscription "action needed" and asks the buyer to re-enter
  those fields; when they do, I receive a fresh "buyer_configured" (re-fetch then).

=== END CONTRACT ===

DELIVERABLES
- The integration code in MY STACK, with secrets read from env vars and clear comments.
- A tiny reusable client with: sign(subscriptionId), fetchConfig(subscriptionId),
  reportRun(subscriptionId), heartbeat(subscriptionId), requestConfig(subscriptionId, fields, message).
- An in-memory cache (Map/dict) of subscriptionId -> config; wire fetchConfig into
  the webhook handler and reportRun into my agent's run path.
- A short README section: which env vars to set and how to run locally.
- List any assumptions you made. Do NOT add endpoints or fields not in the contract.

Prompt 2 — Check if my agent is compatible

Audit the attached agent codebase against the AgentDukaan contract below and tell
me whether it is ready to upload as a Hosted agent. Be strict — assume a reviewer
will reject anything that doesn't clearly meet the contract.

MY AGENT CODE: [paste it, or it's open in this repo]

=== AGENTDUKAAN CONTRACT (requirements) ===
- Env vars AGENTDUKAAN_WEBHOOK_SECRET + AGENTDUKAAN_API_URL; secrets not hard-coded.
- A public HTTPS POST "webhook endpoint".
- Inbound verify: header X-AgentDukaan-Sig == hex HMAC-SHA256 of the RAW body bytes
  with the secret, timing-safe compare, reject on mismatch.
- Responds 2xx within 10s; heavy work happens AFTER responding.
- Handles event "buyer_configured"; keys state by subscriptionId.
- Pulls credentials: GET {API_URL}/api/subscriptions/{subscriptionId}/config with
  X-AgentDukaan-Ts (ms) + X-AgentDukaan-Sig = HMAC-SHA256(`${subscriptionId}.${ts}`, secret).
- Fetched secrets are held IN MEMORY ONLY — never written to a DB, file, or log.
- Reports runs: POST {API_URL}/api/subscriptions/{subscriptionId}/run (same signing);
  handles HTTP 429 by pausing that buyer.
- Signs the EXACT string `${subscriptionId}.${ts}`; ts within 5 min.
- (Optional) heartbeat and request-config endpoints used appropriately.
=== END CONTRACT ===

OUTPUT — a markdown table with one row per requirement:
  | Requirement | Status (PASS / FAIL / PARTIAL / NOT FOUND) | Evidence (file:line) | Fix if not PASS |
Pay special attention to:
  - secrets being persisted anywhere (DB write, file write, console.log/print, error logs) -> FAIL
  - signing the parsed JSON instead of the raw body, or the wrong string for callbacks
  - the endpoint blocking before it returns 2xx
Then finish with:
  COMPATIBLE TO UPLOAD: YES / NO
  TOP 3 THINGS TO FIX: <ranked list, or "none">

Prompt 3 — Generate a local self-test

Write a small standalone script in [MY STACK] that lets me verify my AgentDukaan
integration locally before I submit, using AGENTDUKAAN_WEBHOOK_SECRET from env.

It should:
1) Build a sample "buyer_configured" JSON body, compute X-AgentDukaan-Sig as the hex
   HMAC-SHA256 of the RAW body with the secret, and POST it to my webhook URL
   (default http://localhost:3000/<my route>). Print the status — I expect 2xx.
2) Build the callback signature for a fake subscriptionId: ts = now in ms,
   sig = hex HMAC-SHA256 of `${subscriptionId}.${ts}` with the secret. Print a ready
   curl command for GET {API_URL}/api/subscriptions/{subscriptionId}/config and for
   POST .../run, with the X-AgentDukaan-Ts and X-AgentDukaan-Sig headers filled in,
   so I can confirm my signing matches what the server expects.
Keep it dependency-light and well commented.

Pre-submit checklist (no AI)

  • Webhook endpoint is HTTPS and publicly reachable.
  • Signature is verified over the raw body, timing-safe; bad signatures get 401.
  • Endpoint returns 2xx within 10s; provisioning happens after responding.
  • On buyer_configured, the agent fetches …/config and caches by subscriptionId.
  • Fetched secrets live in memory only — grep your code: no DB write, no file, no console.log/print of the config.
  • Each billable run calls …/run; 429 pauses that buyer until next period.
  • Callback signature is over the exact string `${subscriptionId}.${ts}`; clock is roughly correct (ts within 5 min).
  • Secrets come from env vars, not the code.
  • Test webhook on your listing is green.

When all boxes are ticked, submit for QA from the listing creator (see the Deployment Guide).

See also