swarm

Swarm (Eksperimental, Pendidikan)

Kerangka pendidikan yang mengeksplorasi orkestrasi multi-agen yang ergonomis dan ringan.

Peringatan

Swarm saat ini merupakan kerangka kerja sampel eksperimental yang dimaksudkan untuk mengeksplorasi antarmuka ergonomis untuk sistem multi-agen. Ini tidak dimaksudkan untuk digunakan dalam produksi, dan karenanya tidak memiliki dukungan resmi. (Ini juga berarti kami tidak akan meninjau PR atau masalah!)

Tujuan utama Swarm adalah untuk memamerkan pola handoff & rutinitas yang dieksplorasi dalam agen orkestrasi: Handoffs & Rutines Cookbook. Ini tidak dimaksudkan sebagai perpustakaan mandiri, dan terutama untuk tujuan pendidikan.

Memasang

Membutuhkan Python 3.10+

pip install git+ssh://[email protected]/openai/swarm.git

atau

pip install git+https://github.com/openai/swarm.git

Penggunaan

 from swarm import Swarm , Agent

client = Swarm ()

def transfer_to_agent_b ():
    return agent_b


agent_a = Agent (
    name = "Agent A" ,
    instructions = "You are a helpful agent." ,
    functions = [ transfer_to_agent_b ],
)

agent_b = Agent (
    name = "Agent B" ,
    instructions = "Only speak in Haikus." ,
)

response = client . run (
    agent = agent_a ,
    messages = [{ "role" : "user" , "content" : "I want to talk to agent B." }],
)

print ( response . messages [ - 1 ][ "content" ])

 Hope glimmers brightly,
New paths converge gracefully,
What can I assist?

Daftar isi

• Ringkasan
• Contoh
• Dokumentasi
  • Berlari berkerumun
  • Agen
  • Fungsi
  • Mengalir
• Evaluasi
• Utils

Ringkasan

Swarm berfokus pada membuat koordinasi agen dan eksekusi ringan, sangat terkendali, dan mudah diuji.

Ini mencapai ini melalui dua abstraksi primitif: Agent dan handoff . Seorang Agent mencakup instructions dan tools , dan di titik mana pun memilih untuk menyerahkan percakapan ke Agent lain.

Primitif ini cukup kuat untuk mengekspresikan dinamika yang kaya antara alat dan jaringan agen, yang memungkinkan Anda membangun solusi dunia nyata yang dapat diskalakan sambil menghindari kurva pembelajaran yang curam.

Catatan

Agen Swarm tidak terkait dengan asisten di Asisten API. Mereka dinamai dengan cara yang sama untuk kenyamanan, tetapi sebaliknya sama sekali tidak terkait. Swarm sepenuhnya didukung oleh API Penyelesaian Obrolan dan karenanya tanpa kewarganegaraan di antara panggilan.

Mengapa berkerumun

Swarm mengeksplorasi pola yang ringan, dapat diskalakan, dan sangat dapat disesuaikan dengan desain. Pendekatan yang mirip dengan Swarm paling cocok untuk situasi yang berurusan dengan sejumlah besar kemampuan dan instruksi independen yang sulit dikodekan ke dalam satu prompt.

Asisten API adalah pilihan yang bagus untuk pengembang yang mencari utas yang sepenuhnya diselenggarakan dan dibangun dalam manajemen memori dan pengambilan. Namun, Swarm adalah sumber pendidikan bagi pengembang yang penasaran untuk belajar tentang orkestrasi multi-agen. Swarm berjalan (hampir) sepenuhnya pada klien dan, seperti API penyelesaian obrolan, tidak menyimpan keadaan di antara panggilan.

Contoh

Lihat /examples untuk inspirasi! Pelajari lebih lanjut tentang masing -masing di dalam readme -nya.

• basic : Contoh sederhana dasar -dasar seperti pengaturan, panggilan fungsi, handoff, dan variabel konteks
• triage_agent : Contoh sederhana pengaturan langkah triase dasar untuk menyerahkan ke agen yang tepat
• weather_agent : contoh sederhana dari panggilan fungsi
• airline : Pengaturan multi-agen untuk menangani permintaan layanan pelanggan yang berbeda dalam konteks maskapai.
• support_bot : bot layanan pelanggan yang mencakup agen antarmuka pengguna dan agen pusat bantuan dengan beberapa alat
• personal_shopper : agen belanja pribadi yang dapat membantu melakukan penjualan dan pemulihan pengembalian uang

Dokumentasi

Berlari berkerumun

Mulailah dengan instantiating klien Swarm (yang secara internal hanya membuat klien OpenAI ).

 from swarm import Swarm

client = Swarm ()

client.run()

Fungsi swarm run() analog dengan fungsi chat.completions.create() di API Penyelesaian Obrolan - dibutuhkan messages dan mengembalikan messages dan tidak menyimpan keadaan di antara panggilan. Yang penting, bagaimanapun, ini juga menangani eksekusi fungsi agen, hand-off, referensi variabel konteks, dan dapat mengambil beberapa putaran sebelum kembali ke pengguna.

Pada intinya, client.run() mengimplementasikan loop berikut:

