Agent Integration

Agent Onboarding

This guide shows you how to give any AI agent the ability to check availability and book meetings using Slotflow. Works with OpenAI, Claude, LangChain, or any agent framework.

The agent workflow

Every Slotflow agent integration follows this flow:

User says "book me a demo" or "schedule a call"
         │
         ▼
┌─────────────────────┐
│  Get available slots │  GET /v1/humans/:id/slots
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  Present options     │  Show 2-3 times to the user
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  Book the slot       │  POST /v1/bookings
└─────────┬───────────┘
          │
     ┌────┴────┐
     │         │
  Success    409 Conflict
     │         │
     ▼         ▼
  Confirm    Re-query slots
  to user    and retry

Step 1: Add Slotflow as a tool

Define the Slotflow tools your agent can call. Here are the three core operations:

OpenAI function calling

1[
2  {
3    "type": "function",
4    "function": {
5      "name": "get_available_slots",
6      "description": "Find available booking slots for a team member. Call this before booking to get valid times.",
7      "parameters": {
8        "type": "object",
9        "properties": {
10          "human_id": { "type": "string", "description": "ID of the team member (e.g. hu_abc123)" },
11          "date_from": { "type": "string", "description": "Start date YYYY-MM-DD" },
12          "date_to": { "type": "string", "description": "End date YYYY-MM-DD" },
13          "duration": { "type": "integer", "description": "Meeting duration in minutes" }
14        },
15        "required": ["human_id", "date_from", "date_to", "duration"]
16      }
17    }
18  },
19  {
20    "type": "function",
21    "function": {
22      "name": "create_booking",
23      "description": "Book a specific time slot. Always call get_available_slots first.",
24      "parameters": {
25        "type": "object",
26        "properties": {
27          "human_id": { "type": "string" },
28          "starts_at": { "type": "string", "description": "UTC time from get_available_slots response" },
29          "duration": { "type": "integer" },
30          "attendee_name": { "type": "string" },
31          "attendee_email": { "type": "string" },
32          "metadata": { "type": "object", "description": "Workflow context (lead_id, ticket_id, etc.)" }
33        },
34        "required": ["human_id", "starts_at", "duration", "attendee_name"]
35      }
36    }
37  },
38  {
39    "type": "function",
40    "function": {
41      "name": "cancel_booking",
42      "description": "Cancel an existing booking. Frees the time slot.",
43      "parameters": {
44        "type": "object",
45        "properties": {
46          "booking_id": { "type": "string" }
47        },
48        "required": ["booking_id"]
49      }
50    }
51  }
52]

Claude tool use

1[
2  {
3    "name": "get_available_slots",
4    "description": "Find available booking slots for a team member. Call this before booking to get valid times.",
5    "input_schema": {
6      "type": "object",
7      "properties": {
8        "human_id": { "type": "string", "description": "ID of the team member" },
9        "date_from": { "type": "string", "description": "Start date YYYY-MM-DD" },
10        "date_to": { "type": "string", "description": "End date YYYY-MM-DD" },
11        "duration": { "type": "integer", "description": "Meeting duration in minutes" }
12      },
13      "required": ["human_id", "date_from", "date_to", "duration"]
14    }
15  },
16  {
17    "name": "create_booking",
18    "description": "Book a specific time slot. Always call get_available_slots first.",
19    "input_schema": {
20      "type": "object",
21      "properties": {
22        "human_id": { "type": "string" },
23        "starts_at": { "type": "string", "description": "UTC time from get_available_slots" },
24        "duration": { "type": "integer" },
25        "attendee_name": { "type": "string" },
26        "attendee_email": { "type": "string" },
27        "metadata": { "type": "object" }
28      },
29      "required": ["human_id", "starts_at", "duration", "attendee_name"]
30    }
31  },
32  {
33    "name": "cancel_booking",
34    "description": "Cancel an existing booking. Frees the time slot.",
35    "input_schema": {
36      "type": "object",
37      "properties": {
38        "booking_id": { "type": "string" }
39      },
40      "required": ["booking_id"]
41    }
42  }
43]

Step 2: Add context to your system prompt

