Obsługa awarii i pętli agentów
Dodaj limity czasu, maksymalną liczbę iteracji oraz komunikaty odzyskiwania po błędach, aby zapobiec nieskończonemu zapętlaniu się agentów lub wielokrotnemu wywoływaniu niedziałających narzędzi.
Obsługa awarii i pętli agentów to bezpłatna lekcja AI Engineering Academy na CoddyKit. To lekcja 4 z 4. Możesz przeczytać całą lekcję poniżej za darmo — a potem ćwiczyć ją interaktywnie w przeglądarce z wbudowanym edytorem kodu i tutorem AI dostępnym 24/7. To część ścieżki edukacyjnej AI Engineering Academy, a Twój postęp synchronizuje się między webem a aplikacją CoddyKit. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.
Dlaczego agenci zawodzą i zapętlają się
Agenci mogą utknąć w pętlach błędów z kilku powodów: uszkodzone narzędzie zwraca błąd, z którego agent nie potrafi wyjść, model wielokrotnie generuje niepoprawną składnię akcji, wykonanie zadania jest niemożliwe przy dostępnych narzędziach albo agent wciąż wywołuje to samo narzędzie z niewielkimi zmianami, licząc na inny wynik. Bez zabezpieczeń zużywa to budżet API i nigdy nie prowadzi do rozwiązania.
Limity maksymalnej liczby iteracji
Najprostszym zabezpieczeniem jest twardy limit liczby cykli Thought/Action/Observation. LangChainowy AgentExecutor przyjmuje parametr max_iterations. Po osiągnięciu limitu executor zatrzymuje pętlę i zwraca komunikat informujący, że agent nie mógł ukończyć zadania.
from langchain.agents import AgentExecutor
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
max_iterations=10, # Hard stop after 10 steps
max_execution_time=30.0, # Also stop after 30 wall-clock seconds
early_stopping_method='generate', # Ask the model for a partial answer at the limit
verbose=True
)Wczesne zatrzymanie: wymuszenie końcowej odpowiedzi
Gdy agent osiągnie limit iteracji, early_stopping_method='generate' po raz ostatni wywołuje model z komunikatem: 'Osiągnięto limit kroków. Na podstawie dotychczasowych informacji udziel najlepszej końcowej odpowiedzi.' Jest to lepsze niż zwrócenie pustej odpowiedzi lub awaria, ponieważ użytkownik otrzymuje coś użytecznego.
# The 'generate' early_stopping_method adds this system instruction
# when max_iterations is reached:
#
# 'You have {N} steps remaining but the task is not complete.
# Give your best final answer based on the information gathered so far.'
#
# Contrast with 'force' which abruptly terminates without generating an answer.
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
max_iterations=7,
early_stopping_method='generate'
)Kontrolowanie błędów analizy składni
Gdy model wygeneruje dane wyjściowe, które nie pasują do formatu Thought/Action — na przykład pominie słowo kluczowe akcji, użyje niewłaściwej nazwy narzędzia lub zwróci zwykły tekst — agent zgłasza wyjątek OutputParserException. Ustaw handle_parsing_errors=True, aby przekazać błąd z powrotem jako obserwację i umożliwić modelowi samodzielną korektę.
agent_executor = AgentExecutor(
agent=agent,
tools=tools,
handle_parsing_errors=True,
# Custom error message fed back to the model:
# handle_parsing_errors='Please format your response as Thought/Action/Action Input.'
)
# When a parse error occurs, the executor automatically adds:
# Observation: Could not parse LLM output. Please follow the format:
# Thought: ...
# Action: tool_name
# Action Input: ...Wykrywanie i przerywanie powtarzających się pętli
Typowy wzorzec pętli wygląda następująco: agent wywołuje search('same query') trzy razy z rzędu i za każdym razem otrzymuje ten sam bezużyteczny wynik. Zaimplementuj wykrywanie pętli, śledząc ostatnie pary (narzędzie, dane wejściowe). Jeśli ta sama kombinacja powtórzy się więcej niż dwa razy, wstrzyknij obserwację sugerującą inne podejście.
from collections import Counter
class LoopDetector:
def __init__(self, max_repeats: int = 2):
self.max_repeats = max_repeats
self.call_counts = Counter()
def check(self, tool_name: str, tool_input: str) -> bool:
key = f'{tool_name}:{tool_input}'
self.call_counts[key] += 1
if self.call_counts[key] > self.max_repeats:
return True # Loop detected
return False
def get_warning(self) -> str:
return ('You have called this tool with the same input multiple times. '
'Try a different approach, different search terms, or a different tool.')Obsługa błędów na poziomie narzędzi
Solidni agenci wymagają solidnych narzędzi. Każde narzędzie powinno przechwytywać własne wyjątki i zwracać uporządkowane komunikaty o błędach zamiast zgłaszać wyjątki języka Python. Uwzględnij typ błędu i sugestię dla agenta, aby wiedział, czy ponowić próbę, zmienić podejście, czy eskalować problem.
from langchain_core.tools import tool
import requests
@tool
def get_company_data(company_name: str) -> str:
'''Retrieve company information from the business database.
Input: company name as a string.
'''
try:
resp = requests.get(
f'https://api.example.com/companies/{company_name}',
timeout=5
)
if resp.status_code == 404:
return f'No company found with name "{company_name}". Try the exact legal name or ticker symbol.'
if resp.status_code == 429:
return 'Rate limit exceeded. Wait 60 seconds before trying again.'
resp.raise_for_status()
return resp.json().get('summary', 'No summary available.')
except requests.Timeout:
return 'The database is not responding. Try searching the web instead.'Wykładnicze opóźnienie przy awariach API
Gdy narzędzia wywołują zewnętrzne API, przejściowe awarie są częste. Dodaj logikę ponawiania prób z wykładniczym opóźnieniem wewnątrz funkcji narzędzia — ponawiaj próbę maksymalnie 3 razy, wydłużając przerwy między kolejnymi próbami. Pozwala to w przejrzysty sposób obsługiwać limity szybkości i krótkotrwałe awarie, bez konieczności informowania agenta o ponawianiu prób.
import time
import requests
from langchain_core.tools import tool
@tool
def reliable_search(query: str) -> str:
'''Search with automatic retry on failure. Input: search query string.'''
max_retries = 3
for attempt in range(max_retries):
try:
resp = requests.get(
'https://api.duckduckgo.com/',
params={'q': query, 'format': 'json'},
timeout=10
)
resp.raise_for_status()
data = resp.json()
return data.get('AbstractText', 'No results found.')
except requests.RequestException as e:
if attempt < max_retries - 1:
wait = 2 ** attempt # 1s, 2s, 4s
time.sleep(wait)
else:
return f'Search failed after {max_retries} attempts: {str(e)}'Limity czasu na poziomie agenta
Ponawianie prób przez poszczególne narzędzia jest bardzo przydatne, ale potrzebny jest także łączny limit czasu rzeczywistego dla całego uruchomienia agenta. Jeśli zadanie trwa dłużej, niż pozwala na to umowa SLA (na przykład 30 sekund), zatrzymaj pętlę i zwróć odpowiedź z kontrolowanym ograniczeniem funkcjonalności. Parametr max_execution_time w LangChain obsługuje to na poziomie executora.
import asyncio
async def run_with_timeout(user_input: str, timeout_seconds: float = 30.0) -> str:
try:
result = await asyncio.wait_for(
agent_executor.ainvoke({'input': user_input}),
timeout=timeout_seconds
)
return result['output']
except asyncio.TimeoutError:
return ('I am taking longer than expected to answer this question. '
'Please try again with a simpler question, or check back later.')Rejestrowanie awarii do analizy
Każda awaria agenta dostarcza danych. Zapisuj pełny ślad — dane wejściowe użytkownika, wszystkie kroki pośrednie, przyczynę awarii i liczbę użytych iteracji — w bazie danych lub na platformie obserwowalności. Analiza wzorców awarii ujawnia, które narzędzia są zawodne, jakich typów pytań agent nie potrafi obsłużyć oraz które pętle występują najczęściej.
import logging
import json
logger = logging.getLogger('agent')
def run_and_log(user_input: str) -> str:
try:
result = agent_executor.invoke(
{'input': user_input},
return_intermediate_steps=True
)
if not result.get('output'):
logger.warning('Agent returned empty output', extra={
'input': user_input,
'steps': len(result.get('intermediate_steps', []))
})
return result['output']
except Exception as e:
logger.error('Agent failed with exception', extra={
'input': user_input,
'error': str(e),
'error_type': type(e).__name__
})
return 'I encountered an error. Please try rephrasing your question.'Wstrzykiwanie wskazówek dotyczących odzyskiwania do promptu
Po wykryciu wzorca awarii można dynamicznie wstrzyknąć instrukcje dotyczące odzyskiwania do kolejnego promptu agenta. Jeśli na przykład narzędzie wyszukiwania uległo awarii, dodaj wskazówkę taką jak: 'Narzędzie wyszukiwania w sieci jest obecnie zawodne. W przypadku tego zapytania preferuj narzędzie bazy wiedzy.' W ten sposób agent zostanie skierowany ku działającemu rozwiązaniu bez zakodowanej na stałe logiki awaryjnej.
Testowanie scenariuszy awarii
Utwórz jawny zestaw testów dla scenariuszy awarii. Sprawdź, co się dzieje, gdy: wszystkie narzędzia zwracają błędy, model osiąga max_iterations, dane wejściowe nie zawierają pytania, na które można odpowiedzieć, oraz model wywołuje nieistniejące narzędzie. Agent powinien zawsze zwracać sensowny komunikat i nigdy nie powodować awarii aplikacji, niezależnie od tego, jak wrogi jest dany scenariusz.
Szybkie sprawdzenie
Sprawdź swoją wiedzę na temat obsługi awarii agentów i zapobiegania pętlom.
Podsumowanie lekcji
W tej lekcji nauczyłeś się, że: max_iterations i max_execution_time ustanawiają twarde limity czasu działania agenta, handle_parsing_errors przekazuje błędy formatu z powrotem do modelu w celu samodzielnej korekty, a narzędzia powinny przechwytywać wyjątki i zwracać opisowe ciągi znaków z komunikatami o błędach, zamiast zgłaszać wyjątki. Następnie poznamy natywną funkcję wywoływania funkcji OpenAI do strukturalnej integracji narzędzi.
Ucz się Python dzięki korepetycjom AI — za darmo
Pisz i uruchamiaj kod w przeglądarce, otrzymuj natychmiastową pomoc od korepetytora AI dostępnego 24/7 i kontynuuj naukę w sieci lub w aplikacji.
- Kursy
- 30
- Lekcje
- 120
Często zadawane pytania
Czy lekcja „Obsługa awarii i pętli agentów” jest bezpłatna?
Tak — pełny tekst „Obsługa awarii i pętli agentów” jest dostępny za darmo tutaj w sieci. Aby ćwiczyć ją interaktywnie (wbudowany edytor kodu i tutor AI dostępny 24/7) i odblokować resztę kursu AI Engineering Academy, przejdź na CoddyKit PRO. Kurs AI Engineering Academy zawiera 4 lekcji w sumie.
Co nauczysz się w „Obsługa awarii i pętli agentów”?
Dodaj limity czasu, maksymalną liczbę iteracji oraz komunikaty odzyskiwania po błędach, aby zapobiec nieskończonemu zapętlaniu się agentów lub wielokrotnemu wywoływaniu niedziałających narzędzi. Ćwiczysz AI Engineering Academy z praktycznym kodem, który uruchamiasz bezpośrednio w przeglądarce, a tutor AI dostępny 24/7 odpowiada na Twoje pytania podczas pracy nad lekcją.
Czy potrzebuję doświadczenia, aby zacząć AI Engineering Academy?
Nie wymagamy żadnego doświadczenia. AI Engineering Academy w CoddyKit jest strukturyzowany dla początkujących i zaawansowanych użytkowników, więc możesz zacząć tutaj lub od początku i uczyć się w swoim tempie. To lekcja 4 z 4.
Ile czasu zajmuje lekcja „Obsługa awarii i pętli agentów”?
Większość lekcji CoddyKit trwa około 5–10 minut. Każda lekcja to mały, interaktywny krok, dzięki czemu robisz systematyczne postępy i zawsze wracasz dokładnie do tego samego miejsca — na webie i w aplikacji.
Czy mogę pisać i uruchamiać kod w tej lekcji AI Engineering Academy?
Tak. Każda lekcja AI Engineering Academy zawiera wbudowany edytor kodu, więc piszesz i uruchamiasz prawdziwy kod bezpośrednio w przeglądarce i od razu otrzymujesz sprzężenie zwrotne od AI — bez konfiguracji na komputerze.
Wszystkie lekcje w tym kursie
- Framework ReAct: myślenie, działanie, obserwacja
- Definiowanie narzędzi dla agenta
- Tworzenie agenta ReAct za pomocą LangChain
- Obsługa awarii i pętli agentów