Najlepsze praktyki i kolejne kroki
Na tej stronie
Co już omówiliśmy
Przeszedłeś przez całe API Mistral Agents. Zróbmy krótkie podsumowanie przed przejściem do praktyk produkcyjnych, ponieważ każda część tego kursu bazuje na poprzedniej.
Pierwsze trzy lekcje położyły fundamenty: agent AI to autonomiczny system z pętlą percepcja-działanie; API opiera się na trzech obiektach — Agent, Conversation i Entry; a tym, co odróżnia agenta od chatbota, jest trwałość, narzędzia i przekazywanie zadań (handoffs). Lekcje od 4 do 7 uczyniły te obiekty użytecznymi: tworzenie i konfigurowanie agentów za pomocą client.beta.agents.create(), utrzymywanie trwałych konwersacji dzięki conversations.start() i conversations.append(), oraz używanie trybu bezpośredniego bez agenta podczas prototypowania, gdy trwałość nie wnosi wartości.
Lekcje od 8 do 11 dodały nowe możliwości. web_search daje dostęp do aktualnych informacji z automatycznymi cytowaniami; code_interpreter uruchamia Pythona w piaskownicy, dając agentowi dokładne wyniki tam, gdzie sam model jedynie by przybliżał; image_generation tworzy wizualizacje na podstawie promptów tekstowych; document_library wprowadza zintegrowane RAG do Twoich własnych dokumentów. Lekcje od 12 do 16 pokazały następnie współpracę wielu agentów: przekazywanie zadań (handoffs) przenosi kontrolę z jednego agenta na drugiego, architektura referencyjna łączy centralny router ze specjalistami, tryb serwera automatyzuje procesy, podczas gdy tryb klienta pozostawia Cię w pętli decyzyjnej, a nieograniczone łańcuchowanie dzieli się na wzorce liniowe, gwiaździste i hybrydowe. Na koniec lekcja 17 spięła całość za pomocą barier ochronnych (guardrails), zasady najmniejszych uprawnień oraz moderacji po stronie nadawcy (upstream moderation).
Projektowanie agentów, które się sprawdzają
Jedno zdanie streszcza cały ten kurs: jeden agent, jedna odpowiedzialność, jeden opis mówiący, kiedy go wywołać. Poniższe zestawienie czyni tę różnicę namacalną.
# DOBRZE — wyspecjalizowany agent z precyzyjnym opisem
agent = client.beta.agents.create(
model="mistral-large-latest",
name="invoice-processor",
description="Processes invoices: extracts amounts, dates, vendors.",
instructions="Extract invoice information into structured JSON.",
tools=[{"type": "document_library", "library_ids": [invoices_lib.id]}]
)
# ŹLE — generyczny, niejasny agent
agent = client.beta.agents.create(
model="mistral-large-latest",
name="helper",
description="A helpful agent.",
tools=[{"type": "web_search"}, {"type": "code_interpreter"}, {"type": "image_generation"}]
)
Drugi agent zawiedzie na dwa sposoby jednocześnie. Żaden router nie będzie wiedział, kiedy przekazać mu żądanie, ponieważ „pomocny agent“ nie opisuje żadnej konkretnej sytuacji. A gdy już zostanie wywołany, jego trzy narzędzia pozwalają mu szukać w sieci czegoś, co powinien był obliczyć, lub ilustrować coś, o co proszono go do analizy.
Obsługa błędów
Połączenia sieciowe wcześniej czy później zawodzą. Ponowienie próby z wykładniczym opóźnieniem (exponential backoff) pochłania chwilowe incydenty, nie zamieniając momentalnego spowolnienia w widoczną awarię.
import time
def safe_conversation(agent_id, query, max_retries=3):
"""Konwersacja z obsługą błędów i ponawianiem."""
for attempt in range(max_retries):
try:
response = client.beta.conversations.start(
agent_id=agent_id,
inputs=query
)
return response
except Exception as e:
if attempt == max_retries - 1:
raise
time.sleep(2 ** attempt) # Wykładnicze opóźnienie
return None
Wykładnicze opóźnienie — jedna sekunda, potem dwie, potem cztery — odróżnia kulturalne ponowienie próby od „bombardowania“ usługi, która już ma problemy. Zauważ też, że ostatnia próba ponownie zgłasza wyjątek zamiast zwracać None: wywołujący kod musi wiedzieć, że operacja się nie powiodła.
Widoczność działania
W środowisku produkcyjnym wieloagentowy przepływ pracy, którego nie możesz obserwować, staje się niemożliwy do debugowania. Tryb klienta daje Ci dokładnie te punkty zaczepienia, których potrzebujesz.
import logging
import time
logger = logging.getLogger("agents")
def monitored_conversation(agent_id, query):
"""Konwersacja z monitorowaniem."""
start = time.time()
response = client.beta.conversations.start(
agent_id=agent_id,
inputs=query,
handoff_execution="client"
)
handoff_count = 0
tool_count = 0
for entry in response.outputs:
if entry.type == "agent.handoff":
handoff_count += 1
logger.info(f"Handoff #{handoff_count}: → {entry.next_agent_id}")
elif entry.type == "tool.execution":
tool_count += 1
logger.info(f"Tool #{tool_count}: {entry.tool_name}")
duration = time.time() - start
logger.info(f"Finished in {duration:.1f}s — {handoff_count} handoffs, {tool_count} tools")
return response
Te dwa liczniki są warte więcej, niż sugeruje ich prostota: dryf średniej liczby przekazań (handoffs) sygnalizuje wahający się router; skok liczby wywołań narzędzi wskazuje na kosztowne zapytania.
Kontrola kosztów sprowadza się zatem do konkretnych decyzji. Monitoruj liczbę tokenów na konwersację, ponieważ to jest rzeczywista jednostka rozliczeniowa. Używaj mistral-medium-latest wszędzie tam, gdzie mistral-large-latest nic nie wnosi — pierwszy poziom wsparcia jest tego podręcznikowym przykładem. Ogranicz max_tokens w completion_args, aby uniknąć nieskończonych odpowiedzi na proste pytania, i wyłącz przechowywanie za pomocą store=False, gdy trwałość nie jest wymagana.
Testowanie routingu
Testuj system wieloagentowy jak każdą centralę: podawaj przypadki, co do których znasz oczekiwane miejsce docelowe, i sprawdzaj, gdzie trafią.
def test_agent_routing():
"""Weryfikuje, czy router poprawnie dystrybuuje żądania."""
test_cases = [
("What is the price of Bitcoin?", "web-search-agent"),
("Calculate 25 * 48", "calculator-agent"),
("Summarize this document", "doc-agent"),
]
for query, expected_agent_name in test_cases:
response = client.beta.conversations.start(
agent_id=router.id,
inputs=query,
handoff_execution="client"
)
for entry in response.outputs:
if entry.type == "agent.handoff":
target = client.beta.agents.get(agent_id=entry.next_agent_id)
assert target.name == expected_agent_name, \
f"Incorrect routing for '{ query}': {target.name} instead of {expected_agent_name}"
Buduj ten zestaw testów z czasem: każde źle skierowane żądanie, które wychwycisz w produkcji, staje się kolejną linią w test_cases, i będziesz wiedział, że przepisanie opisu naprawia konkretny przypadek, nie psując innego.
Architektura referencyjna
Dla projektu produkcyjnego oto zalecana architektura:
Application
│
▼
Moderator Agent (filters requests)
│
▼
Router Agent (distributes to specialists)
├── Search Agent (web_search)
├── Analysis Agent (code_interpreter)
├── Documents Agent (document_library)
└── Creation Agent (image_generation)
│
▼
Logging + Monitoring + Alerting
Łączy ona wszystko, o czym była mowa w tym kursie: moderator filtruje przed jakimkolwiek wykonaniem, router kieruje, nigdy sam nie odpowiadając, każdy specjalista posiada jedno narzędzie i jedną odpowiedzialność, a obserwacja otacza cały system.
Gdzie dalej
Cztery kierunki rozszerzają to, co możesz teraz zrobić. Function calling pozwala budować własne, niestandardowe narzędzia wykraczające poza te wbudowane: wywołanie biznesowego API, zapytanie do bazy danych, uruchomienie usługi wewnętrznej. MCP Servers integrują Model Context Protocol, który standaryzuje sposób udostępniania narzędzi. Structured outputs wymuszają odpowiedzi zgodne ze schematem JSON, co zmienia wszystko, gdy wyjście agenta zasila inny system, a nie ludzkiego czytelnika. Wreszcie, streaming zwraca odpowiedzi w czasie rzeczywistym zamiast w jednym bloku — kluczowe przy długich łańcuchach, gdzie ciche oczekiwanie staje się niewygodne.
Trzy zasoby towarzyszą temu następnemu krokowi: oficjalna dokumentacja pod adresem docs.mistral.ai/agents, cookbooks Mistral dostarczające kompletne przykłady implementacji oraz API Reference szczegółowo dokumentujące każdy punkt końcowy.
Kluczowe wnioski
- Specjalizuj swoich agentów — jeden agent = jedna odpowiedzialność
- Monitoruj — loguj każde przekazanie (handoff) i wykonanie narzędzia
- Testuj — waliduj routing i odpowiedzi każdego agenta
- Zabezpieczaj — bariery ochronne, najmniejsze uprawnienia, moderacja upstream
- Optymalizuj koszty — model dopasowany do zadań, max_tokens, store=False gdy to możliwe
- Mistral Agents są w fazie beta — bądź na bieżąco ze zmianami w API
Sprawdź swoją wiedzę
Agenci, wbudowane narzędzia, przekazywanie zadań: czy w API Agents zostały jakieś ślepe punkty?
1. Kiedy agent jest konieczny, a kiedy chatbot wystarczy?
Odpowiedź: Agent jest uzasadniony, gdy potrzebujesz narzędzi, trwałości i decyzji wieloetapowych; do prostych pytań i odpowiedzi wystarczy standardowa konwersacja — architektura podąża za potrzebą.
2. Czym zarządzają trwałe konwersacje w API Agents?
Odpowiedź: Historią po stronie Mistral: kontynuujesz konwersację poprzez jej ID bez konieczności ponownego wysyłania całego kontekstu — stan staje się usługą.
3. Wymień dostępne wbudowane narzędzia i ich zastosowanie.
Odpowiedź: web_search (informacje w czasie rzeczywistym), code_interpreter (uruchamianie Pythona), image_generation (tworzenie obrazów), document_library (pytania i odpowiedzi na podstawie Twoich plików) — gotowe możliwości, niewymagające implementacji.
4. Jak działa system wieloagentowy z przekazywaniem zadań (handoffs)?
Odpowiedź: Router kwalifikuje żądanie i przekazuje je do właściwego agenta-specialisty; każdy agent pozostaje prosty, orkiestracja zapewnia pokrycie, a handoffs tworzą łańcuchy w głąb.
5. Jak zabezpieczyć agentów w środowisku produkcyjnym?
Odpowiedź: Za pomocą barier ochronnych na wejściach/wyjściach, narzędzi o wąskim zakresie, możliwości śledzenia działań oraz walidacji przez człowieka w przypadku decyzji o wysokim ryzyku — autonomia jest zdobywana poprzez kontrolę.
Wyspecjalizowani agenci, wbudowane narzędzia, routing, bariery ochronne: kompletna architektura mieści się w czterech słowach — a ten kurs pozwolił Ci zbudować każdy z tych elementów.