Bài 5 — Giao việc tự động: đẩy action item lên Trello/Jira/Notion qua API

Bạn đã có JSON action item sạch. Giờ biến chúng thành task thật trong công cụ nhóm đang dùng. Bài này về tích hợp API, ánh xạ dữ liệu, và — quan trọng nhất — chống tạo trùng.

Nguyên tắc: agent thích nghi với công cụ, không ngược lại

Đừng bắt nhóm đổi từ Trello sang Jira vì agent. Agent phải nói được "ngôn ngữ" của công cụ hiện có. Mỗi công cụ có API tạo card/issue/page.

Ánh xạ trường (mapping)

Bước ánh xạ tên người → ID hệ thống là mấu chốt. Giữ một bảng tra:

MEMBER_MAP = {
    "Minh": "5f3a...trello_member_id",
    "Lan":  "6b2c...trello_member_id",
    "Khang":"7d1e...trello_member_id",
}

Tạo card Trello (ví dụ)

import requests

def create_trello_card(item):
    member_id = MEMBER_MAP.get(item["assignee"])
    resp = requests.post("https://api.trello.com/1/cards", params={
        "key": TRELLO_KEY, "token": TRELLO_TOKEN,
        "idList": TODO_LIST_ID,
        "name": item["task"],
        "desc": f"Trích từ họp: \"{item['source_quote']}\"",
        "due": item["due_date"],
        "idMembers": member_id if member_id else "",
    })
    resp.raise_for_status()
    return resp.json()["id"]   # lưu lại để follow-up ở bài 7

Hãy lưu ID card trả về vào bảng action_items của bạn — bài 7 cần nó để kiểm tra trạng thái.

Chống tạo trùng (idempotency)

Agent chạy lại (retry, upload nhầm 2 lần) không được tạo 2 card giống nhau. Hai cách:

• Hash nội dung: sinh khóa từ meeting_id + task, kiểm tra đã tồn tại chưa trước khi tạo.
• Cờ trạng thái: mỗi action item có pushed = false; chỉ đẩy khi false, đẩy xong set true.

key = hashlib.sha1(f"{meeting_id}|{item['task']}".encode()).hexdigest()
if not already_pushed(key):
    card_id = create_trello_card(item)
    mark_pushed(key, card_id)

Xử lý item "CHƯA_RÕ"

Item thiếu assignee/hạn KHÔNG đẩy tự động. Gom vào một tin nhắn gửi người chủ trì: "3 việc chưa rõ người phụ trách, bạn gán giúp?" kèm nút xác nhận. Có phản hồi rồi mới tạo card.

Xử lý lỗi từng item, không dừng cả batch

Giả sử bạn có 5 action item cần đẩy. Nếu item thứ 2 lỗi (mạng chập chờn, thành viên không tồn tại) mà bạn để exception làm dừng vòng lặp, thì 3 item còn lại không bao giờ được tạo. Hãy bọc mỗi lần tạo trong try/except riêng, ghi lại item nào lỗi để retry, và tiếp tục các item còn lại:

results = {"created": [], "failed": []}
for item in items:
    try:
        card_id = create_trello_card(item)
        results["created"].append((item, card_id))
    except Exception as e:
        results["failed"].append((item, str(e)))
# Cuối cùng: báo cáo, retry riêng phần failed

Bảo mật token: dùng biến môi trường

Token API là chìa khóa vào board của cả nhóm. Không bao giờ hardcode trong code hay commit lên git — dùng biến môi trường (os.environ) hoặc secret manager. Một token Trello rò rỉ đủ để người ngoài đọc và sửa toàn bộ công việc của team.

Các bước triển khai

• Lấy API key/token của công cụ; xác định list/board/project đích.
• Xây MEMBER_MAP tên → ID.
• Viết hàm tạo task cho từng công cụ, có xử lý lỗi (raise_for_status).
• Thêm lớp chống trùng (hash hoặc cờ pushed).
• Với item hợp lệ: tạo task, lưu lại task_id.
• Với item CHƯA_RÕ: gửi đi hỏi, chờ xác nhận.
• Trả về báo cáo: đã tạo N task, M item chờ xác nhận.

Checklist tích hợp

• [ ] Có lưu task_id trả về để follow-up không?
• [ ] Đã chống tạo trùng khi chạy lại chưa?
• [ ] Lỗi API (mạng, quyền) có được bắt và báo không?
• [ ] Item thiếu dữ liệu có bị chặn khỏi tạo tự động không?
• [ ] Token API lưu an toàn (env var), không hardcode?

Sai lầm thường gặp

• Không lưu task_id: bài 7 không có cách nào biết task đã xong hay chưa.
• Không chống trùng: mỗi lần retry đẻ thêm một loạt card, ngập board.
• Hardcode token trong code: rò rỉ khi push lên git. Dùng biến môi trường.
• Bỏ qua xử lý lỗi: một card lỗi làm dừng cả batch. Bắt lỗi từng item, tiếp tục các item còn lại.
• Đẩy cả item CHƯA_RÕ: tạo task "mồ côi" không ai nhận, sớm bị bỏ quên.

Bài 6: dựng orchestrator ghép 5 bước thành một agent chạy tự động.