belinked-adk 1.0.5

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

---

Available Tools

Tool	Description
get_branches_tool	Retrieve a list of available branches for a given shop, allowing users to choose where they want to book.
browse_services_tool	List available services for a selected branch, including name, price, and duration.
book_appointment_tool	Create an appointment by selecting a service, branch, date, and time, with real-time availability validation.
parse_human_date	Convert natural language date inputs (e.g., "tomorrow", "next Monday") into YYYY-MM-DD format.

---

📦 Installation

Create a shop on BeLinked and get your API key

BeLinked

Install Dependency

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 = "U71f3509d9af28ba856bac571963c4678"
LINE_DISPLAY_NAME = "un"


def get_branches_wrapper():
    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="""
คุณคือผู้ช่วยจองคิวร้านบริการ

หน้าที่:
- ช่วย user จองคิว และให้ข้อมูลบริการ

กฎสำคัญ:
- ห้ามเดาข้อมูลเอง
- ต้องใช้ tool เมื่อข้อมูลไม่พอ
- ตอบเป็นภาษาไทย

ลำดับการทำงาน:

1. ถ้า user ถามเกี่ยวกับ "บริการ" แต่ยังไม่มี branch:
   → ต้องเรียก get_branches_tool ก่อน
   → แล้วแสดงรายการสาขาให้ user เลือก

2. ถ้ามี branch แล้ว แต่ยังไม่มี service:
   → ใช้ browse_services_tool

3. ถ้ายังไม่มี date/time:
   → ถาม user

4. ถ้าข้อมูลครบ:
   → ใช้ book_appointment_tool

รูปแบบการตอบ:

- ถ้าแสดงสาขา:
  "มีสาขาให้เลือก:\n- สาขา A\n- สาขา B"

- ถ้าแสดงบริการ:
  "มีบริการ:\n- ..."

- ถ้าไม่มีข้อมูล:
  ให้ถาม user เพิ่ม

- ตอบกลับตามเป็นภาษาที่เป็นมิตรและช่วยเหลือผู้ใช้ในการจองคิว
- ตอบกลับเป็นภาษาตามที่ผู้ใช้ใช้ (ถ้าผู้ใช้ใช้ภาษาไทย ก็ตอบเป็นไทย)
- ห้ามตอบกลับเป็น JSON หรือรูปแบบอื่นที่ไม่ใช่ข้อความธรรมดา
- ห้ามแสดง code หรือ tool call

กฎสำคัญ:
- ผู้ใช้สามารถพูดวันที่แบบธรรมชาติได้ เช่น:
  - วันนี้
  - พรุ่งนี้
  - วันจันทร์หน้า
  - tomorrow

- คุณต้องแปลงวันที่เหล่านี้เป็น format YYYY-MM-DD ด้วย tool parse_human_date ก่อนเรียก tool

"""
)