Bagaimana Cara Menggunakan OpenAI Agents SDK?

OpenAI Agents SDK adalah pustaka Python yang dirancang untuk menyederhanakan pengembangan agen AI yang didukung oleh model bahasa OpenAI. Pustaka ini membekali pengembang dengan alat untuk membuat agen khusus tugas, mengintegrasikan fungsionalitas eksternal, mengelola delegasi tugas antar-agen, memberlakukan validasi input/output, dan memantau alur eksekusi. Panduan ini memberikan penjelasan teknis terperinci tentang cara menginstal, mengonfigurasi, dan memanfaatkan SDK secara efektif, memastikan minimal 2000 kata dengan fokus pada presisi dan aplikasi praktis.

💡

Sebelum kita mulai, berikut adalah tip cepat: Karena kita akan banyak bekerja dengan API dalam panduan ini, Anda mungkin ingin mengambil Apidog. Ini adalah alat gratis yang membuat pengujian dan debugging API menjadi sangat mudah, sempurna untuk bereksperimen dengan OpenAI Agents SDK. Anda dapat mengunduh Apidog secara gratis di sini. Percayalah, ini akan menyelamatkan Anda dari beberapa masalah di kemudian hari!

button

Pendahuluan

OpenAI Agents SDK menyediakan kerangka kerja terstruktur untuk membangun sistem multi-agen di mana setiap agen disesuaikan untuk melakukan tugas-tugas tertentu. Agen-agen ini dapat berinteraksi dengan pengguna, menjalankan tindakan melalui alat yang terintegrasi, dan berkolaborasi dengan meneruskan tugas ke agen lain. Komponen utama dari SDK meliputi:

Agen: Instansi model bahasa yang dikonfigurasi dengan instruksi dan peran tertentu.
Alat: Fungsi atau layanan (misalnya, pencarian web, kode Python khusus) yang memperluas kemampuan agen.
Serah Terima: Mekanisme yang memungkinkan agen untuk mendelegasikan tugas ke agen lain dengan mulus.
Pelindung: Lapisan validasi untuk memastikan input dan output memenuhi kriteria yang ditentukan.
Pelacakan: Log eksekusi untuk debugging dan analisis kinerja.

Panduan ini dirancang untuk pengembang dengan pemahaman dasar tentang Python dan interaksi API, memberikan penjelasan rinci, contoh kode, dan praktik terbaik untuk membuat sumber daya yang kuat dan komprehensif.

Instalasi dan Konfigurasi

Pengaturan yang tepat sangat penting untuk menggunakan OpenAI Agents SDK secara efektif. Bagian ini mencakup prasyarat, pengaturan lingkungan, instalasi, dan verifikasi.

Prasyarat

Sebelum melanjutkan, pastikan hal berikut:

Python 3.8+: Verifikasi versi Python Anda dengan python --version. Instal dari python.org jika diperlukan.

Kunci API OpenAI: Dapatkan kunci Anda dari platform.openai.com di bawah pengaturan akun Anda. Kunci ini mengotentikasi permintaan ke server OpenAI.

Langkah 1: Siapkan Lingkungan Virtual

Lingkungan virtual mengisolasi dependensi proyek, mencegah konflik dengan proyek Python lainnya. Untuk membuat dan mengaktifkannya:

Linux/macOS:

python -m venv agents_env
source agents_env/bin/activate

Windows:

python -m venv agents_env
agents_env\Scripts\activate

Setelah diaktifkan, prompt terminal Anda harus mencerminkan lingkungan (misalnya, (agents_env)). Langkah ini adalah praktik terbaik untuk pengembangan Python, memastikan ruang kerja yang bersih.

Langkah 2: Instal SDK

Dengan lingkungan virtual aktif, instal SDK menggunakan pip:

pip install openai-agents

Perintah ini mengambil versi terbaru dari SDK dan dependensinya dari PyPI. Untuk mengonfirmasi instalasi, jalankan:

