---

一、關(guān)于 Swarm（實驗性、教育性）

• github : https://github.com/openai/swarm

---

Swarm 是探索人體工程學(xué)、輕量級 多代理編排的 教育框架。(An educational framework exploring ergonomic, lightweight multi-agent orchestration.)

Swarm 專注于使代理協(xié)調(diào)和 執(zhí)行輕量級、高度可控且易于測試。

它通過兩個基本抽象來實現(xiàn)這一點：Agent和切換。Agent包含instructions和tools，并且可以 隨時選擇將對話 交給另一個Agent。

這些原語功能強大，足以表達工具和代理網(wǎng)絡(luò)之間的豐富動態(tài)，允許您構(gòu)建可擴展的真實解決方案，同時避免陡峭的學(xué)習(xí)曲線。

注：群代理與助理應(yīng)用編程接口中的助理無關(guān)。為了方便起見，它們的命名類似，但在其他方面完全不相關(guān)。群完全由聊天完成應(yīng)用編程接口提供支持，因此在調(diào)用之間是無狀態(tài)的。

---

警告：

Swarm目前是一個實驗性的示例框架，旨在探索多智能體系統(tǒng)的人體工程學(xué)界面。它不打算在生產(chǎn)中使用，因此沒有官方支持。（這也意味著我們不會審查PR或問題！）

Swarm的主要目標(biāo)是展示編排代理：切換和例程食譜中探索的切換和例程模式。它不意味著是一個獨立的庫，主要用于教育目的。

---

為什么選擇蜂群

Swarm 通過設(shè)計探索輕量級、可擴展和高度可定制的模式。類似于Swarm的方法 最適合處理難以編碼為單個提示的大量獨立功能和指令的情況。

對于尋找完全托管線程和內(nèi)置內(nèi)存管理和檢索的開發(fā)人員來說，助理應(yīng)用編程接口是一個很好的選擇。然而，對于想了解多代理編排的開發(fā)人員來說，Swarm是一個教育資源。Swarm（幾乎）完全在客戶端上運行，并且很像聊天完成應(yīng)用編程接口，不存儲調(diào)用之間的狀態(tài)。

---

文檔

---

二、安裝使用

安裝

需要Python 3.10+

pip install git+ssh://git@github.com/openai/swarm.git

---

或者

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

---

基本用法

如果你想使用 Qwen 等 API 替代默認(rèn)的 OpenAI，可參考文章：https://ezcode.blog.csdn.net/article/details/143300605

from swarm import Swarm, Agentclient = Swarm()def transfer_to_agent_b():return agent_bagent_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?

---

其它示例

看看/examples的靈感！在自述文件中了解更多關(guān)于每一個的信息。

• basic：簡單的基礎(chǔ)示例，如設(shè)置、函數(shù)調(diào)用、切換和上下文變量
• triage_agent：設(shè)置基本分類步驟以交給正確代理的簡單示例
• weather_agent：函數(shù)調(diào)用的簡單示例
• airline：用于在航空公司上下文中處理不同客戶服務(wù)請求的多代理設(shè)置。
• support_bot：一個客戶服務(wù)機器人，包括一個用戶交互界面代理和一個帶有多個工具的幫助中心代理
• personal_shopper：可以幫助進行銷售和退款訂單的個人購物代理

---

三、Running Swarm

首先實例化一個Swarm客戶端（它在內(nèi)部只實例化一個OpenAI客戶端）。

from swarm import Swarmclient = Swarm()

---

client.run()

Swarm的run()函數(shù)類似于Chat Completions API中的chat.completions.create()函數(shù) —— 它接受messages并返回messages，并且在調(diào)用之間不保存任何狀態(tài)。

然而，重要的是，它還處理代理 函數(shù)的執(zhí)行、移交、上下文變量引用，并且可以在返回給用戶之前 進行多次輪換。

Swarm的client.run()的核心實現(xiàn)了以下循環(huán)：

1. 從當(dāng)前代理處獲得完成
2. 執(zhí)行工具調(diào)用并附加結(jié)果
3. 必要時切換代理
4. 如有必要，更新上下文變量
5. 如果沒有新的函數(shù)調(diào)用，返回

---

Arguments

參數(shù)	類型	描述	默認(rèn)
agent	Agent	要調(diào)用的（初始）代理。	（必需）
messages	List	消息對象列表，與 Chat Completions messages	（必需）
context_variables	dict	附加上下文變量的字典，可用于函數(shù)和代理指令	{}
max_turns	int	允許的最大會話輪流次數(shù)	float("inf")
model_override	str	一個可選字符串，用于覆蓋代理正在使用的模型	None
execute_tools	bool	如果False，中斷執(zhí)行并立即返回tool_calls消息，當(dāng)代理嘗試調(diào)用函數(shù)時	True
stream	bool	如果True，啟用流響應(yīng)	False
debug	bool	如果True，啟用調(diào)試日志	False

---

一旦client.run() 完成（在可能多次調(diào)用代理和工具之后），它將返回一個Response，其中包含所有相關(guān)的更新狀態(tài)。

