Week 4 · CRM — idempotent contact upserts

🎯 Learning objectives

Trim the tool surface

Expose exactly 3 functions (find / upsert / log_note) — not 200. Avoids the "token tax."

เปิด 3 ฟังก์ชัน (find / upsert / log_note) เท่านั้น ไม่ใช่ 200 ตัว เลี่ยง token tax

只暴露 3 个函数（find / upsert / log_note），而不是 200 个，避免"token 税"。

Idempotent upsert

Phone number = key. Retries don't make duplicate contacts.

เบอร์โทร = key รีทรายไม่สร้าง contact ซ้ำ

用电话号当 key，重试不再生成重复联系人。

State machine in Python

Validate pipeline transitions in code. Prompt can't override.

ตรวจสอบการเปลี่ยน stage ใน Python prompt ห้ามเปลี่ยน

在代码里校验阶段跳转，提示词无权覆盖。

🚦 Interactive: the pipeline state machine

Click any stage to see which transitions are allowed. The agent can suggest anything; only valid transitions actually run.

คลิก stage ใดก็ได้ ดูว่าเปลี่ยนไปไหนได้บ้าง agent เสนออะไรก็ได้ — แต่เฉพาะที่ valid เท่านั้นที่ทำงานจริง

点击任一阶段，看哪些跳转被允许。代理可以提议任何事，但只有合法跳转会真正执行。

Inquiry

→

Qualified

→

Closed Won

⤓

Closed Lost

Click a stage above to see allowed transitions.

⚠️ Premature "Closed Won"

An enthusiastic Hermes will read "customer loves the tour" and try to skip from Inquiry straight to Closed Won. The state machine returns REJECTED — no API call to HubSpot is made.

Hermes อาจอ่าน "ลูกค้าชอบมาก" แล้วข้าม Inquiry ไป Closed Won ทันที state machine จะคืน REJECTED ไม่ส่ง API ให้ HubSpot

兴奋的 Hermes 看到"客户很喜欢"，会想从 Inquiry 直接跳到 Closed Won。状态机会返回 REJECTED，HubSpot 这一边一个请求都不会发。

📚 Key concepts

🇬🇧 English

Token tax — every tool description Hermes sees eats context. Wrap only what you need.

Idempotency key — a unique business identifier (phone). upsert finds by it, else creates.

Pipeline as state machine — ALLOWED dict in Python is the source of truth; the LLM only proposes.

🇹🇭 ไทย

Token tax — คำอธิบายเครื่องมือทุกตัวกินที่ context ห่อเฉพาะที่ต้องใช้

Idempotency key — ตัวระบุที่ไม่ซ้ำในธุรกิจ (เบอร์โทร) upsert หาก่อน ไม่เจอค่อยสร้าง

Pipeline as state machine — dict ALLOWED ใน Python คือ source of truth LLM แค่เสนอ

🇨🇳 中文

Token 税 — Hermes 看到的每个工具描述都吃上下文。只包装你真正需要的。

幂等键 — 业务上的唯一标识（电话），upsert 先查、找不到再建。

管道即状态机 — Python 里的 ALLOWED 字典是事实源；LLM 只能提议。

🧪 Hands-on lab

Install + load the token

pip install hubspot-api-client python-dotenv
# put HUBSPOT_TOKEN=pat-xxxx into a .env next to agent_pro.py

Three trimmed FunctionTools

import os
from hubspot import HubSpot
_hs = HubSpot(access_token=os.environ["HUBSPOT_TOKEN"])

def find_contact(phone: str) -> str:
    """Find a HubSpot contact by phone. Returns id or 'NOT_FOUND'."""
    r = _hs.crm.contacts.search_api.do_search(public_object_search_request={
        "filterGroups": [{"filters": [
            {"propertyName": "phone", "operator": "EQ", "value": phone}
        ]}],
        "properties": ["phone", "firstname", "lifecyclestage"],
    })
    return r.results[0].id if r.total else "NOT_FOUND"

def upsert_hubspot_contact(phone: str, name: str) -> str:
    """Idempotent: find by phone, else create. Returns contact id."""
    existing = find_contact(phone)
    if existing != "NOT_FOUND": return f"existing {existing}"
    new = _hs.crm.contacts.basic_api.create(simple_public_object_input_for_create={
        "properties": {"phone": phone, "firstname": name}
    })
    return f"created {new.id}"

