Router CrewAI tương thích OpenAI: Một khóa cho các quy trình đa tác tử

Việc thiết lập một router CrewAI tương thích OpenAI rất hữu ích khi bạn muốn nhiều tác tử CrewAI sử dụng một ranh giới cổng vào duy nhất thay vì phân tán các khóa nhà cung cấp, URL cơ sở và bí danh mô hình trên mọi vai trò trong quy trình làm việc.

Tài liệu LLM hiện tại của CrewAI chỉ ra hai hướng thiết lập quan trọng cho các điểm cuối tương thích OpenAI: các biến môi trường như OPENAI_API_BASE, và các thuộc tính LLM(...) tường minh như model, base_url, và api_key. Flatkey phù hợp ở ranh giới đó. Trang web công khai của nó hướng các client tương thích OpenAI đến https://router.flatkey.ai/v1, với việc xem xét mức sử dụng, chi phí, định tuyến và lỗi trong bảng điều khiển sản phẩm.

Hướng dẫn này trình bày một mẫu router CrewAI tương thích OpenAI thực tế cho các quy trình làm việc đa tác tử. Mã này là một mẫu: hãy xác thực các bí danh mô hình chính xác, hành vi của công cụ và nhật ký bằng khóa Flatkey của riêng bạn trước khi định tuyến các tác tử sản xuất.

Câu trả lời nhanh cho router CrewAI tương thích OpenAI

Sử dụng một gốc API cổng vào duy nhất và các tên định tuyến tường minh. Đừng chôn vùi việc định tuyến trong văn bản gợi ý.

Đó là mẫu router CrewAI tương thích OpenAI cốt lõi: giữ cho CrewAI chịu trách nhiệm điều phối, giữ cho Flatkey chịu trách nhiệm về ranh giới cổng vào tương thích OpenAI, và làm cho các kiểm tra vận hành trở nên rõ ràng.

Tại sao các quy trình làm việc đa tác tử cần một ranh giới cổng vào

Các quy trình làm việc của CrewAI thường bắt đầu với một hình dạng đơn giản: một tác tử quản lý, một vài tác tử chuyên gia và một nhiệm vụ cuối cùng. Điều đó hoạt động tốt cho đến khi quy trình làm việc chuyển từ bản demo sang một dịch vụ mà các nhóm khác phụ thuộc vào.

Các hệ thống đa tác tử trong môi trường sản xuất thường cần nhiều hơn là một phản hồi hoạt động được:

Để biết các kiểm soát thiết kế liền kề, hãy sử dụng hướng dẫn của Flatkey về các kiểm soát cổng vào cho tác tử AI. Một router CrewAI tương thích OpenAI nên làm cho các kiểm soát đó trở nên cụ thể cho từng vai trò của tác tử.

Bước 1: Tạo các giá trị định tuyến Flatkey

Tạo một khóa Flatkey cho khối lượng công việc này và giữ các giá trị định tuyến bên ngoài kiểm soát nguồn.

FLATKEY_API_KEY=sk-fk-your-key
FLATKEY_BASE_URL=https://router.flatkey.ai/v1
FLATKEY_DEFAULT_MODEL=your-default-flatkey-model-alias
FLATKEY_PLANNER_MODEL=your-planner-model-alias
FLATKEY_TOOL_MODEL=your-tool-capable-model-alias
FLATKEY_VERIFIER_MODEL=your-verifier-model-alias

Giữ gốc API tách biệt với đường dẫn điểm cuối. Đối tượng LLM của CrewAI nên nhận URL cơ sở. Các bài kiểm tra curl trực tiếp sẽ thêm /chat/completions.

curl "$FLATKEY_BASE_URL/chat/completions" \
  -H "Authorization: Bearer $FLATKEY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "'"$FLATKEY_DEFAULT_MODEL"'",
    "messages": [
      { "role": "user", "content": "Reply with exactly: flatkey route ok" }
    ]
  }'

Nếu yêu cầu trực tiếp này không thành công, trước tiên hãy sửa khóa Flatkey, bí danh mô hình, họ điểm cuối hoặc định tuyến tài khoản. Một router CrewAI tương thích OpenAI không thể bù đắp cho một bí danh mô hình mà tài khoản cổng vào không thể gọi.

