CrewAI OpenAI-Compatible Router: Satu Kunci untuk Multi-Agent Workflows

CrewAI OpenAI compatible router berguna ketika Anda ingin beberapa agen CrewAI menggunakan satu batas gateway alih-alih menyebarkan kunci penyedia, base URL, dan alias model ke setiap peran dalam workflow.

Dokumentasi LLM CrewAI saat ini menunjukkan dua jalur setup penting untuk endpoint yang kompatibel dengan OpenAI: variabel lingkungan seperti OPENAI_API_BASE, dan atribut LLM(...) eksplisit seperti model, base_url, dan api_key. Flatkey cocok pada batas tersebut. Situs publiknya mengarahkan klien yang kompatibel dengan OpenAI ke https://router.flatkey.ai/v1, dengan penggunaan, biaya, routing, dan tinjauan error di dashboard produk.

Panduan ini menunjukkan pola praktis CrewAI OpenAI compatible router untuk workflow multi-agent. Kode ini adalah template: validasi alias model yang tepat, perilaku tool, dan log dengan kunci Flatkey Anda sendiri sebelum merutekan agen produksi.

Jawaban cepat untuk CrewAI OpenAI compatible router

Gunakan satu root API gateway dan nama route yang eksplisit. Jangan menyembunyikan routing di teks prompt.

Itulah inti pola CrewAI OpenAI compatible router: biarkan CrewAI bertanggung jawab atas orkestrasi, biarkan Flatkey bertanggung jawab atas batas gateway yang kompatibel dengan OpenAI, dan buat pemeriksaan operasional terlihat jelas.

Mengapa workflow multi-agent membutuhkan batas gateway

Workflow CrewAI sering dimulai dengan bentuk sederhana: satu agen manajer, beberapa agen spesialis, dan sebuah task akhir. Itu bekerja sampai workflow berpindah dari demo menjadi layanan yang diandalkan tim lain.

Sistem multi-agent produksi biasanya membutuhkan lebih dari sekadar respons yang berfungsi:

Untuk kontrol desain yang berdekatan, gunakan panduan Flatkey tentang kontrol gateway agen AI. CrewAI OpenAI compatible router harus membuat kontrol tersebut konkret untuk setiap peran agen.

Langkah 1: Buat nilai route Flatkey

Buat satu kunci Flatkey untuk workload ini dan simpan nilai route di luar source control.

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

Simpan root API terpisah dari path endpoint. Objek LLM CrewAI harus menerima base URL. Pengujian curl langsung menambahkan /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" }
    ]
  }'

Jika request langsung ini gagal, perbaiki dulu kunci Flatkey, alias model, family endpoint, atau route akun. CrewAI OpenAI compatible router tidak dapat mengompensasi alias model yang tidak dapat dipanggil oleh akun gateway.

Langkah 2: Konfigurasikan objek LLM CrewAI secara eksplisit

CrewAI mendukung pengaturan base API URL untuk sebuah LLM melalui base_url, dan dokumentasinya menunjukkan setup LLM yang kompatibel dengan OpenAI melalui variabel lingkungan atau atribut class LLM. Untuk pekerjaan produksi, objek LLM yang eksplisit lebih mudah ditinjau karena setiap peran agen mengarah ke route yang diketahui.

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)

Ini adalah keputusan penyiapan paling penting dalam migrasi CrewAI OpenAI compatible router. Alias model dapat berubah حسب lingkungan, tetapi kode CrewAI mempertahankan satu root API yang kompatibel dengan OpenAI dan satu pemilik kunci gateway.

Step 3: Tetapkan rute berdasarkan tanggung jawab agen

Berikan setiap agen CrewAI rute LLM yang sesuai dengan profil risikonya. Mulailah dengan set rute kecil. Anda selalu bisa memisahkan lebih banyak peran nanti setelah log membuktikan kebijakan pertama bekerja.

planner = Agent(
    role="Workflow planner",
    goal="Break the request into a short execution plan.",
    backstory="You keep the crew scoped and avoid unnecessary model calls.",
    llm=planner_llm,
)

researcher = Agent(
    role="Researcher",
    goal="Collect only the facts needed for the task.",
    backstory="You prefer source-backed notes over broad speculation.",
    llm=planner_llm,
)

tool_user = Agent(
    role="Tool operator",
    goal="Use approved tools only when the task requires them.",
    backstory="You verify tool inputs before calling external systems.",
    llm=tool_llm,
)

verifier = Agent(
    role="Verifier",
    goal="Check the final answer against requirements and evidence.",
    backstory="You look for missing proof, tool errors, and rollback risks.",
    llm=verifier_llm,
)

Untuk peluncuran awal CrewAI OpenAI compatible router, hindari memberi model unik untuk setiap agen. Dua atau tiga jenis rute biasanya sudah cukup: perencanaan, eksekusi yang mampu memakai tool, dan verifikasi.

Step 4: Bangun crew kecil dan simpan field bukti

Crew dapat tetap biasa. Bukti routing tidak boleh. Tambahkan field sederhana ke deskripsi tugas, output, atau log aplikasi di sekelilingnya agar request dapat dicocokkan dengan log Flatkey.

analysis_task = Task(
    description=(
        "Review the support ticket and produce a short resolution plan. "
        "Do not call tools unless an account lookup is required. "
        "Evidence fields to keep outside this prompt: workflow=crew_support_triage, "
        "route_policy=crewai-router-v1."
    ),
    expected_output="A concise plan with risks, tool needs, and next action.",
    agent=planner,
)