def log_note(contact_id: str, body: str) -> str:
    """Attach a note (use for sales-call recaps)."""
    n = _hs.crm.objects.notes.basic_api.create(simple_public_object_input_for_create={
        "properties": {"hs_note_body": body, "hs_timestamp": now_ms()},
        "associations": [{"to": {"id": contact_id},
                          "types": [{"associationCategory": "HUBSPOT_DEFINED", "associationTypeId": 202}]}],
    })
    return f"note {n.id} on contact {contact_id}"

for fn in (find_contact, upsert_hubspot_contact, log_note):
    TOOLS.append(FunctionTool.from_defaults(fn))

The state machine guard

ALLOWED = {
    "Inquiry":     {"Qualified"},
    "Qualified":   {"Closed Won", "Closed Lost"},
    "Closed Won":  set(),
    "Closed Lost": set(),
}

def move_stage(contact_id: str, new_stage: str) -> str:
    """Move contact to new pipeline stage IFF the transition is allowed."""
    cur = _hs.crm.contacts.basic_api.get_by_id(contact_id, properties=["lifecyclestage"]).properties["lifecyclestage"]
    if new_stage not in ALLOWED.get(cur, set()):
        return f"REJECTED: {cur} -> {new_stage} is not allowed"
    _hs.crm.contacts.basic_api.update(contact_id, {"properties": {"lifecyclestage": new_stage}})
    return f"moved {contact_id}: {cur} -> {new_stage}"
TOOLS.append(FunctionTool.from_defaults(move_stage))

Feed the agent a WhatsApp transcript

you > Here's a WhatsApp transcript: [paste]. Use idempotency on the phone number.
        Log a 3-bullet recap as a note. Move them from Inquiry to Qualified
        (they asked for a payment link).

💡 Test the guard

Now try: you > Move that contact to Closed Won. The state machine returns REJECTED — Hermes adapts and explains why.

ลอง: you > Move that contact to Closed Won. state machine จะคืน REJECTED Hermes ปรับและอธิบายเอง

试试：you > Move that contact to Closed Won. 状态机返回 REJECTED，Hermes 会自动调整并解释原因。

⚠️ Top gotchas

1. Token-tax crash

The full HubSpot client has hundreds of methods. Wrapping only what you need keeps Hermes' context under control.

HubSpot client เต็มมีหลายร้อยเมธอด ห่อเฉพาะที่ใช้ก็พอ

HubSpot 完整客户端有几百个方法。只包装真正需要的，才能控制住上下文。

2. Duplicate contacts on retry

A network blip during create makes clones if you skip find_contact() first. Always upsert.

เน็ตสะดุดตอน create จะมี clone ถ้าข้าม find_contact() ใช้ upsert เสมอ

create 时网络抖动会产生克隆，除非先 find_contact()。永远走 upsert。

3. Premature "Closed Won"

Without the state machine guard, an excited Hermes skips ahead. Python validates; the prompt cannot override.

ไม่มี state machine = Hermes ตื่นเต้นกระโดดข้าม Python คุมไว้ prompt บังคับไม่ได้

没有状态机，兴奋的 Hermes 就会越级。由 Python 校验，提示词无权覆盖。

📝 Assessment & homework

✅ Assessment

A new HubSpot contact with the recap note and pipeline stage Qualified. Explain why CRM tools are trimmed instead of exposed wholesale.

มี contact ใน HubSpot พร้อม note และ stage Qualified อธิบายว่าทำไมต้อง trim เครื่องมือ CRM

HubSpot 里有新联系人、纪要笔记、阶段为 Qualified。说明为什么 CRM 工具要精简而不是全开。

🏠 Homework

Export one real (non-sensitive) WhatsApp/email thread. Run the full pipeline. Bring the trickiest one to Week 5 — we'll add an adversarial reviewer.

เอา WhatsApp/อีเมลจริง 1 thread มารัน pipeline เอาตัวที่ยากที่สุดไป Week 5 — เพิ่ม adversarial reviewer

导出一段真实（非敏感）WhatsApp/邮件，跑完整流程。把最棘手的一条带到 Week 5，加上对抗审查者。