具體來說，新messages、最后一個要調(diào)用的Agent和最新的context_variables。

您可以將這些值（加上新用戶消息）傳遞到client.run()的下一次執(zhí)行中，以繼續(xù)它中斷的交互——很像chat.completions.create()。

（run_demo_loop函數(shù)在/swarm/repl/repl.py.）中實現(xiàn)完整執(zhí)行循環(huán)的示例

---

Response字段

字段	類型	描述
messages	List	對話期間生成的消息對象列表。非常類似于聊天完成messages，但有一個sender字段，指示消息來自哪個Agent。
agent	Agent	處理消息的最后一個代理。
context_variables	dict	與輸入變量相同，加上任何更改。

---

四、Agent

一個Agent只是用一組functions封裝了一組instructions（加上下面的一些附加設(shè)置），并且能夠?qū)?zhí)行交給另一個Agent。

雖然很容易將Agent擬人化為“做X的人”，但它也可以用來表示由一組instructions和functions定義的非常具體的工作流或步驟（例如一組步驟、復(fù)雜的檢索、單步數(shù)據(jù)轉(zhuǎn)換等）。

這允許Agent被組成一個由“代理”、“工作流”和“任務(wù)”組成的網(wǎng)絡(luò)，所有這些都由同一個原語表示。

---

Fields Agent

字段	類型	描述	默認(rèn)
name	str	代理的名稱。	"Agent"
model	str	代理要使用的模型。	"gpt-4o"
instructions	str或func() -> str	代理的說明，可以是字符串或返回字符串的可調(diào)用對象。	"You are a helpful agent."
functions	List	代理可以調(diào)用的函數(shù)列表。	[]
tool_choice	str	代理的工具選擇（如果有）。	None

---

指令

Agent instructions直接轉(zhuǎn)換為對話的system提示（作為第一條消息），任何給定時間只有活動Agent的instructions會出現(xiàn)（例如，如果有Agent切換，system提示會改變，但聊天記錄不會。）

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

---

這些instructions可以是常規(guī)str，也可以是返回str的函數(shù)。

該函數(shù)可以選擇接收一個context_variables參數(shù)，該參數(shù)將由傳遞給client.run()的context_variables填充。

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?

---

函數(shù)

• SwarmAgent可以直接調(diào)用python函數(shù)。
• 函數(shù)通常應(yīng)該返回一個str（值將被嘗試轉(zhuǎn)換為str）。
• 如果函數(shù)返回一個Agent，執(zhí)行將轉(zhuǎn)移到該Agent。
• 如果一個函數(shù)定義了一個context_variables參數(shù)，它將由傳遞給client.run()的context_variables填充。

---

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函數(shù)調(diào)用出現(xiàn)錯誤（缺少函數(shù)、錯誤參數(shù)、錯誤），則會將錯誤響應(yīng)附加到聊天中，以便Agent可以正?；謴?fù)。
• 如果Agent調(diào)用多個函數(shù)，它們將按該順序執(zhí)行。

---

切換和更新上下文變量

一個Agent可以通過在Agent中返回另一個function來傳遞。

sales_agent = Agent(name="Sales Agent")def transfer_to_sales():return sales_agentagent = 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。這也可以包含一個value和一個agent，以防您希望單個函數(shù)返回一個值、更新代理和更新上下文變量（或三個變量的任何子集）。

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調(diào)用多個函數(shù)來移交給Agent，則僅使用最后一個移交函數(shù)。

---

函數(shù)模式

Swarm自動將函數(shù)轉(zhuǎn)換為JSON模式，并將其傳遞給聊天完成tools。

• 文檔字符串被轉(zhuǎn)換成函數(shù)description。
• 沒有默認(rèn)值的參數(shù)設(shè)置為required。
• 類型提示映射到參數(shù)的type（默認(rèn)為string）。
• 不明確支持每個參數(shù)的描述，但如果只是在文檔字符串中添加，則應(yīng)該類似地工作。（將來可能會添加文檔字符串參數(shù)解析。）

---

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.\n\nArgs:\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流相同的事件。請參見/swarm/repl/repl.py中的process_and_print_streaming_response作為示例。

添加了兩種新的事件類型：

• {"delim":"start"}和{"delim":"end"}，用于每次Agent處理單個消息（響應(yīng)或函數(shù)調(diào)用）時發(fā)出信號。這有助于識別Agent之間的切換。
• {"response": Response}將在流的末尾返回一個Response對象，其中包含聚合的（完整的）響應(yīng)，以方便起見。

---

評估

評估對任何項目都是至關(guān)重要的，我們鼓勵開發(fā)人員帶上他們自己的eval套件來測試他們的集群的性能。作為參考，我們有一些關(guān)于如何在airline、weather_agent和triage_agent快速入門示例中使用eval swarm的示例。有關(guān)更多詳細(xì)信息，請參閱READMEs。

---

工具

使用該run_demo_loop測試您的集群！這將在您的命令行上運行REPL。支持流式傳輸。

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

---

2024-10-28(一)