Keep your data in your database

​

What stays where

​

1. Build the endpoints

GET  https://api.yourapp.com/orders/{{order_id}}
POST https://api.yourapp.com/appointments    {"name": "{{name}}", "slot": "{{slot}}"}

• https only. Addresses inside private networks are refused.
• Authenticate with a header you choose, e.g. Authorization: Bearer <secret>. We store it sealed and never show it again.
• Answer within 10 seconds — callers on the phone are waiting.
• Return only what the agent needs. It reads about 4,000 characters of the answer; an order’s status, not the order history.
• Treat every argument as untrusted — it came from a stranger’s message. Use parameterised queries and never let an argument pick a table or a URL.

​

2. Connect them

1. create_action — name (get_order), a description of when to call it (the agent decides from this sentence alone), the URL with placeholders, one parameter per placeholder, and your auth header.
2. test_action with sample arguments — a real call, through the same path the agent uses. Fix errors now, not when a customer is waiting.
3. enable_action — after your approval it goes live for everyone talking to the agent.
4. update_agent — tell the agent about it in its instructions: “Look up the order with get_order before answering anything about delivery.”

​

3. Receive what happens

import { createHmac, timingSafeEqual } from "node:crypto";

export function verify(rawBody: string, header: string, secret: string): boolean {
  const expected = Buffer.from("sha256=" + createHmac("sha256", secret).update(rawBody).digest("hex"));
  const actual = Buffer.from(header ?? "");
  return expected.length === actual.length && timingSafeEqual(expected, actual);
}