swarm

Swarm (ทดลองการศึกษา)

กรอบการศึกษาสำรวจการยศาสตร์ที่มีน้ำหนักเบาและมีน้ำหนักเบา

คำเตือน

Swarm ปัจจุบันเป็นกรอบตัวอย่างการทดลองที่มีวัตถุประสงค์เพื่อสำรวจอินเตอร์เฟสการยศาสตร์สำหรับระบบหลายตัวแทน มันไม่ได้มีวัตถุประสงค์เพื่อใช้ในการผลิตดังนั้นจึงไม่มีการสนับสนุนอย่างเป็นทางการ (นี่ก็หมายความว่าเราจะไม่ตรวจสอบ PRS หรือปัญหา!)

เป้าหมายหลักของ Swarm คือการจัดแสดงรูปแบบการส่งมอบและกิจวัตรประจำวันที่สำรวจในตัวแทนการเตรียมการ: ตำราแฮนด์ออฟและรูทีน มันไม่ได้หมายถึงเป็นห้องสมุดแบบสแตนด์อโลนและเป็นหลักเพื่อการศึกษา

ติดตั้ง

ต้องใช้ Python 3.10+

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

หรือ

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

การใช้งาน

 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?

สารบัญ

• ภาพรวม
• ตัวอย่าง
• เอกสาร
  • การวิ่ง
  • ตัวแทน
  • ฟังก์ชั่น
  • การสตรีม
• การประเมินผล
• เครื่องใช้

ภาพรวม

Swarm มุ่งเน้นไปที่ การประสานงาน ตัวแทนและ การดำเนินการ ที่มีน้ำหนักเบาควบคุมได้สูงและทดสอบได้ง่าย

มันทำสิ่งนี้ได้ผ่านบทที่สองแบบดั้งเดิม: Agent S และ Handoffs Agent ครอบคลุม instructions และ tools และสามารถเลือกที่จะส่งการสนทนาไปยัง Agent อื่น

These primitives are powerful enough to express rich dynamics between tools and networks of agents, allowing you to build scalable, real-world solutions while avoiding a steep learning curve.

บันทึก

ตัวแทนฝูงไม่เกี่ยวข้องกับผู้ช่วยใน API ผู้ช่วย พวกเขามีชื่อคล้ายกันเพื่อความสะดวก แต่ไม่เกี่ยวข้องอย่างสมบูรณ์ Swarm ได้รับการขับเคลื่อนโดย API การแชทเสร็จสมบูรณ์และไม่มีสัญลักษณ์ระหว่างการโทร

ทำไมฝูง

Swarm สำรวจรูปแบบที่มีน้ำหนักเบาปรับขนาดได้และปรับแต่งได้สูงโดยการออกแบบ Approaches similar to Swarm are best suited for situations dealing with a large number of independent capabilities and instructions that are difficult to encode into a single prompt.

Assistants API เป็นตัวเลือกที่ยอดเยี่ยมสำหรับนักพัฒนาที่กำลังมองหาเธรดที่โฮสต์อย่างเต็มรูปแบบและการจัดการหน่วยความจำในตัวและการดึงข้อมูล อย่างไรก็ตาม Swarm เป็นทรัพยากรทางการศึกษาสำหรับนักพัฒนาที่อยากรู้อยากเห็นเกี่ยวกับการประสานหลายตัวแทน Swarm Runs (เกือบ) ทั้งหมดบนลูกค้าและเหมือนกับการแชทเสร็จสิ้น API ไม่ได้จัดเก็บสถานะระหว่างการโทร

ตัวอย่าง

ตรวจสอบ /examples สำหรับแรงบันดาลใจ! เรียนรู้เพิ่มเติมเกี่ยวกับแต่ละคนใน readme

