> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.slotflow.dev/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.slotflow.dev/_mcp/server.

# Agent Onboarding

> Give your AI agent scheduling superpowers in 5 minutes.

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

```json
[
  {
    "type": "function",
    "function": {
      "name": "get_available_slots",
      "description": "Find available booking slots for a team member. Call this before booking to get valid times.",
      "parameters": {
        "type": "object",
        "properties": {
          "human_id": { "type": "string", "description": "ID of the team member (e.g. hu_abc123)" },
          "date_from": { "type": "string", "description": "Start date YYYY-MM-DD" },
          "date_to": { "type": "string", "description": "End date YYYY-MM-DD" },
          "duration": { "type": "integer", "description": "Meeting duration in minutes" }
        },
        "required": ["human_id", "date_from", "date_to", "duration"]
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "create_booking",
      "description": "Book a specific time slot. Always call get_available_slots first.",
      "parameters": {
        "type": "object",
        "properties": {
          "human_id": { "type": "string" },
          "starts_at": { "type": "string", "description": "UTC time from get_available_slots response" },
          "duration": { "type": "integer" },
          "attendee_name": { "type": "string" },
          "attendee_email": { "type": "string" },
          "metadata": { "type": "object", "description": "Workflow context (lead_id, ticket_id, etc.)" }
        },
        "required": ["human_id", "starts_at", "duration", "attendee_name"]
      }
    }
  },
  {
    "type": "function",
    "function": {
      "name": "cancel_booking",
      "description": "Cancel an existing booking. Frees the time slot.",
      "parameters": {
        "type": "object",
        "properties": {
          "booking_id": { "type": "string" }
        },
        "required": ["booking_id"]
      }
    }
  }
]
```

### Claude tool use

```json
[
  {
    "name": "get_available_slots",
    "description": "Find available booking slots for a team member. Call this before booking to get valid times.",
    "input_schema": {
      "type": "object",
      "properties": {
        "human_id": { "type": "string", "description": "ID of the team member" },
        "date_from": { "type": "string", "description": "Start date YYYY-MM-DD" },
        "date_to": { "type": "string", "description": "End date YYYY-MM-DD" },
        "duration": { "type": "integer", "description": "Meeting duration in minutes" }
      },
      "required": ["human_id", "date_from", "date_to", "duration"]
    }
  },
  {
    "name": "create_booking",
    "description": "Book a specific time slot. Always call get_available_slots first.",
    "input_schema": {
      "type": "object",
      "properties": {
        "human_id": { "type": "string" },
        "starts_at": { "type": "string", "description": "UTC time from get_available_slots" },
        "duration": { "type": "integer" },
        "attendee_name": { "type": "string" },
        "attendee_email": { "type": "string" },
        "metadata": { "type": "object" }
      },
      "required": ["human_id", "starts_at", "duration", "attendee_name"]
    }
  },
  {
    "name": "cancel_booking",
    "description": "Cancel an existing booking. Frees the time slot.",
    "input_schema": {
      "type": "object",
      "properties": {
        "booking_id": { "type": "string" }
      },
      "required": ["booking_id"]
    }
  }
]
```

## 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:

| File                                                | When to use                                              | Size   |
| --------------------------------------------------- | -------------------------------------------------------- | ------ |
| [llms.txt](https://slotflow.dev/llms.txt)           | Agent needs to know what Slotflow is (routing decisions) | \~2 KB |
| [llms-full.txt](https://slotflow.dev/llms-full.txt) | Agent 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

```typescript
import { SlotflowClient } from "slotflow";

const slotflow = new SlotflowClient({
  token: process.env.SLOTFLOW_API_KEY,
});

async function handleToolCall(name, args) {
  switch (name) {
    case "get_available_slots":
      return await slotflow.slots.getAvailableSlots({
        humanId: args.human_id,
        date_from: args.date_from,
        date_to: args.date_to,
        duration: args.duration,
      });

    case "create_booking":
      return await slotflow.bookings.createBooking({
        human_id: args.human_id,
        starts_at: args.starts_at,
        duration: args.duration,
        attendee_name: args.attendee_name,
        attendee_email: args.attendee_email,
        metadata: args.metadata,
      });

    case "cancel_booking":
      return await slotflow.bookings.cancelBooking(args.booking_id);
  }
}
```

### With raw HTTP (Python)

```python
import requests

API_KEY = os.environ["SLOTFLOW_API_KEY"]
BASE = "https://api.slotflow.dev/v1"
headers = {"Authorization": f"Bearer {API_KEY}"}

def handle_tool_call(name, args):
    if name == "get_available_slots":
        return requests.get(
            f"{BASE}/humans/{args['human_id']}/slots",
            headers=headers,
            params={
                "date_from": args["date_from"],
                "date_to": args["date_to"],
                "duration": args["duration"],
            },
        ).json()

    elif name == "create_booking":
        return requests.post(
            f"{BASE}/bookings",
            headers=headers,
            json=args,
        ).json()

    elif name == "cancel_booking":
        return requests.delete(
            f"{BASE}/bookings/{args['booking_id']}",
            headers=headers,
        ).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](https://slotflow.dev/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](/ai-sales-agent)

Full walkthrough: build an AI SDR that books demos.

#### [Error Handling](/error-handling)

All error codes and agent strategies for each one.