1. Dapatkan penyelesaian dari agen saat ini
2. Menjalankan panggilan alat dan menambahkan hasil
3. Beralih agen jika perlu
4. Perbarui variabel konteks, jika perlu
5. Jika tidak ada fungsi baru panggilan, kembalikan

Argumen

Argumen	Jenis	Keterangan	Bawaan
agen	Agent	Agen (awal) yang akan dipanggil.	(diperlukan)
pesan	List	Daftar objek pesan, identik dengan messages penyelesaian obrolan	(diperlukan)
Context_variables	dict	Kamus variabel konteks tambahan, tersedia untuk fungsi dan instruksi agen	{}
Max_Turns	int	Jumlah maksimum putaran percakapan diizinkan	float("inf")
model_override	str	String opsional untuk mengganti model yang digunakan oleh agen	None
execute_tools	bool	Jika False , Eksekusi Ganggu dan segera mengembalikan pesan tool_calls ketika agen mencoba memanggil fungsi	True
sungai kecil	bool	Jika True , aktifkan respons streaming	False
debug	bool	Jika True , memungkinkan pencatatan debug	False

Setelah client.run() selesai (setelah berpotensi beberapa panggilan ke agen dan alat), ia akan mengembalikan Response yang berisi semua status yang diperbarui yang relevan. Secara khusus, messages baru, Agent terakhir yang akan dipanggil, dan context_variables yang paling mutakhir. Anda dapat memberikan nilai -nilai ini (ditambah pesan pengguna baru) ke dalam eksekusi Anda berikutnya dari client.run() untuk melanjutkan interaksi di mana ia ditinggalkan - seperti chat.completions.create() . (Fungsi run_demo_loop mengimplementasikan contoh loop eksekusi penuh di /swarm/repl/repl.py .)

Bidang Response

Bidang	Jenis	Keterangan
pesan	List	Daftar objek pesan yang dihasilkan selama percakapan. Sangat mirip dengan messages penyelesaian obrolan, tetapi dengan bidang sender yang menunjukkan Agent mana pesan berasal dari.
agen	Agent	Agen terakhir untuk menangani pesan.
Context_variables	dict	Sama seperti variabel input, ditambah perubahan apa pun.

Agen

Agent hanya merangkum satu set instructions dengan satu set functions (ditambah beberapa pengaturan tambahan di bawah), dan memiliki kemampuan untuk menyerahkan eksekusi ke Agent lain.

Meskipun tergoda untuk mempersonifikasikan Agent sebagai "seseorang yang melakukan x", itu juga dapat digunakan untuk mewakili alur kerja atau langkah yang sangat spesifik yang ditentukan oleh serangkaian instructions dan functions (misalnya satu set langkah, pengambilan yang kompleks, satu langkah dari tunggal dari transformasi data, dll). Hal ini memungkinkan Agent untuk disusun ke dalam jaringan "agen", "alur kerja", dan "tugas", semuanya diwakili oleh primitif yang sama.

Bidang Agent

Bidang	Jenis	Keterangan	Bawaan
nama	str	Nama agen.	"Agent"
model	str	Model yang akan digunakan oleh agen.	"gpt-4o"
instruksi	str or func() -> str	Instruksi untuk agen, dapat berupa string atau callable mengembalikan string.	"You are a helpful agent."
fungsi	List	Daftar fungsi yang dapat dihubungi agen.	[]
Tool_choice	str	Pilihan alat untuk agen, jika ada.	None

Instruksi

instructions Agent secara langsung dikonversi menjadi prompt system percakapan (sebagai pesan pertama). Hanya instructions dari Agent aktif yang akan hadir pada waktu tertentu (misalnya jika ada handoff Agent , prompt system akan berubah, tetapi riwayat obrolan tidak akan.)

 agent = Agent (
   instructions = "You are a helpful agent."
)

instructions bisa menjadi str biasa, atau fungsi yang mengembalikan str . Fungsi ini secara opsional dapat menerima parameter context_variables , yang akan diisi oleh context_variables yang diteruskan ke client.run() .

 def instructions ( context_variables ):
   user_name = context_variables [ "user_name" ]
   return f"Help the user, { user_name } , do whatever they want."

agent = Agent (
   instructions = instructions
)
response = client . run (
   agent = agent ,
   messages = [{ "role" : "user" , "content" : "Hi!" }],
   context_variables = { "user_name" : "John" }
)
print ( response . messages [ - 1 ][ "content" ])

 Hi John, how can I assist you today?

Fungsi

• Agent Swarm dapat menghubungi fungsi Python secara langsung.
• Fungsi biasanya harus mengembalikan str (nilai akan dicoba dilemparkan sebagai str ).
• Jika suatu fungsi mengembalikan Agent , eksekusi akan ditransfer ke Agent itu.
• Jika suatu fungsi mendefinisikan parameter context_variables , itu akan diisi oleh context_variables yang diteruskan ke client.run() .

 def greet ( context_variables , language ):
   user_name = context_variables [ "user_name" ]
   greeting = "Hola" if language . lower () == "spanish" else "Hello"
   print ( f" { greeting } , { user_name } !" )
   return "Done"