Give your agent the Slotflow API reference so it can construct correct calls. We provide two machine-readable files:

FileWhen to useSize
llms.txtAgent needs to know what Slotflow is (routing decisions)~2 KB
llms-full.txtAgent needs to make API calls (include full reference)~8 KB

Example system prompt

You are a customer support agent for Acme Corp. When a customer needs
to speak with a human, use the Slotflow API to schedule a callback.
{contents of llms-full.txt}
Your Slotflow API key: use the SLOTFLOW_API_KEY environment variable.
Team members available for callbacks:
- Lisa Park (Billing): hu_lisa_id
- James Wu (Technical): hu_james_id
Rules:
- Always check available slots before booking
- Present 2-3 time options to the customer
- Include the ticket_id in booking metadata
- If a slot is taken (409), silently re-query and offer alternatives

Step 3: Implement the tool handlers

When your agent calls a Slotflow tool, execute the API call and return the result.

With the Node.js SDK

1import { SlotflowClient } from "slotflow";
2
3const slotflow = new SlotflowClient({
4  token: process.env.SLOTFLOW_API_KEY,
5});
6
7async function handleToolCall(name, args) {
8  switch (name) {
9    case "get_available_slots":
10      return await slotflow.slots.getAvailableSlots({
11        humanId: args.human_id,
12        date_from: args.date_from,
13        date_to: args.date_to,
14        duration: args.duration,
15      });
16
17    case "create_booking":
18      return await slotflow.bookings.createBooking({
19        human_id: args.human_id,
20        starts_at: args.starts_at,
21        duration: args.duration,
22        attendee_name: args.attendee_name,
23        attendee_email: args.attendee_email,
24        metadata: args.metadata,
25      });
26
27    case "cancel_booking":
28      return await slotflow.bookings.cancelBooking(args.booking_id);
29  }
30}

With raw HTTP (Python)

1import requests
2
3API_KEY = os.environ["SLOTFLOW_API_KEY"]
4BASE = "https://api.slotflow.dev/v1"
5headers = {"Authorization": f"Bearer {API_KEY}"}
6
7def handle_tool_call(name, args):
8    if name == "get_available_slots":
9        return requests.get(
10            f"{BASE}/humans/{args['human_id']}/slots",
11            headers=headers,
12            params={
13                "date_from": args["date_from"],
14                "date_to": args["date_to"],
15                "duration": args["duration"],
16            },
17        ).json()
18
19    elif name == "create_booking":
20        return requests.post(
21            f"{BASE}/bookings",
22            headers=headers,
23            json=args,
24        ).json()
25
26    elif name == "cancel_booking":
27        return requests.delete(
28            f"{BASE}/bookings/{args['booking_id']}",
29            headers=headers,
30        ).json()

Best practices

  1. Always query slots before booking — never let the agent guess at times. The slots endpoint returns exactly what’s available.

  2. Handle 409 conflicts gracefully — when multiple agents book simultaneously, conflicts happen. Build retry logic: re-query slots and try the next available time.

  3. Use metadata — attach workflow context (lead IDs, ticket numbers, conversation IDs) to every booking. This flows through to webhook payloads so downstream systems stay in sync.

  4. Present times in the user’s timezone — slots come back in UTC. Convert using the timezone field from the slots response before showing to end users.

  5. Keep the API reference in context — include llms-full.txt in your agent’s system prompt so it constructs correct API calls without hallucinating endpoints.

Agent-friendly design

Slotflow is built specifically for AI agents:

  • Fixed time slots — discrete, bookable slots. No ambiguity, no computation needed.
  • Deterministic responses — same query always returns the same results.
  • Machine-readable errors — stable error.code field (e.g. SLOT_UNAVAILABLE, LIMIT_REACHED). Agents should switch on codes, not parse messages.
  • UTC timestamps — no timezone ambiguity in API responses.
  • Metadata passthrough — arbitrary JSON on every booking, flowing through to webhooks.

What’s next?

AI Sales Agent

Full walkthrough: build an AI SDR that books demos.

Error Handling

All error codes and agent strategies for each one.