pip show openai-agents-python

Ini menampilkan metadata, termasuk nomor versi, yang mengonfirmasi bahwa paket telah diinstal.

Langkah 3: Konfigurasikan Kunci API

SDK memerlukan kunci API OpenAI untuk berfungsi. Atur sebagai variabel lingkungan untuk menghindari penyematannya dalam kode Anda, yang meningkatkan keamanan:

Linux/macOS:

export OPENAI_API_KEY='your-api-key'

Windows:

set OPENAI_API_KEY='your-api-key'

Untuk membuat ini persisten di seluruh sesi, tambahkan perintah ke file konfigurasi shell Anda (misalnya, .bashrc atau .zshrc pada sistem Unix). Atau, Anda dapat mengaturnya secara terprogram di Python, meskipun ini kurang aman:

import os
os.environ["OPENAI_API_KEY"] = "your-api-key"

Langkah 4: Verifikasi Instalasi

Uji pengaturan dengan agen minimal untuk memastikan semuanya berfungsi:

from agents import Agent, Runner

agent = Agent(name="TestAgent", instructions="Return 'Setup successful'")
result = Runner.run_sync(agent, "Run test")
print(result.final_output)  # Expected output: "Setup successful"

Jika ini mencetak "Setup successful," instalasi Anda berfungsi. Masalah umum meliputi:

Kunci API Tidak Valid: Periksa kembali kunci dan pastikan tidak ada spasi atau kesalahan ketik tambahan.
Kesalahan Jaringan: Verifikasi koneksi internet Anda dan status server OpenAI.

Membuat Agen

Agen adalah blok bangunan fundamental dari SDK, masing-masing didefinisikan oleh peran dan perilaku yang unik.

Inisialisasi Agen

Kelas Agent digunakan untuk membuat instansi agen. Parameter utama meliputi:

name: Pengidentifikasi string (misalnya, "MathAgent").
instructions: String yang menentukan tujuan agen (misalnya, "Selesaikan masalah matematika").
model: Model OpenAI yang akan digunakan (default: gpt-4).
temperature: Angka floating antara 0 dan 1 yang mengontrol keacakan output (default: 0.7).

Contoh: Agen Dasar

Berikut adalah agen sederhana untuk aritmatika:

from agents import Agent, Runner

agent = Agent(
    name="MathAgent",
    instructions="Solve arithmetic expressions."
)
result = Runner.run_sync(agent, "Calculate 10 * 2")
print(result.final_output)  # Output: "20"

Metode Runner.run_sync mengeksekusi agen secara sinkron, mengembalikan objek hasil dengan atribut final_output.

Konfigurasi Tingkat Lanjut

Sesuaikan agen untuk kebutuhan spesifik dengan menyesuaikan parameter:

agent = Agent(
    name="CreativeWriter",
    instructions="Write a short story based on the prompt.",
    model="gpt-4",
    temperature=0.9
)
result = Runner.run_sync(agent, "A robot in a distant galaxy")
print(result.final_output)  # Output: A creative story

Model: gpt-4 menawarkan penalaran yang superior, sementara gpt-3.5-turbo lebih cepat dan lebih murah untuk tugas yang lebih sederhana.
Temperature: Nilai yang lebih rendah (misalnya, 0.2) menghasilkan output yang dapat diprediksi; nilai yang lebih tinggi (misalnya, 0.9) meningkatkan kreativitas.

Contoh Beberapa Agen

Buat agen yang berbeda untuk tugas yang berbeda:

support_agent = Agent(
    name="SupportBot",
    instructions="Answer technical support questions."
)
code_agent = Agent(
    name="CodeHelper",
    instructions="Generate Python code snippets."
)

support_result = Runner.run_sync(support_agent, "How do I install Python?")
code_result = Runner.run_sync(code_agent, "Write a function to add two numbers")
print(support_result.final_output)  # Output: Installation instructions
print(code_result.final_output)     # Output: "def add(a, b): return a + b"