• basic : ตัวอย่างง่ายๆของพื้นฐานเช่นการตั้งค่าการเรียกใช้ฟังก์ชันแฮนด์ออฟและตัวแปรบริบท
• triage_agent : ตัวอย่างง่ายๆในการตั้งค่าขั้นตอนการไตรมาสพื้นฐานเพื่อส่งไปยังตัวแทนที่เหมาะสม
• weather_agent : ตัวอย่างง่ายๆของการเรียกใช้ฟังก์ชัน
• airline : การตั้งค่าหลายตัวแทนสำหรับการจัดการคำขอบริการลูกค้าที่แตกต่างกันในบริบทของสายการบิน
• support_bot : บอตบริการลูกค้าซึ่งรวมถึงตัวแทนส่วนต่อประสานผู้ใช้และตัวแทนศูนย์ช่วยเหลือที่มีเครื่องมือหลายอย่าง
• personal_shopper : ตัวแทนการช็อปปิ้งส่วนบุคคลที่สามารถช่วยในการทำยอดขายและขอคืนเงิน

เอกสาร

การวิ่ง

เริ่มต้นด้วยการสร้างอินสแตนซ์ไคลเอ็นต์ฝูง (ซึ่งภายในอินสแตนติสลูกค้า OpenAI )

 from swarm import Swarm

client = Swarm ()

client.run()

Swarm's run() function is analogous to the chat.completions.create() function in the Chat Completions API – it takes messages and returns messages and saves no state between calls. Importantly, however, it also handles Agent function execution, hand-offs, context variable references, and can take multiple turns before returning to the user.

ที่แกนกลางของ Swarm client.run() ใช้ลูปต่อไปนี้:

1. รับความสำเร็จจากตัวแทนปัจจุบัน
2. เรียกใช้การเรียกใช้เครื่องมือและผนวกผลลัพธ์
3. สลับตัวแทนหากจำเป็น
4. อัปเดตตัวแปรบริบทหากจำเป็น
5. หากไม่มีการเรียกใช้ฟังก์ชันใหม่ให้ส่งคืน

ข้อโต้แย้ง

การโต้แย้ง	พิมพ์	คำอธิบาย	ค่าเริ่มต้น
ตัวแทน	Agent	ตัวแทน (เริ่มต้น) ที่จะเรียก	(ที่จำเป็น)
ข้อความ	List	รายการวัตถุข้อความเหมือนกับ messages การแชทเสร็จสมบูรณ์	(ที่จำเป็น)
context_variables	dict	พจนานุกรมของตัวแปรบริบทเพิ่มเติมพร้อมใช้งานสำหรับฟังก์ชั่นและคำแนะนำตัวแทน	{}
max_turns	int	จำนวนการเปลี่ยนการสนทนาสูงสุดที่อนุญาต	float("inf")
model_override	str	สตริงเสริมเพื่อแทนที่โมเดลที่ใช้โดยตัวแทน	None
Execute_tools	bool	หากเป็น False การดำเนินการขัดจังหวะและส่งคืนข้อความ tool_calls ทันทีเมื่อเอเจนต์พยายามเรียกใช้ฟังก์ชัน	True
ลำธาร	bool	หากเป็น True ให้เปิดใช้งานการตอบสนองการสตรีม	False
การดีบัก	bool	ถ้า True ให้เปิดใช้งานการบันทึกการดีบัก	False

เมื่อ client.run() เสร็จสิ้น (หลังจากการโทรหลายครั้งไปยังตัวแทนและเครื่องมือ) มันจะส่งคืน Response กลับที่มีสถานะการอัปเดตที่เกี่ยวข้องทั้งหมด โดยเฉพาะ messages ใหม่ Agent สุดท้ายที่จะเรียกและเป็น context_variables ที่ทันสมัยที่สุด คุณสามารถผ่านค่าเหล่านี้ (รวมถึงข้อความผู้ใช้ใหม่) ในการดำเนินการครั้งต่อไปของ client.run() เพื่อดำเนินการต่อการโต้ตอบที่มันทิ้งไว้ - เหมือนกับ chat.completions.create() (ฟังก์ชั่น run_demo_loop ใช้ตัวอย่างของลูปการดำเนินการเต็มรูปแบบใน /swarm/repl/repl.py )

