belinked-adk 1.0.2

AI-ready booking tools for BeTask services.

BeLinked ADK - AI Booking Tools

BeLinked ADK is a Python toolkit for building AI-powered booking agents.
It provides ready-to-use tools for browsing services, selecting branches, and creating appointments in a structured and testable way.

This package is designed to work with agent frameworks such as Google ADK, enabling developers to build conversational booking experiences quickly.

---

🚀 Features

• Retrieve available branches
• Browse services by branch
• Create appointments with validation
• Support chat-driven booking flows
• Compatible with AI agent frameworks (Google ADK, etc.)

---

🧠 Use Case

Developers can build AI agents that handle booking workflows end-to-end:

1. User asks for a service (e.g., haircut)
2. Agent suggests available branches
3. Agent lists services for the selected branch
4. Agent collects date and time
5. Agent completes the booking

---

Create a shop on BeLinked and get your API key

BeLinked

📦 Installation

pip install belinked-adk

Setup Environment

BETASK_SHOP_ID=5156aa9d-e7d9-4042-b19b-9a3f1411e61b

Agent Example

from google.adk.agents import Agent

from belinked_adk.tools.browse_services import browse_services_tool
from belinked_adk.tools.book_appointment import book_appointment_tool
from belinked_adk.tools.get_branches import get_branches_tool
from belinked_adk.utils.date_parser import parse_human_date
from dotenv import load_dotenv
import os

load_dotenv()

BETASK_SHOP_ID = os.getenv("BETASK_SHOP_ID")
LINE_USER_ID = "88fbd32e-48a7-40c5-a909-a7f9cc7020b9"
LINE_DISPLAY_NAME = "un"


def get_branches_wrapper():
    print("🔥 TOOL CALLED: get_branches_tool")
    return get_branches_tool(
        line_user_id=LINE_USER_ID,
        line_display_name=LINE_DISPLAY_NAME,
        shop_id=BETASK_SHOP_ID
    )


def browse_services_wrapper(branch_id):
    return browse_services_tool(
        line_user_id=LINE_USER_ID,
        line_display_name=LINE_DISPLAY_NAME,
        shop_id=BETASK_SHOP_ID,
        branch_id=branch_id
    )

def book_appointment_wrapper(
    service_keyword: str,
    date: str,
    time: str,
    remark: str = ""
):
    return book_appointment_tool(
        line_user_id=LINE_USER_ID,
        line_display_name=LINE_DISPLAY_NAME,
        shop_id=BETASK_SHOP_ID,
        service_keyword=service_keyword,
        date=date,
        time=time,
        remark=remark
    )

root_agent = Agent(
    model="gemini-2.5-flash",
    name="booking_agent",
    tools=[
        browse_services_wrapper,
        book_appointment_wrapper,
        get_branches_wrapper,
        parse_human_date
    ],
    instruction="""
You are a service booking assistant.

Your responsibilities:
- Help users book appointments
- Provide information about available services

Important rules:
- Do not assume or fabricate any information
- Always use tools when required data is missing
- Respond in the same language as the user (e.g., if the user speaks Thai, reply in Thai)

Workflow:

1. If the user asks about services but no branch is selected:
   → You MUST call get_branches_tool first
   → Then present the list of branches for the user to choose

2. If a branch is selected but no service is specified:
   → Use browse_services_tool

3. If date or time is missing:
   → Ask the user for the missing information

4. If all required information is available:
   → Use book_appointment_tool

Response format:

- When showing branches:
  "Available branches:\n- Branch A\n- Branch B"

- When showing services:
  "Available services:\n- ..."

- If information is incomplete:
  Ask the user for more details

- Always respond in a friendly and helpful tone to guide the user through the booking process
- Do NOT respond in JSON or any structured format
- Do NOT display code or tool calls in the response

Date handling rules:

- Users may provide dates in natural language, such as:
  - today
  - tomorrow
  - next Monday
  - วันนี้
  - พรุ่งนี้

- You MUST convert these into YYYY-MM-DD format by calling parse_human_date tool before calling any booking-related tool
"""
)