Architektura API Agentów Mistral
Na tej stronie
Zaktualizowano 3 listopada 2026 r. Poprzedni pełny przykład agenta przekazywał
guardrails={"enabled": True}, co jest nieistniejącym formatem: oficjalnym parametrem jest lista konfiguracjimoderation_llm_v2. Dane wejściowetool.executionudostępniają nazwę narzędzia w poluentry.name, a nieentry.tool_name, co wcześniej powodowało błądAttributeError. Źródła: Agents & Conversations · Moderation & Guardrailing · SDKmistralai3.7.0.
Trzy fundamentalne obiekty
API Agentów Mistral opiera się na trzech współdziałających obiektach: Agent, Conversation (konwersacja) i Entry (wpis). Większość błędów projektowych popełnianych na początku projektu – takich jak tworzenie nowego agenta dla każdego żądania, ponowne użycie wygasłego conversation_id czy parsowanie odpowiedzi, które kończy się awarią przy niespodziewanym wpisie – wynika z pomylenia tych trzech poziomów. Zrozumienie ich ról i relacji jest warunkiem koniecznym, aby napisać choćby jedną linię kodu.
Obiekt Agent
Agent to zestaw konfiguracji definiujący zachowanie modelu. Nie zawiera żadnych danych konwersacyjnych: jest wielokrotnego użytku szablonem, który tworzysz raz, a do którego mogą odwoływać się tysiące konwersacji.
Tworzenie wymaga co najmniej podania modelu, nazwy i opisu.
agent = client.beta.agents.create(
model="mistral-large-latest", # Model LLM do użycia
name="My Agent", # Identyfikator czytelny dla człowieka
description="Agent for financial analysis" # Opis ukierunkowany na zadanie
)
Parametr model wskazuje model, który będzie napędzał agenta, wybierany spośród dostępnych modeli uzupełniania czatu, takich jak mistral-medium-latest lub mistral-large-latest. name to czytelny dla człowieka identyfikator, którego używasz do znajdowania i odwoływania się do agenta: w projekcie z dwudziestoma takimi obiektami to właśnie on ratuje Cię przed grzebaniem w logach, by ustalić, który z nich odpowiada klientom. Z kolei description ma charakter zadaniowy i służy nie tylko dokumentacji wewnętrznej – pomaga modelowi zrozumieć oczekiwaną rolę, co wyjaśnia sformułowanie „agent do analizy finansowej“ zamiast niejasnego „agent numer 3“.
Resztę konfigurujesz opcjonalnie i to właśnie tutaj kształtuje się rzeczywista osobowość agenta.
agent = client.beta.agents.create(
model="mistral-large-latest",
name="Complete Agent",
description="Agent with all parameters",
instructions="You are a finance expert. Always respond with sources.",
tools=[
{"type": "web_search"},
{"type": "code_interpreter"}
],
completion_args={"temperature": 0.3, "top_p": 0.95},
guardrails=[
{
"block_on_error": True,
"moderation_llm_v2": {
"custom_category_thresholds": {"jailbreaking": 0.2, "financial": 1},
"action": "block",
},
}
],
)
instructions– Prompt systemowy agenta (definiuje jego osobowość, zasady i styl).tools– Lista dostępnych narzędzi:web_search,web_search_premium,code_interpreter,image_generation,document_librarylub funkcje niestandardowe.completion_args– Parametry samplerowania (temperature, top_p, max_tokens itp.).guardrails– Lista konfiguracji moderacji (moderation_llm_v2) stosowanych do wiadomości przychodzących w każdej konwersacji agenta; tutaj jailbreaking jest blokowany powyżej progu 0,2, a kategoriafinancialjest wyłączona (próg1), ponieważ agent został zbudowany do dyskusji o finansach. Szczegóły znajdziesz w kursie AI Moderation and Security with Mistral.
W powyższym przykładzie agent finansowy dziedziczy wymóg podawania źródeł ze swoich instrukcji, możliwość weryfikacji danych dzięki narzędziom oraz niską temperaturę, która ogranicza kreatywność tam, gdzie wymagana jest ścisłość.
Obiekt Conversation
Conversation to historia interakcji między użytkownikiem a agentem – lub między użytkownikiem a samym modelem. Zawiera wiadomości, wyniki wykonania narzędzi oraz zdarzenia przekazania (handoff).
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Analyze trends in the European AI market."
)
# Pobierz ID konwersacji, aby kontynuować później
conversation_id = response.conversation_id
Zachowanie tego obiektu kryje kilka niespodzianek. Konwersacja jest trwała: historia jest przechowywana po stronie Mistral, chyba że przekażesz store=False. Jest niezależna od agenta, co oznacza, że konwersacja może istnieć bez agenta, w trybie bezpośredniego modelu. Wreszcie, jest niemutowalna: każde dodanie zwraca nowe conversation_id, przy czym stare pozostaje dostępne. Ten ostatni punkt jest najbardziej zaskakujący: jeśli zapiszesz początkowe ID w swojej bazie danych i użyjesz go ponownie przy trzeciej turze, cofniesz się do kontekstu pierwszej wymiany.
Obiekt Entry
Entry to indywidualna akcja w ramach konwersacji: atomowa jednostka historii. Gdy otrzymasz odpowiedź, pole outputs zawiera listę wpisów, których typ zależy od tego, co zrobił agent. Wpis typu message.output niesie odpowiedź tekstową od agenta, czyli tekst, który wyświetli Twój interfejs. Wpis typu tool.execution zawiera wynik wykonania narzędzia, np. kodu lub wyszukiwania w sieci: uruchomiony skrypt i jego wynik lub strony zwrócone przez silnik. Wpis typu agent.handoff sygnalizuje zdarzenie przekazania do innego agenta i pojawia się wyłącznie w scenariuszach wieloagentowych.
Pojedyncza odpowiedź często miesza te typy. Jeśli poprosisz wyposażonego w narzędzia agenta o obliczenie, otrzymasz najpierw wynik wykonania, a potem komentarz mu towarzyszący: Twój kod musi zatem iterować po tej liście, zamiast odczytywać pojedyncze pole.
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Calculate the square root of 144"
)
for entry in response.outputs:
print(f"Type: {entry.type}")
if entry.type == "message.output":
print(f"Message: {entry.content}")
elif entry.type == "tool.execution":
print(f"Tool: {entry.name}")
Relacje między obiektami
Poniższy diagram podsumowuje powiązania trzech poziomów: wielokrotnego użytku konfiguracji, wątku historii i jednostkowych akcji.
Agent (configuration)
├── model, instructions, tools, guardrails
└── Can be referenced by N conversations
Conversation (history)
├── Linked to 0 or 1 Agent (optional)
├── Contains N ordered entries
└── Each append creates a new conversation_id
Entry (unit action)
├── message.output (text response)
├── tool.execution (tool result)
└── agent.handoff (agent transfer)
Opcje konwersacji
Rozpoczynanie konwersacji przyjmuje ustawienia, które wpływają zarówno na Twoją zgodność z przepisami, jak i na architekturę systemu – lepiej więc decydować o nich świadomie, niż mierzyć się z ich skutkami później. Po pierwsze przechowywanie: store=False zapobiega jakiemukolwiek zapisowi po stronie Mistral, co wykorzystasz do przetwarzania danych, których Twoja wewnętrzna polityka zabrania zostawiać na serwerze strony trzeciej.
# Wyłącz przechowywanie w chmurze
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Sensitive question",
store=False
)
Drugie ustawienie definiuje, kto wykonuje przekazania (handoffs). W trybie server (wartość domyślna) Mistral łańcuchuje przekazy między agentami bez Twojej ingerencji; w trybie client otrzymujesz zdarzenia handoff i zachowujesz kontrolę, aby je logować, filtrować lub odrzucać.
# Tryb server (domyślny) — Mistral automatycznie obsługuje handoffy
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="server"
)
# Tryb client — otrzymujesz zdarzenia handoff i decydujesz, co zrobić
response = client.beta.conversations.start(
agent_id=agent.id,
inputs="Complex request",
handoff_execution="client"
)
Kluczowe wnioski
- Agent = wielokrotnego użytku konfiguracja (model, instrukcje, narzędzia, guardrails).
- Conversation = trwała historia przechowywana na serwerze, niezależna od agenta.
- Entry = jednostkowa akcja (wiadomość, wykonanie narzędzia, handoff).
- Konwersacje mogą istnieć bez agenta (tryb bezpośredniego modelu).
- Każde dodanie do konwersacji tworzy nowe
conversation_id. - Tryb
store=Falsezapobiega przechowywaniu danych po stronie Mistral.