Bài 2 — Cài đặt & cấu hình: chạy crew CrewAI đầu tiên

Chuẩn bị môi trường

Multi-agent framework nào cũng cần: Python, một virtualenv sạch, và một API key của LLM (OpenAI, Azure, hoặc endpoint tương thích như DeepSeek). Chúng ta bắt đầu với CrewAI vì cú pháp rõ ràng, dễ nhìn thấy role/goal/task.

Bước cài đặt

• Tạo môi trường ảo để tránh xung đột thư viện:

python -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate

• Cài CrewAI:

pip install crewai crewai-tools

• Đặt API key vào biến môi trường (KHÔNG hardcode trong code):

export OPENAI_API_KEY="sk-..."
export OPENAI_MODEL_NAME="gpt-4o-mini"

> Mẹo: dùng file .env + thư viện python-dotenv để nạp key tự động, và thêm .env vào .gitignore.

Cấu trúc một crew tối thiểu

Một crew CrewAI gồm 3 khối: Agent (ai làm), Task (làm gì), Crew (ghép lại và chạy). Dưới đây là crew 2 agent viết tóm tắt về một chủ đề.

from crewai import Agent, Task, Crew, Process

researcher = Agent(
    role="Chuyên viên nghiên cứu",
    goal="Thu thập 5 ý chính đáng tin về chủ đề {topic}",
    backstory="Bạn tỉ mỉ, chỉ giữ lại thông tin có căn cứ.",
    verbose=True,
)

writer = Agent(
    role="Biên tập viên",
    goal="Viết đoạn tóm tắt 150 từ dễ hiểu từ dữ liệu nghiên cứu",
    backstory="Bạn viết ngắn gọn, mạch lạc cho người mới.",
    verbose=True,
)

Tiếp theo là task cho từng agent:

research_task = Task(
    description="Nghiên cứu chủ đề: {topic}. Liệt kê 5 ý chính.",
    expected_output="Danh sách 5 gạch đầu dòng, mỗi ý 1-2 câu.",
    agent=researcher,
)

write_task = Task(
    description="Từ kết quả nghiên cứu, viết đoạn tóm tắt 150 từ.",
    expected_output="Một đoạn văn khoảng 150 từ.",
    agent=writer,
)

Ghép lại thành crew chạy tuần tự:

crew = Crew(
    agents=[researcher, writer],
    tasks=[research_task, write_task],
    process=Process.sequential,
    verbose=True,
)

result = crew.kickoff(inputs={"topic": "Điện toán đám mây cho SME"})
print(result)

Các bước chạy thử

• Lưu code vào crew_demo.py.
• Kích hoạt virtualenv và đảm bảo key đã export.
• Chạy python crew_demo.py.
• Quan sát log verbose=True: bạn sẽ thấy researcher chạy trước, output của nó tự động được truyền làm ngữ cảnh cho writer.
• Kiểm tra kết quả cuối in ra có đúng ~150 từ không.

Vì sao expected_output quan trọng

expected_output là hợp đồng giữa các agent. Task sau tự động nhận output task trước làm context (khi process=sequential). Nếu bạn mô tả output mơ hồ, writer sẽ nhận dữ liệu khó dùng. Hãy mô tả output càng cụ thể càng tốt: định dạng, độ dài, cấu trúc.

Hãy hình dung sự khác biệt: nếu researcher trả về một khối văn xuôi dài lộn xộn, writer phải tự đoán đâu là ý chính. Nhưng nếu bạn yêu cầu expected_output="5 gạch đầu dòng, mỗi ý 1-2 câu, kèm nguồn", writer nhận đúng cấu trúc và dễ dàng chuyển thành đoạn văn mạch lạc. Output có cấu trúc chính là thứ khiến chuỗi agent không bị suy giảm chất lượng qua từng bước.

Nạp cấu hình bằng file .env

Trong dự án thật, bạn không muốn export key mỗi lần mở terminal. Dùng python-dotenv để nạp tự động:

from dotenv import load_dotenv
load_dotenv()   # đọc file .env ở thư mục hiện tại

File .env (nhớ thêm vào .gitignore):

OPENAI_API_KEY=sk-...
OPENAI_MODEL_NAME=gpt-4o-mini

Cách này giúp cấu hình gọn, tách biệt bí mật khỏi mã nguồn, và dễ chuyển giữa các môi trường (dev, staging, production) chỉ bằng cách đổi file .env.

Điều chỉnh hành vi agent qua tham số

Ngoài role/goal/backstory, một vài tham số hữu ích khi cấu hình Agent:

• allow_delegation=False: chặn agent tự ủy thác việc cho agent khác (mặc định nên tắt để luồng dễ đoán khi mới học).
• max_iter: giới hạn số vòng suy luận nội bộ của một agent, tránh nó lặp vô ích.
• verbose=True: in log chi tiết — bật khi debug, tắt khi chạy thật.

researcher = Agent(
    role="Chuyên viên nghiên cứu",
    goal="...",
    backstory="...",
    allow_delegation=False,
    max_iter=5,
    verbose=True,
)

Những tham số nhỏ này quyết định lớn tới độ ổn định và chi phí khi crew chạy thật.

Checklist trước khi chạy crew

• [ ] Virtualenv đã kích hoạt.
• [ ] API key đã ở biến môi trường, không hardcode.
• [ ] Mỗi Agent có role + goal + backstory rõ ràng.
• [ ] Mỗi Task có description và expected_output cụ thể.
• [ ] agents và tasks khớp nhau, đúng thứ tự.
• [ ] verbose=True khi debug để thấy luồng chạy.

Sai lầm thường gặp

• Quên set model/API key → lỗi xác thực khó hiểu. Luôn kiểm tra biến môi trường trước.
• expected_output để trống hoặc quá chung → agent tự bịa định dạng, task sau nhận rác.
• Cài đè lên môi trường hệ thống thay vì virtualenv → xung đột phiên bản với dự án khác.
• Bật verbose=False khi mới học → không thấy được luồng phối hợp, rất khó tìm lỗi.
• Chạy crew 5 agent ngay lần đầu → khó cô lập lỗi. Luôn bắt đầu với 2 agent chạy được rồi mở rộng.

Bài 3 sẽ đào sâu cách viết role/goal/task thật sắc để agent làm đúng ý bạn.