เขตข้อมูล Response

สนาม	พิมพ์	คำอธิบาย
ข้อความ	List	รายการวัตถุข้อความที่สร้างขึ้นระหว่างการสนทนา คล้ายกับ messages การแชทเสร็จสมบูรณ์ แต่มีฟิลด์ sender ระบุว่า Agent ใดที่ข้อความมาจาก
ตัวแทน	Agent	เอเจนต์สุดท้ายในการจัดการข้อความ
context_variables	dict	เช่นเดียวกับตัวแปรอินพุตรวมถึงการเปลี่ยนแปลงใด ๆ

ตัวแทน

Agent เพียงแค่ห่อหุ้มชุด instructions ด้วยชุดของ functions (รวมถึงการตั้งค่าเพิ่มเติมด้านล่าง) และมีความสามารถในการส่งการดำเนินการกับ Agent อื่น

ในขณะที่มันเป็นสิ่งที่ดึงดูดให้เป็นตัวแทน Agent ในฐานะ "คนที่ทำ X" แต่ก็สามารถใช้เพื่อเป็นตัวแทนเวิร์กโฟลว์ที่เฉพาะเจาะจงหรือขั้นตอนที่กำหนดโดยชุด instructions และ functions (เช่นชุดของขั้นตอนการดึงข้อมูลที่ซับซ้อนขั้นตอนเดียวของขั้นตอนเดียว การแปลงข้อมูล ฯลฯ ) สิ่งนี้ช่วยให้ Agent ถูกแต่งขึ้นเป็นเครือข่ายของ "ตัวแทน", "เวิร์กโฟลว์" และ "งาน" ซึ่งทั้งหมดแสดงโดยดั้งเดิมเดียวกัน

ฟิลด์ Agent

สนาม	พิมพ์	คำอธิบาย	ค่าเริ่มต้น
ชื่อ	str	ชื่อของตัวแทน	"Agent"
แบบอย่าง	str	โมเดลที่จะใช้โดยตัวแทน	"gpt-4o"
คำแนะนำ	str หรือ func() -> str	คำแนะนำสำหรับเอเจนต์สามารถเป็นสตริงหรือเรียกได้ว่าเรียกคืนสตริง	"You are a helpful agent."
ฟังก์ชั่น	List	รายการฟังก์ชั่นที่เอเจนต์สามารถเรียกได้	[]
tool_choice	str	ตัวเลือกเครื่องมือสำหรับเอเจนต์ถ้ามี	None

คำแนะนำ

instructions Agent จะถูกแปลงโดยตรงเป็นพรอมต์ system ของการสนทนา (เป็นข้อความแรก) เฉพาะ instructions ของ Agent ที่ใช้งานอยู่ในเวลาใดก็ตาม (เช่นหากมีการแฮนด์ Agent พรอมต์ system จะเปลี่ยนไป แต่ประวัติการแชทจะไม่เป็นเช่นนั้น)

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

instructions อาจเป็น str ปกติหรือฟังก์ชั่นที่ส่งคืน str ฟังก์ชั่นสามารถเลือกได้รับพารามิเตอร์ context_variables ซึ่งจะถูกเติมโดย context_variables ที่ส่งผ่านไปยัง 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?

ฟังก์ชั่น

• Swarm Agent S สามารถเรียกฟังก์ชั่น Python ได้โดยตรง
• ฟังก์ชั่นควรส่งคืน str (ค่าจะถูกพยายามเลือกเป็น str )
• หากฟังก์ชั่นส่งคืน Agent การดำเนินการจะถูกโอนไปยัง Agent นั้น
• หากฟังก์ชั่นกำหนดพารามิเตอร์ context_variables มันจะถูกเติมโดย context_variables ที่ส่งผ่านไปยัง 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!

