Sửa lỗi RuntimeError: GroupChat select_speaker failed to resolve the next speaker's name trong AutoGen

Lỗi gặp phải

RuntimeError: GroupChat select_speaker failed to resolve the next speaker's name

Lỗi này xảy ra giữa chừng khi GroupChatManager của AutoGen không xác định được agent nào sẽ nói tiếp theo. LLM đáng lẽ phải trả về tên của một trong các agent đã đăng ký. Thay vào đó, nó trả về thứ gì đó không nhận dạng được — hoặc không trả về gì cả.

Nguyên nhân gốc rễ

Có nhiều nguyên nhân khác nhau gây ra lỗi này, và mỗi nguyên nhân cần cách xử lý riêng:

• LLM trả về tên không khớp với agent nào — model tự bịa ra tên, hoặc thêm định dạng như "Agent: Coder" thay vì chuỗi đơn giản "Coder".
• Tên agent chứa dấu cách hoặc ký tự đặc biệt — các tên như "Code Writer" hay "agent-1" làm rối cơ chế fuzzy matching mà AutoGen dùng để phân tích output của LLM.
• Đạt giới hạn token trong quá trình chọn speaker — prompt chọn lượt bị cắt ngắn, khiến model trả về phản hồi rỗng hoặc không đầy đủ.
• Model yếu chạy GroupChatManager — GPT-3.5 và hầu hết các LLM local thất bại với tác vụ này khá thường xuyên. Các model thuộc dòng GPT-4 xử lý ổn định hơn nhiều.
• Hàm speaker_selection_method tùy chỉnh ném exception — nếu bạn truyền vào một callable và nó bị lỗi, AutoGen sẽ bọc lỗi đó thành RuntimeError này.

Cách 1: Dùng tên agent đơn giản, một từ

Cách này giải quyết lỗi cho hầu hết mọi người. Đổi tên agent thành chuỗi chữ và số đơn giản. Không dấu cách. Không gạch nối. Không gạch dưới nếu có thể tránh được.

import autogen

coder = autogen.AssistantAgent(
    name="Coder",  # Tốt: đơn giản, một từ
    llm_config=llm_config,
)

reviewer = autogen.AssistantAgent(
    name="Reviewer",  # Tốt
    llm_config=llm_config,
)

# Ví dụ xấu:
# name="Code Writer"     → dấu cách làm hỏng matching
# name="code-reviewer"   → gạch nối gây nhầm lẫn cho LLM
# name="agent_1"         → gạch dưới đôi khi bị đọc nhầm thành dấu cách

Cách 2: Dùng model mạnh hơn cho GroupChatManager

Chọn speaker là một lời gọi LLM riêng biệt — manager không dùng chung model với các agent của bạn. Nếu model của manager yếu, hãy cấu hình riêng cho nó trỏ đến GPT-4o hoặc tương đương. Đặt temperature=0 cũng giúp ích: output xác định hơn đồng nghĩa ít tên bịa đặt hơn.

manager_llm_config = {
    "config_list": [{"model": "gpt-4o", "api_key": "..."}],
    "temperature": 0,
}

group_chat = autogen.GroupChat(
    agents=[user_proxy, coder, reviewer],
    messages=[],
    max_round=12,
)

manager = autogen.GroupChatManager(
    groupchat=group_chat,
    llm_config=manager_llm_config,  # config riêng, model mạnh hơn
)

Cách 3: Bỏ qua LLM bằng cách chọn lượt xác định

Không cần định tuyến động? Đừng tốn chi phí cho nó. Dùng "round_robin" hoặc một callable tùy chỉnh, và lời gọi chọn speaker sẽ không bao giờ xảy ra.

# Lựa chọn A: round_robin — các agent lần lượt theo thứ tự
group_chat = autogen.GroupChat(
    agents=[user_proxy, coder, reviewer],
    messages=[],
    max_round=10,
    speaker_selection_method="round_robin",
)

# Lựa chọn B: callable tùy chỉnh — kiểm soát hoàn toàn
def my_speaker_selector(last_speaker, groupchat):
    agents = groupchat.agents
    last_idx = agents.index(last_speaker)
    return agents[(last_idx + 1) % len(agents)]

group_chat = autogen.GroupChat(
    agents=[user_proxy, coder, reviewer],
    messages=[],
    max_round=10,
    speaker_selection_method=my_speaker_selector,
)

Cách 4: Tăng max_retries_for_selecting_speaker