Bước 2: Cấu hình các đối tượng LLM của CrewAI một cách tường minh

CrewAI hỗ trợ thiết lập URL API cơ sở cho một LLM thông qua base_url, và tài liệu của nó cho thấy việc thiết lập LLM tương thích OpenAI thông qua các biến môi trường hoặc các thuộc tính lớp LLM. Đối với công việc sản xuất, các đối tượng LLM tường minh dễ xem xét hơn vì mỗi vai trò của tác tử đều trỏ đến một định tuyến đã biết.

import os

from crewai import Agent, Crew, LLM, Process, Task


BASE_URL = os.environ.get("FLATKEY_BASE_URL", "https://router.flatkey.ai/v1")
API_KEY = os.environ["FLATKEY_API_KEY"]


def flatkey_llm(model_env: str, temperature: float = 0.2) -> LLM:
    return LLM(
        model=os.environ[model_env],
        base_url=BASE_URL,
        api_key=API_KEY,
        temperature=temperature,
    )


planner_llm = flatkey_llm("FLATKEY_PLANNER_MODEL", temperature=0.1)
tool_llm = flatkey_llm("FLATKEY_TOOL_MODEL", temperature=0.0)
verifier_llm = flatkey_llm("FLATKEY_VERIFIER_MODEL", temperature=0.0)

Đây là quyết định thiết lập quan trọng nhất trong quá trình di chuyển **router CrewAI tương thích OpenAI**. Bí danh mô hình có thể thay đổi theo môi trường, nhưng mã CrewAI giữ một gốc API tương thích OpenAI và một chủ sở hữu khóa cổng.

Bước 3: Phân công các tuyến đường theo trách nhiệm của tác tử

Gán cho mỗi tác tử CrewAI một tuyến đường LLM phù hợp với hồ sơ rủi ro của nó. Bắt đầu với một bộ tuyến đường nhỏ. Bạn luôn có thể chia nhỏ thêm các vai trò sau khi nhật ký chứng minh chính sách đầu tiên hoạt động.

planner = Agent(
    role="Người lập kế hoạch quy trình làm việc",
    goal="Chia yêu cầu thành một kế hoạch thực thi ngắn gọn.",
    backstory="Bạn giữ cho nhóm làm việc trong phạm vi và tránh các lệnh gọi mô hình không cần thiết.",
    llm=planner_llm,
)

researcher = Agent(
    role="Nhà nghiên cứu",
    goal="Chỉ thu thập những dữ kiện cần thiết cho nhiệm vụ.",
    backstory="Bạn ưu tiên các ghi chú có nguồn gốc rõ ràng hơn là suy đoán rộng.",
    llm=planner_llm,
)

tool_user = Agent(
    role="Người vận hành công cụ",
    goal="Chỉ sử dụng các công cụ đã được phê duyệt khi nhiệm vụ yêu cầu.",
    backstory="Bạn xác minh đầu vào của công cụ trước khi gọi các hệ thống bên ngoài.",
    llm=tool_llm,
)

verifier = Agent(
    role="Người xác minh",
    goal="Kiểm tra câu trả lời cuối cùng so với các yêu cầu và bằng chứng.",
    backstory="Bạn tìm kiếm bằng chứng còn thiếu, lỗi công cụ và rủi ro hoàn tác.",
    llm=verifier_llm,
)

Đối với lần triển khai **router CrewAI tương thích OpenAI** đầu tiên, hãy tránh gán một mô hình duy nhất cho mọi tác tử. Hai hoặc ba loại tuyến đường thường là đủ: lập kế hoạch, thực thi có khả năng sử dụng công cụ và xác minh.

Bước 4: Xây dựng một nhóm nhỏ và giữ lại các trường bằng chứng

Nhóm có thể giữ nguyên như bình thường. Bằng chứng định tuyến thì không. Thêm các trường đơn giản vào mô tả nhiệm vụ, đầu ra hoặc nhật ký ứng dụng xung quanh của bạn để yêu cầu có thể được khớp với nhật ký Flatkey.