Ini menunjukkan fleksibilitas SDK dalam menangani berbagai peran.

Mengintegrasikan Alat

Alat meningkatkan agen dengan memungkinkan mereka melakukan tindakan eksternal. SDK mendukung alat yang dihosting, alat fungsi khusus, dan alat berbasis agen.

Menggunakan Alat yang Dihosting

Alat yang dihosting, seperti web_search, sudah dibuat sebelumnya dan siap digunakan:

from agents import Agent, Runner, web_search

agent = Agent(
    name="ResearchAgent",
    instructions="Answer questions using web search.",
    tools=[web_search]
)
result = Runner.run_sync(agent, "What is the capital of France?")
print(result.final_output)  # Output: "The capital of France is Paris."

Agen secara otomatis memanggil web_search untuk mengambil data waktu nyata.

Membuat Alat Fungsi Khusus

Tentukan alat khusus dengan dekorator @function_tool. Alat harus menerima dan mengembalikan string.

Contoh: Alat Pengambilan Data

from agents import Agent, Runner, function_tool

@function_tool
def fetch_data(id: str) -> str:
    """Return data for the given ID."""
    # Simulated database lookup
    return f"Data for ID {id}: active"

agent = Agent(
    name="DataAgent",
    instructions="Retrieve data using the tool.",
    tools=[fetch_data]
)
result = Runner.run_sync(agent, "Fetch data for ID 123")
print(result.final_output)  # Output: "Data for ID 123: active"

Mengintegrasikan API Eksternal

Alat dapat terhubung ke layanan eksternal. Berikut adalah contoh alat cuaca:

import requests
from agents import function_tool, Agent, Runner

@function_tool
def get_weather(city: str) -> str:
    """Get the current weather for a city."""
    api_key = "your-weather-api-key"  # Replace with a real key
    url = f"http://api.weatherapi.com/v1/current.json?key={api_key}&q={city}"
    response = requests.get(url)
    if response.status_code == 200:
        data = response.json()
        return f"The weather in {city} is {data['current']['condition']['text']}."
    return "Weather data unavailable."

agent = Agent(
    name="WeatherAgent",
    instructions="Provide weather updates using the tool.",
    tools=[get_weather]
)
result = Runner.run_sync(agent, "What's the weather in Tokyo?")
print(result.final_output)  # Output: "The weather in Tokyo is Sunny." (example)

Mendaftar untuk kunci API gratis di weatherapi.com untuk menguji ini.

Menggabungkan Beberapa Alat

Agen dapat menggunakan beberapa alat secara bersamaan:

@function_tool
def log_entry(text: str) -> str:
    """Log a message."""
    return f"Logged: {text}"

agent = Agent(
    name="MultiToolAgent",
    instructions="Use tools to search and log.",
    tools=[web_search, log_entry]
)
result = Runner.run_sync(agent, "Search for AI trends and log the query")
print(result.final_output)  # Output includes search results and log confirmation

Serah Terima Agen

Serah terima memungkinkan agen untuk mendelegasikan tugas, memungkinkan alur kerja yang kompleks.

Menyiapkan Serah Terima

Tentukan agen utama dengan akses ke agen sekunder melalui parameter handoffs:

from agents import Agent, Runner

english_agent = Agent(
    name="EnglishHelper",
    instructions="Respond in English only."
)
spanish_agent = Agent(
    name="SpanishHelper",
    instructions="Respond in Spanish only."
)
triage_agent = Agent(
    name="LanguageRouter",
    instructions="Detect the language and hand off to the appropriate agent.",
    handoffs=[english_agent, spanish_agent]
)

result = Runner.run_sync(triage_agent, "Hola, ¿qué tal?")
print(result.final_output)  # Output: "¡Bien, gracias!" (or similar)

triage_agent menganalisis input dan mendelegasikan ke agen khusus bahasa yang sesuai.