• หากการเรียกใช้ฟังก์ชัน Agent มีข้อผิดพลาด (ฟังก์ชั่นที่หายไป, อาร์กิวเมนต์ผิด, ข้อผิดพลาด) การตอบกลับข้อผิดพลาดจะถูกผนวกเข้ากับการแชทเพื่อให้ Agent สามารถกู้คืนได้อย่างสง่างาม
• หาก Agent เรียกฟังก์ชั่นหลายฟังก์ชันพวกเขาจะถูกดำเนินการตามลำดับนั้น

แฮนด์ออฟและอัปเดตตัวแปรบริบท

Agent สามารถส่งมอบให้กับ Agent อื่นโดยส่งคืนใน 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

นอกจากนี้ยังสามารถอัปเดต context_variables โดยการส่งคืนวัตถุ Result ที่สมบูรณ์ยิ่งขึ้น This can also contain a value and an agent , in case you want a single function to return a value, update the agent, and update the context variables (or any subset of the three).

 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'}

บันทึก

หาก Agent เรียกฟังก์ชั่นหลายฟังก์ชั่นเพื่อส่งไปยัง Agent จะใช้ฟังก์ชันแฮนด์ออฟสุดท้ายเท่านั้น

สคีมาฟังก์ชั่น

Swarm แปลงฟังก์ชั่นเป็นสคีมา JSON โดยอัตโนมัติซึ่งส่งผ่านไปยัง tools การแชทเสร็จสมบูรณ์

• เอกสารถูกเปลี่ยนเป็น description ฟังก์ชั่น
• พารามิเตอร์ที่ไม่มีค่าเริ่มต้นถูกตั้งค่าเป็น required
• คำแนะนำประเภทถูกแมปกับ type ของพารามิเตอร์ (และค่าเริ่มต้นเป็น string )
• คำอธิบายต่อพารามิเตอร์ไม่ได้รับการสนับสนุนอย่างชัดเจน แต่ควรทำงานในทำนองเดียวกันหากเพิ่งเพิ่มในเอกสาร (ในการแยกการแยกการโต้เถียงของเอกสารในอนาคตอาจถูกเพิ่มเข้ามา)

 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" ]
      }
   }
} 

การสตรีม

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

ใช้กิจกรรมเดียวกันกับการแชทเสร็จสิ้นการสตรีม API ดู process_and_print_streaming_response ใน /swarm/repl/repl.py เป็นตัวอย่าง

มีการเพิ่มกิจกรรมใหม่สองประเภท:

• {"delim":"start"} และ {"delim":"end"} เพื่อส่งสัญญาณแต่ละครั้ง Agent จัดการข้อความเดียว (การตอบสนองหรือการเรียกใช้ฟังก์ชัน) สิ่งนี้ช่วยระบุสวิตช์ระหว่าง Agent
• {"response": Response} จะส่งคืนวัตถุ Response กลับในตอนท้ายของสตรีมด้วยการตอบสนองแบบรวม (เสร็จสมบูรณ์) เพื่อความสะดวก

การประเมินผล

การประเมินมีความสำคัญต่อโครงการใด ๆ และเราสนับสนุนให้นักพัฒนานำชุดประเมินของพวกเขามาทดสอบประสิทธิภาพของฝูง สำหรับการอ้างอิงเรามีตัวอย่างสำหรับวิธีการประเมินฝูงใน airline , weather_agent และ triage_agent Quickstart ตัวอย่าง ดูรายละเอียดเพิ่มเติม

เครื่องใช้

ใช้ run_demo_loop เพื่อทดสอบฝูงของคุณ! สิ่งนี้จะเรียกใช้ RELP บนบรรทัดคำสั่งของคุณ รองรับการสตรีม

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

ผู้สนับสนุนหลัก

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