analysis_task = Task(
    description=(
        "Xem xét phiếu hỗ trợ và đưa ra một kế hoạch giải quyết ngắn gọn. "
        "Không gọi các công cụ trừ khi cần tra cứu tài khoản. "
        "Các trường bằng chứng cần giữ bên ngoài lời nhắc này: workflow=crew_support_triage, "
        "route_policy=crewai-router-v1."
    ),
    expected_output="Một kế hoạch ngắn gọn với các rủi ro, nhu cầu công cụ và hành động tiếp theo.",
    agent=planner,
)

verification_task = Task(
    description=(
        "Kiểm tra xem kế hoạch có trích dẫn các dữ kiện của phiếu hỗ trợ, tránh các tuyên bố không có cơ sở, "
        "và nêu tên bất kỳ lệnh gọi công cụ nào vẫn cần phê duyệt."
    ),
    expected_output="Ghi chú đạt/không đạt với các bản sửa lỗi cần thiết.",
    agent=verifier,
    context=[analysis_task],
)

crew = Crew(
    agents=[planner, researcher, tool_user, verifier],
    tasks=[analysis_task, verification_task],
    process=Process.sequential,
)

result = crew.kickoff(
    inputs={
        "ticket_id": "TICKET-123",
        "request_id": "support-triage-2026-07-08-001",
    }
)
print(result)

request_id trong mẫu này không phải là một tính năng định tuyến của CrewAI. Nó là một thói quen để quan sát. Ứng dụng của bạn nên ghi lại ID yêu cầu, chính sách định tuyến, bí danh mô hình, dấu thời gian và nhãn khóa để đường dẫn của **router CrewAI tương thích OpenAI** có thể được kiểm tra trong Flatkey.

Bước 5: Xác minh các lệnh gọi công cụ trước khi triển khai rộng rãi

Việc sử dụng công cụ là nơi định tuyến tương thích OpenAI trở nên rủi ro. Một tuyến đường trò chuyện đơn giản có thể hoạt động trong khi một tuyến đường sử dụng nhiều công cụ lại không xác thực được lược đồ, truyền các đối số công cụ theo cách khác hoặc tạo ra các đối số mà trình thực thi của bạn từ chối.

Sử dụng một bài kiểm tra công cụ có phạm vi hẹp trước khi bạn tin tưởng vào một tuyến đường công cụ CrewAI. Để hiểu rõ hơn về hành vi của nhà cung cấp, hãy kết hợp hướng dẫn này với bài viết của Flatkey về lệnh gọi công cụ tương thích OpenAI.

Đừng coi đây là tùy chọn. Một **router CrewAI tương thích OpenAI** chỉ sẵn sàng cho môi trường sản xuất khi tuyến đường công cụ được kiểm tra như một hợp đồng riêng biệt.

Bước 6: Thêm các quy tắc về ngân sách, thử lại và dự phòng bên ngoài lời nhắc

Đừng yêu cầu các tác tử ghi nhớ mọi quy tắc hoạt động bằng ngôn ngữ tự nhiên. Hãy giữ các quy tắc về ngân sách và dự phòng trong mã hoặc cấu hình mà người đánh giá có thể kiểm tra.

Khi phương án dự phòng được phê duyệt, hãy giữ bí danh dự phòng một cách rõ ràng. Câu hỏi hữu ích không phải là "nhóm đã hoàn thành chưa?" mà là "tuyến đường nào đã hoàn thành, tại sao nó lại chuyển đổi, và chi phí là bao nhiêu?" Đó là giá trị hoạt động của một router CrewAI tương thích OpenAI.

Bước 7: Lưu một gói xác minh

Trước khi đặt Flatkey làm cổng mặc định cho một quy trình CrewAI, hãy lưu một gói xác minh nhỏ gọn.

1. Yêu cầu curl trực tiếp đến https://router.flatkey.ai/v1/chat/completions thành công với bí danh mô hình đã chọn.
2. Mỗi đối tượng LLM của CrewAI chạy một lời nhắc nhỏ bên ngoài nhóm đầy đủ.
3. Nhóm đầy đủ chạy một quy trình đơn giản và một quy trình sử dụng nhiều công cụ.
4. Một đường dẫn thất bại bắt buộc sẽ dừng lại một cách sạch sẽ thay vì thử lại mãi mãi.
5. Nhật ký Flatkey hiển thị khóa, bí danh mô hình, dấu thời gian và chủ sở hữu yêu cầu như mong đợi.
6. Các trường token hoặc sử dụng đủ rõ ràng để chủ sở hữu ngân sách xem xét.
7. Việc khôi phục chỉ là một thay đổi môi trường hoặc cấu hình, không phải là tái cấu trúc CrewAI.