agent = Agent (
   functions = [ greet ]
)

client . run (
   agent = agent ,
   messages = [{ "role" : "user" , "content" : "Usa greet() por favor." }],
   context_variables = { "user_name" : "John" }
)

 Hola, John!

• Jika panggilan fungsi Agent memiliki kesalahan (fungsi yang hilang, argumen yang salah, kesalahan) respons kesalahan akan ditambahkan ke obrolan sehingga Agent dapat memulihkan dengan anggun.
• Jika beberapa fungsi dipanggil oleh Agent , mereka akan dieksekusi dalam urutan itu.

Handoff dan memperbarui variabel konteks

Agent dapat menyerahkan ke Agent lain dengan mengembalikannya dalam suatu function .

 sales_agent = Agent ( name = "Sales Agent" )

def transfer_to_sales ():
   return sales_agent

agent = Agent ( functions = [ transfer_to_sales ])

response = client . run ( agent , [{ "role" : "user" , "content" : "Transfer me to sales." }])
print ( response . agent . name )

 Sales Agent

Ini juga dapat memperbarui context_variables dengan mengembalikan objek Result yang lebih lengkap. Ini juga dapat berisi value dan agent , jika Anda ingin fungsi tunggal untuk mengembalikan nilai, memperbarui agen, dan memperbarui variabel konteks (atau subset dari ketiganya).

 sales_agent = Agent ( name = "Sales Agent" )

def talk_to_sales ():
   print ( "Hello, World!" )
   return Result (
       value = "Done" ,
       agent = sales_agent ,
       context_variables = { "department" : "sales" }
   )

agent = Agent ( functions = [ talk_to_sales ])

response = client . run (
   agent = agent ,
   messages = [{ "role" : "user" , "content" : "Transfer me to sales" }],
   context_variables = { "user_name" : "John" }
)
print ( response . agent . name )
print ( response . context_variables )

 Sales Agent
{'department': 'sales', 'user_name': 'John'}

Catatan

Jika Agent memanggil banyak fungsi untuk diserahkan ke Agent , hanya fungsi handoff terakhir yang akan digunakan.

Skema fungsi

Swarm secara otomatis mengubah fungsi menjadi skema JSON yang diteruskan ke tools penyelesaian obrolan.

• Docstrings diubah menjadi description fungsi.
• Parameter tanpa nilai default diatur ke required .
• Jenis petunjuk dipetakan ke type parameter (dan default ke string ).
• Deskripsi per-parameter tidak didukung secara eksplisit, tetapi harus bekerja sama jika hanya ditambahkan dalam docString. (Di masa mendatang, argumen docstring parsing dapat ditambahkan.)

 def greet ( name , age : int , location : str = "New York" ):
   """Greets the user. Make sure to get their name and age before calling.

   Args:
      name: Name of the user.
      age: Age of the user.
      location: Best place on earth.
   """
   print ( f"Hello { name } , glad you are { age } in { location } !" )

 {
   "type" : "function" ,
   "function" : {
      "name" : "greet" ,
      "description" : "Greets the user. Make sure to get their name and age before calling.nnArgs:n   name: Name of the user.n   age: Age of the user.n   location: Best place on earth." ,
      "parameters" : {
         "type" : "object" ,
         "properties" : {
            "name" : { "type" : "string" } ,
            "age" : { "type" : "integer" } ,
            "location" : { "type" : "string" }
         } ,
         "required" : [ "name" , "age" ]
      }
   }
} 

Mengalir

 stream = client . run ( agent , messages , stream = True )
for chunk in stream :
   print ( chunk )

Menggunakan acara yang sama dengan streaming API penyelesaian obrolan. Lihat process_and_print_streaming_response di /swarm/repl/repl.py sebagai contoh.

Dua jenis acara baru telah ditambahkan:

• {"delim":"start"} dan {"delim":"end"} , untuk memberi sinyal setiap kali Agent menangani satu pesan (respons atau panggilan fungsi). Ini membantu mengidentifikasi sakelar antar Agent .
• {"response": Response} akan mengembalikan objek Response di akhir aliran dengan respons agregat (lengkap), untuk kenyamanan.

Evaluasi

Evaluasi sangat penting untuk proyek apa pun, dan kami mendorong pengembang untuk membawa suite eval mereka sendiri untuk menguji kinerja kawanan mereka. Sebagai referensi, kami memiliki beberapa contoh cara mengevaluasi gerombolan di airline , weather_agent dan triage_agent quickStart. Lihat Readmes untuk lebih jelasnya.

Utils

Gunakan run_demo_loop untuk menguji segerombolan Anda! Ini akan menjalankan repl pada baris perintah Anda. Mendukung streaming.

 from swarm . repl import run_demo_loop
...
run_demo_loop ( agent , stream = True )

Kontributor inti

• Ilan Bigio - Ibigio
• James Hills - JHills20
• Shyamal Anadkat - Shyamal -Anadkat
• Charak Jaiswal - Charuj
• Colin Jarvis - Colin -Openai
• Katia Gil Guzman - Katia -Openai