AutoGen 0.2.x có tham số retry được thiết kế riêng cho chế độ lỗi này. Mặc định là 2 lần thử lại — thường không đủ khi model thỉnh thoảng bị trục trặc. Tăng lên 5 sẽ phục hồi hầu hết các lỗi thoáng qua mà không cần thay đổi gì khác.

group_chat = autogen.GroupChat(
    agents=[user_proxy, coder, reviewer],
    messages=[],
    max_round=10,
    max_retries_for_selecting_speaker=5,  # mặc định là 2
    speaker_selection_method="auto",
)

Cách 5: Xử lý tràn context window với LLM local

Đang dùng Ollama hay LM Studio? Prompt chọn speaker bao gồm toàn bộ lịch sử hội thoại. Đến vòng 8 hay 10, lịch sử đó có thể vượt quá context window 4K hoặc 8K. Model nhận input bị cắt ngắn và trả về kết quả vô nghĩa — hoặc không trả về gì.

Hai tùy chỉnh giúp được: giới hạn max_tokens cho phản hồi của speaker (chỉ cần một từ thôi), và giảm max_round để giữ lịch sử ngắn gọn.

llm_config = {
    "config_list": [{
        "model": "llama3",
        "base_url": "http://localhost:11434/v1",
        "api_key": "ollama",
    }],
    "max_tokens": 512,   # phản hồi của speaker chỉ là một tên
    "temperature": 0,
}

group_chat = autogen.GroupChat(
    agents=[user_proxy, coder, reviewer],
    messages=[],
    max_round=6,  # ít vòng hơn = lịch sử context ngắn hơn
)

Cách 6: Đã migrate sang autogen-agentchat 0.4.x?

Gói 0.4.x đã viết lại hoàn toàn GroupChat API từ đầu. Các pattern GroupChatManager cũ không còn tồn tại nữa. Dùng RoundRobinGroupChat cho thứ tự xác định, hoặc SelectorGroupChat khi cần định tuyến dựa trên LLM.

from autogen_agentchat.teams import RoundRobinGroupChat, SelectorGroupChat
from autogen_agentchat.agents import AssistantAgent
from autogen_ext.models.openai import OpenAIChatCompletionClient

model_client = OpenAIChatCompletionClient(model="gpt-4o")

coder = AssistantAgent(name="Coder", model_client=model_client)
reviewer = AssistantAgent(name="Reviewer", model_client=model_client)

# Xoay vòng xác định
team = RoundRobinGroupChat([coder, reviewer], max_turns=10)

# Chọn lựa dựa trên LLM — dùng model có năng lực ở đây
team = SelectorGroupChat(
    [coder, reviewer],
    model_client=model_client,
)

Kiểm tra

Chạy một cuộc trò chuyện hai agent tối giản với tác vụ đơn giản. Nếu hoàn thành mà không có lỗi, nghĩa là đã sửa thành công.

import autogen

llm_config = {"config_list": [{"model": "gpt-4o", "api_key": "YOUR_KEY"}], "temperature": 0}

user = autogen.UserProxyAgent(name="User", human_input_mode="NEVER", max_consecutive_auto_reply=1)
coder = autogen.AssistantAgent(name="Coder", llm_config=llm_config)

gc = autogen.GroupChat(agents=[user, coder], messages=[], max_round=3)
mgr = autogen.GroupChatManager(groupchat=gc, llm_config=llm_config)

user.initiate_chat(mgr, message="Write a hello world in Python")
# Nên hoàn thành mà không có RuntimeError

Xem log sau khi chạy. Cảnh báo select_speaker là bình thường — chúng có nghĩa là đã thử lại và thành công. Lỗi thực sự có nghĩa là vấn đề chưa được khắc phục.

Phòng ngừa

• Dùng tên agent CamelCase một từ: Planner, Coder, Critic. Tên nhàm chán không gây ra bug.
• Đặt temperature=0 trong config LLM của manager. Output xác định = ít tên speaker bịa đặt hơn.
• Với bất kỳ thứ gì chạy trên production, hãy dùng round_robin hoặc callable tùy chỉnh. Định tuyến dựa trên LLM ("auto") thêm một điểm có thể thất bại và rất khó debug lúc 2 giờ sáng.
• Kiểm tra speaker selection rõ ràng trước khi xây dựng pipeline phức tạp với model local — hầu hết các model dưới 7B thất bại với tác vụ này ở độ dài hội thoại thực tế.
• Ghim phiên bản pyautogen trong requirements.txt. Việc migration từ 0.2.x → 0.4.x đã phá vỡ toàn bộ GroupChat API, và điều đó có thể xảy ra lại.