verification_task = Task(
    description=(
        "Check whether the plan cites the ticket facts, avoids unsupported claims, "
        "and names any tool call that still needs approval."
    ),
    expected_output="Pass/fail notes with required fixes.",
    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 dalam templat ini bukan fitur routing CrewAI itu sendiri. Ini adalah kebiasaan observabilitas. Aplikasi Anda harus mencatat request ID, kebijakan rute, alias model, timestamp, dan label kunci sehingga jalur CrewAI OpenAI compatible router dapat diperiksa di Flatkey.

Step 5: Verifikasi panggilan tool sebelum peluncuran luas

Penggunaan tool adalah bagian yang membuat routing kompatibel dengan OpenAI menjadi berisiko. Rute chat biasa mungkin berfungsi, sementara rute yang banyak memakai tool gagal validasi schema, mengalirkan argumen tool dengan cara yang berbeda, atau menghasilkan argumen yang ditolak executor Anda.

Gunakan pengujian tool yang sempit sebelum Anda mempercayai rute tool CrewAI. Untuk perilaku provider yang lebih luas, padukan panduan ini dengan artikel Flatkey tentang OpenAI-compatible tool calling.

Jangan menganggap ini opsional. CrewAI OpenAI compatible router hanya siap produksi ketika rute tool diuji sebagai kontrak terpisah.

Step 6: Tambahkan aturan budget, retry, dan fallback di luar prompt

Jangan meminta agen untuk mengingat setiap aturan operasional dalam bahasa alami. Simpan aturan budget dan fallback dalam kode atau konfigurasi yang dapat diperiksa oleh reviewer.

Ketika fallback disetujui, tetap buat alias fallback eksplisit. Pertanyaan yang berguna bukanlah "apakah crew selesai?" melainkan "rute mana yang selesai, mengapa ia beralih, dan berapa biayanya?" Itulah nilai operasional dari CrewAI OpenAI compatible router.

Langkah 7: Simpan paket verifikasi

Sebelum menjadikan Flatkey sebagai gateway default untuk workflow CrewAI, simpan paket verifikasi yang ringkas.

1. Permintaan curl langsung ke https://router.flatkey.ai/v1/chat/completions berhasil dengan alias model yang dipilih.
2. Setiap objek LLM CrewAI menjalankan satu prompt kecil di luar crew penuh.
3. Crew penuh menjalankan satu workflow sederhana dan satu workflow yang banyak menggunakan tool.
4. Jalur kegagalan yang dipaksa berhenti dengan bersih alih-alih mencoba ulang tanpa henti.
5. Log Flatkey menampilkan key, alias model, timestamp, dan pemilik request yang diharapkan.
6. Field token atau usage terlihat cukup jelas agar pemilik anggaran dapat meninjaunya.
7. Rollback adalah satu perubahan environment atau config, bukan refactor CrewAI.

Gunakan panduan dashboard penggunaan token Flatkey untuk menentukan field apa yang harus diperiksa tim operasi Anda setelah smoke test pertama. Untuk harga dan tinjauan akun, mulai dari halaman harga Flatkey yang aktif, lalu verifikasi rute aktual di akun Anda.

Mengatasi masalah pada CrewAI OpenAI compatible router

Jika permintaan pertama gagal, kecilkan permukaan debugging: satu key, satu base URL, satu alias model, satu LLM CrewAI, satu permintaan langsung, dan satu pencarian log Flatkey.

FAQ

Apakah CrewAI OpenAI compatible router sama dengan model fallback?

Tidak. CrewAI OpenAI compatible router adalah gateway dan batas konfigurasi yang digunakan CrewAI untuk mencapai rute model. Fallback adalah satu kebijakan yang dapat dijalankan ketika rute yang dipilih gagal. Uji routing dan fallback secara terpisah.

Apakah setiap agen CrewAI harus mendapatkan model yang berbeda?

Tidak. Mulailah dengan rute default dan satu rute khusus untuk pekerjaan yang banyak menggunakan tool atau verifier jika diperlukan. Terlalu banyak alias membuat log, tinjauan biaya, dan rollback lebih sulit.

Bisakah CrewAI menggunakan environment variables alih-alih objek LLM eksplisit?

Ya. Dokumentasi CrewAI menunjukkan setup OpenAI-compatible melalui environment variables seperti OPENAI_API_BASE. Objek LLM eksplisit sering kali lebih mudah untuk tinjauan produksi karena setiap peran agen menampilkan model, base_url, dan api_key di satu tempat.

Bisakah saya menggunakan key Flatkey yang sama untuk setiap workflow CrewAI?

Anda bisa, tetapi key spesifik workload lebih mudah diaudit. Gunakan key atau label terpisah ketika tim, environment, anggaran, atau tingkat risiko yang berbeda memerlukan tinjauan terpisah.

Checklist akhir

Setup CrewAI OpenAI compatible router Anda siap melampaui template ketika:

1. Objek LLM CrewAI menggunakan root API Flatkey sebagai base_url.
2. Alias model berada di environment atau config, bukan tersebar di prompt.
3. Setiap peran agen memiliki keputusan rute yang disengaja.
4. Rute yang banyak menggunakan tool lolos pengujian skema, argumen, batas, dan kegagalan.
5. Batas budget, retry, dan fallback berjalan di luar narasi agen.
6. Penggunaan Flatkey atau log request mengonfirmasi key dan alias model yang diharapkan.
7. Rollback adalah satu perubahan config.

Ketika Anda siap mengarahkan lalu lintas CrewAI melalui satu gateway, dapatkan kunci Flatkey, uji satu crew berisiko rendah, dan perluas hanya setelah log membuktikan kebijakan tersebut bekerja.