Sửa lỗi LangChain "Agent stopped due to iteration limit"

Chuyện gì đã xảy ra

Bạn chạy một LangChain agent và nó dừng giữa chừng, trả về thông báo kiểu như:

Agent stopped due to iteration limit or time limit.

Không có câu trả lời cuối cùng. Chỉ là kết quả dở dang — hoặc không có gì cả. LangChain giới hạn agent ở 15 vòng lặp theo mặc định. Đây là cơ chế bảo vệ, không phải lỗi. Nếu không có giới hạn này, một agent bị kẹt có thể chạy vô tận và tiêu tốn hàng trăm lần gọi API.

Giới hạn này được kích hoạt vì một số nguyên nhân:

• Tác vụ thực sự cần nhiều lần gọi tool hơn mức mặc định cho phép.
• Agent đang bị kẹt trong vòng lặp — gọi đi gọi lại cùng một tool mà không tiến triển gì.
• LLM liên tục sinh ra các bước trung gian thay vì đưa ra câu trả lời cuối cùng.
• Một tool cứ trả về kết quả mà agent không biết cách xử lý.

Chẩn đoán nhanh

Trước khi chỉnh bất kỳ cấu hình nào, hãy bật chế độ verbose để xem agent thực sự đang làm gì ở mỗi vòng lặp:

agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    verbose=True,   #  str:
    return f"Parsing failed: {str(error)[:100]}. Try a different approach."

agent_executor = AgentExecutor(
    agent=agent,
    tools=tools,
    max_iterations=25,
    handle_parsing_errors=handle_error
)

Cách sửa 4: Giải quyết gốc rễ vòng lặp — cải thiện prompt

Tăng giới hạn chỉ trì hoãn vấn đề nếu agent cứ lặp vào một tool cụ thể. Chín trong mười trường hợp, nguyên nhân gốc rễ là system prompt không nói cho agent biết khi nào thì dừng. Hãy thêm các quy tắc dừng rõ ràng:

from langchain.agents import create_react_agent
from langchain_core.prompts import PromptTemplate

prompt = PromptTemplate.from_template("""
You are a helpful assistant. Answer the question using the tools available.

IMPORTANT:
- If you've used a tool and have enough information to answer, stop and give the Final Answer immediately.
- Do NOT call the same tool twice with the same input.
- If a tool returns an error twice, stop and explain what you found so far.

{tools}

Question: {input}
{agent_scratchpad}
""")

agent = create_react_agent(llm=llm, tools=tools, prompt=prompt)

Cách sửa 5: LangGraph agents (0.3.x trở lên)

Đã chuyển sang LangGraph? Giới hạn vòng lặp hoạt động khác ở đó. Thay vì max_iterations, bạn đặt recursion_limit trong invoke config:

from langgraph.prebuilt import create_react_agent

agent = create_react_agent(model=llm, tools=tools)

# Truyền recursion_limit trong config khi invoke
result = agent.invoke(
    {"messages": [("user", "your question here")]},
    config={"recursion_limit": 50}
)

LangGraph cũng cho phép bạn stream trạng thái đồ thị để debug vòng lặp từng bước:

for step in agent.stream(
    {"messages": [("user", "your question here")]},
    config={"recursion_limit": 50}
):
    print(step)
    print("---")

Xác nhận bản sửa hoạt động

Chạy agent với bản sửa đã áp dụng và xác nhận nó đạt được câu trả lời cuối cùng thực sự:

result = agent_executor.invoke({"input": "your test question"})

# Kiểm tra bạn nhận được output thực, không phải kết quả rỗng hay lỗi
print(result["output"])
assert "Agent stopped due to iteration limit" not in str(result)
assert len(result["output"]) > 0

Với verbose=True, bạn sẽ thấy Final Answer: xuất hiện trước khi chạm giới hạn vòng lặp. Vẫn còn vòng lặp? Hãy xem lại output của các tool và siết chặt hướng dẫn trong prompt.

Tóm tắt các cách sửa

• Tác vụ dài hợp lệ: tăng max_iterations, thêm max_execution_time.
• Output xấu khi dừng: đặt early_stopping_method="generate".
• Lỗi phân tích gây thử lại liên tục: bật handle_parsing_errors=True.
• Agent lặp vào cùng một tool: sửa system prompt với các quy tắc dừng rõ ràng.
• LangGraph agents: dùng recursion_limit trong invoke config.