Sử dụng hướng dẫn bảng điều khiển sử dụng token của Flatkey để quyết định các trường mà đội vận hành của bạn nên kiểm tra sau lần kiểm tra sơ bộ đầu tiên. Để xem xét giá cả và tài khoản, hãy bắt đầu từ trang giá của Flatkey trực tiếp, sau đó xác minh tuyến đường thực tế trong tài khoản của bạn.

Xử lý sự cố router CrewAI tương thích OpenAI

Nếu yêu cầu đầu tiên thất bại, hãy giữ phạm vi gỡ lỗi nhỏ: một khóa, một URL cơ sở, một bí danh mô hình, một LLM của CrewAI, một yêu cầu trực tiếp và một lần tra cứu nhật ký Flatkey.

Câu hỏi thường gặp

Router CrewAI tương thích OpenAI có giống như phương án dự phòng mô hình không?

Không. Một router CrewAI tương thích OpenAI là cổng và ranh giới cấu hình mà CrewAI sử dụng để tiếp cận các tuyến đường mô hình. Dự phòng là một chính sách có thể chạy khi một tuyến đường đã chọn thất bại. Hãy kiểm tra định tuyến và dự phòng một cách riêng biệt.

Mỗi tác tử CrewAI có nên có một mô hình khác nhau không?

Không. Hãy bắt đầu với một tuyến đường mặc định và một tuyến đường đặc biệt cho công việc sử dụng nhiều công cụ hoặc công việc xác minh nếu cần. Quá nhiều bí danh sẽ làm cho việc xem nhật ký, đánh giá chi phí và khôi phục trở nên khó khăn hơn.

CrewAI có thể sử dụng biến môi trường thay vì các đối tượng LLM tường minh không?

Có. Tài liệu của CrewAI cho thấy việc thiết lập tương thích OpenAI thông qua các biến môi trường như OPENAI_API_BASE. Các đối tượng LLM tường minh thường dễ dàng hơn cho việc xem xét trong môi trường sản xuất vì mỗi vai trò tác tử hiển thị model, base_url, và api_key ở cùng một nơi.

Tôi có thể sử dụng cùng một khóa Flatkey cho mọi quy trình CrewAI không?

Bạn có thể, nhưng các khóa dành riêng cho khối lượng công việc sẽ dễ kiểm tra hơn. Sử dụng các khóa hoặc nhãn riêng biệt khi các nhóm, môi trường, ngân sách hoặc mức độ rủi ro khác nhau cần được xem xét riêng.

Danh sách kiểm tra cuối cùng

Thiết lập router CrewAI tương thích OpenAI của bạn đã sẵn sàng để vượt ra ngoài một mẫu khi:

1. Các đối tượng LLM của CrewAI sử dụng gốc API của Flatkey làm base_url.
2. Các bí danh mô hình nằm trong môi trường hoặc cấu hình, không nằm rải rác trong các lời nhắc.
3. Mỗi vai trò tác tử có một quyết định tuyến đường có chủ đích.
4. Các tuyến đường sử dụng nhiều công cụ vượt qua các bài kiểm tra về lược đồ, đối số, giới hạn và thất bại.
5. Các giới hạn về ngân sách, thử lại và dự phòng chạy bên ngoài văn bản của tác tử.
6. Nhật ký sử dụng hoặc yêu cầu của Flatkey xác nhận khóa và bí danh mô hình như mong đợi.
7. Việc khôi phục chỉ là một thay đổi cấu hình.

Khi bạn đã sẵn sàng định tuyến lưu lượng truy cập CrewAI qua một gateway, hãy lấy một khóa Flatkey, thử nghiệm một crew có rủi ro thấp và chỉ mở rộng sau khi log chứng minh chính sách hoạt động hiệu quả.