Logika Serah Terima

Keputusan serah terima bergantung pada instruksi agen utama. Misalnya:

"Jika input berisi kata-kata Spanyol, serahkan ke SpanishHelper."
"Untuk input bahasa Inggris, gunakan EnglishHelper."

Uji dengan input bahasa Inggris:

result = Runner.run_sync(triage_agent, "How are you?")
print(result.final_output)  # Output: "I'm good, thanks!"

Serah Terima Bertingkat

Untuk alur kerja yang lebih dalam, agen dapat menyerahkan ke agen lain dengan serah terima:

analysis_agent = Agent(
    name="AnalysisBot",
    instructions="Analyze data and hand off for reporting."
)
report_agent = Agent(
    name="ReportBot",
    instructions="Generate a report from analysis."
)
main_agent = Agent(
    name="WorkflowManager",
    instructions="Start with analysis.",
    handoffs=[analysis_agent, report_agent]
)

result = Runner.run_sync(main_agent, "Analyze sales data")
print(result.final_output)  # Output: A generated report

Menerapkan Pelindung

Pelindung memberlakukan batasan pada input dan output menggunakan model Pydantic.

Mendefinisikan Pelindung

Buat model untuk memvalidasi struktur output:

from pydantic import BaseModel
from agents import Agent, Runner

class QuestionCheck(BaseModel):
    is_question: bool
    reason: str

guard_agent = Agent(
    name="QuestionGuard",
    instructions="Determine if the input is a question.",
    output_type=QuestionCheck
)

result = Runner.run_sync(guard_agent, "What is the capital of France?")
print(result.final_output)  # Output: {"is_question": true, "reason": "Ends with a question mark"}

Integrasi Alur Kerja

Gunakan pelindung untuk memfilter input:

task_agent = Agent(
    name="TaskProcessor",
    instructions="Process questions only.",
    handoffs=[guard_agent]
)
result = Runner.run_sync(task_agent, "Tell me a story")
print(result.final_output)  # Output indicates it’s not a question

Pelacakan dan Debugging

Pelacakan mencatat detail eksekusi agen, dapat diakses melalui Dasbor OpenAI.

Mengaktifkan Pelacakan

Pelacakan bersifat otomatis. Setiap eksekusi menghasilkan jejak dengan:

Data input/output
Panggilan alat
Acara serah terima
Kesalahan

Contoh Debugging

Jika agen gagal, tinjau jejak untuk mengidentifikasi:

Parameter alat yang salah
Salah rute serah terima
Kesalahan API

Praktik Terbaik

Optimasi Kinerja

Pilihan Model: Gunakan gpt-3.5-turbo untuk kecepatan, gpt-4 untuk penalaran kompleks.
Temperature: 0.2 untuk presisi, 0.9 untuk kreativitas.
Eksekusi Asinkron: Gunakan Runner.run_async untuk tugas paralel.

Penanganan Kesalahan

Alat: Kembalikan pesan kesalahan yang jelas (misalnya, "ID Tidak Valid").
Serah Terima: Sertakan agen fallback untuk kegagalan.

Desain Alur Kerja

Modularitas: Pisahkan tugas di seluruh agen.
Kejelasan: Tulis instruksi yang tidak ambigu.
Validasi: Terapkan pelindung pada tahap-tahap kunci.

Kesimpulan

OpenAI Agents SDK memberdayakan pengembang untuk membangun sistem AI canggih dengan agen khusus, alat terintegrasi, dan alur kerja kolaboratif. Panduan ini memberikan fondasi teknis untuk memanfaatkan potensi penuhnya, lengkap dengan contoh dan praktik terbaik.

Jadi, apa selanjutnya? Mulai bereksperimen! Bermain dengan instruksi, alat, dan alur kerja yang berbeda. Dan jika Anda mengalami kendala, alat seperti Apidog dapat membantu dengan pengujian API, dapatkan secara gratis.

button