Przejdź do głównej treści
Polski— Wybierz język
Menu

Architektura API Agentów Mistral

Lekcja 3 z 18 Zaktualizowano 3 listopada 2026 Programista
Na tej stronie
  1. Trzy fundamentalne obiekty
  2. Obiekt Agent
  3. Obiekt Conversation
  4. Obiekt Entry
  5. Relacje między obiektami
  6. Opcje konwersacji
  7. Kluczowe wnioski

Zaktualizowano 3 listopada 2026 r. Poprzedni pełny przykład agenta przekazywał guardrails={"enabled": True}, co jest nieistniejącym formatem: oficjalnym parametrem jest lista konfiguracji moderation_llm_v2. Dane wejściowe tool.execution udostępniają nazwę narzędzia w polu entry.name, a nie entry.tool_name, co wcześniej powodowało błąd AttributeError. Źródła: Agents & Conversations · Moderation & Guardrailing · SDK mistralai 3.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_library lub 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 kategoria financial jest wyłączona (próg 1), 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=False zapobiega przechowywaniu danych po stronie Mistral.