Tworzenie wyspecjalizowanych agentów i routera
Na tej stronie
Od teorii do praktyki
Poprzednia lekcja wprowadziła koncepcję przekazywania zadań (handoffs). Teraz zbudujesz kompletny system w właściwej kolejności: najpierw specjaliści, potem router, następnie połączenia między nimi, a na końcu rozmowa, która uruchamia całość. Ta kolejność nie jest przypadkowa – router może wskazywać tylko na agentów, którzy już istnieją.
Krok 1: Tworzenie agentów specjalistycznych
Każdy agent otrzymuje precyzyjną domenę ekspertyzy i nic więcej.
from mistralai.client import Mistral
from mistralai.client.models import CompletionArgs, ResponseFormat, JSONSchema
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# Agent wyszukiwania w sieci
web_agent = client.beta.agents.create(
model="mistral-large-latest",
name="web-search-agent",
description="Agent wyszukujący informacje w internecie.",
instructions="Wykonuj precyzyjne wyszukiwania w sieci. Zawsze cytuj źródła.",
tools=[{"type": "web_search"}]
)
# Agent finansowy
finance_agent = client.beta.agents.create(
model="mistral-large-latest",
name="finance-agent",
description="Agent specjalizujący się w pytaniach finansowych.",
instructions="""Jesteś ekspertem finansowym.
- Używaj danych liczbowych
- Wyjaśniaj koncepcje w sposób jasny
- Sygnalizuj ryzyka"""
)
# Agent kalkulatora
calculator_agent = client.beta.agents.create(
model="mistral-large-latest",
name="calculator-agent",
description="Agent do szczegółowych obliczeń matematycznych.",
instructions="Wyjaśniaj każdy krok obliczeń. Do złożonych kalkulacji używaj interpretera kodu.",
tools=[{"type": "code_interpreter"}]
)
Te cztery pola pełnią zupełnie różne role, a jedno zasługuje na szczególną uwagę. Pole name w formacie kebab-case służy Tobie: pojawia się w logach i testach, a czytelna nazwa избавia Cię od porównywania nieprzejrzystych identyfikatorów. Pole instructions adresuje model, gdy ten zaczyna pracować, więc musi być specyficzne dla domeny – „sygnalizuj ryzyka“ coś znaczy dla agenta finansowego, podczas gdy „bądź pomocny“ nie znaczy nic dla nikogo. Pole tools podlega zasadzie ścisłej konieczności: powyższy agent finansowy nie ma narzędzi, ponieważ rozumuje bez ich potrzeby, a przydzielenie mu narzędzi jedynie zaprosiłoby do nadużyć. Wreszcie, pole description nie jest dokumentacją: to tekst, który router odczytuje, aby zdecydować, czy przekazać zadanie tutaj, czy gdzie indziej.
Krok 2: Tworzenie agenta-routera
Router nie posiada narzędzi. Jego jedynym zadaniem jest analiza żądania i wybór odbiorcy.
router_agent = client.beta.agents.create(
model="mistral-large-latest",
name="router-agent",
description="Agent-router rozdzielający żądania.",
instructions="""Jesteś orkiestratorem.
Analizuj każde żądanie i przekazuj je do właściwego agenta:
- Pytania wymagające danych online → web-search-agent
- Pytania finansowe → finance-agent
- Obliczenia i analiza numeryczna → calculator-agent
Nigdy nie odpowiadaj bezpośrednio – zawsze przekazuj dalej."""
)
Ostatnia linijka zapobiega załamaniu się systemu. Bez niej router zbudowany na dużym modelu będzie odpowiadał na pytania, które wydają mu się łatwe, pomijając Twoich specjalistów i generując odpowiedzi bez użycia narzędzi, z których ci by skorzystali. W rezultacie otrzymujesz architekturę wieloagentową, w której połowa agentów nigdy nie zostaje użyta.
Krok 3: Definiowanie celów przekazywania zadań
Teraz musisz poinformować routera, do których agentów może przekazywać zadania.
router_agent = client.beta.agents.update(
agent_id=router_agent.id,
handoffs=[web_agent.id, finance_agent.id, calculator_agent.id]
)
Parametr handoffs przyjmuje listę identyfikatorów agentów, a router może przekazać zadanie do dowolnego z nich. Nie jest to przywilej zastrzeżony wyłącznie dla routera: specjaliści również mogą deklarować własne cele przekazań.
# Agent finansowy może przekazywać zadania do wyszukiwania w sieci i kalkulatora
finance_agent = client.beta.agents.update(
agent_id=finance_agent.id,
handoffs=[web_agent.id, calculator_agent.id]
)
Łańcuch typu router → finanse → wyszukiwanie w sieci → kalkulator staje się wtedy możliwy. Gdy agent finansowy сталкиwa się z pytaniem wymagającym aktualnego kursu, nie odsyła z powrotem do routera: idzie bezpośrednio do specjalisty, którego potrzebuje, tak jak konsultant dzwoniący do kolegi, zamiast wracać przez recepcję.
Krok 4: Rozpoczęcie rozmowy
response = client.beta.conversations.start(
agent_id=router_agent.id,
inputs="Znajdź aktualną kluczową stopę procentową EBC i oblicz procent składany przez 10 lat dla 100 000 €."
)
# Analiza przepływu
for entry in response.outputs:
if entry.type == "agent.handoff":
print(f"[HANDOFF] → {entry.next_agent_id}")
elif entry.type == "tool.execution":
print(f"[TOOL] {entry.tool_name}")
elif entry.type == "message.output":
print(f"[RESPONSE] {entry.content[:200]}...")
Uruchom to żądanie i obserwuj ślad wykonania przed sprawdzeniem odpowiedzi. Powinieneś zobaczyć dwa przekazania zadań i co najmniej jedno wykonanie narzędzia; jeśli nie widzisz żadnego, Twój router odpowiedział samodzielnie i czas zaostrzyć jego instrukcje.
Główny mechanizm: opis
Gdy routowanie zawodzi, winny jest prawie zawsze opis. Router nie zna Twoich intencji; odczytuje jedynie ten tekst dla każdego kandydującego agenta.
# Źle – zbyt ogólnie
description="Użyteczny agent."
# Dobrze – router wie, kiedy przekazać zadanie
description="Agent wyszukujący aktualne informacje w internecie i cytujący swoje źródła."
Pisz każdy opis jako odpowiedź na pytanie „w jakim przypadku powinienem wywołać tego agenta?“, a nie jako podsumowanie tego, czym on jest. Drugi przykład nazywa sytuację – aktualne informacje, w internecie – podczas gdy pierwszy pozostawia routera w domysłach. Upewnij się również, że żadna para opisów nie nakłada się na siebie: dwaj agenci opisani w podobny sposób spowodują niestabilne routowanie od jednego wykonania do drugiego.
Kompletny przykład
Oto wersja skondensowana, z parametrem handoffs przekazanym bezpośrednio podczas tworzenia routera, ponieważ specjaliści istnieją już w tym momencie.
from mistralai.client import Mistral
import os
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
# 1. Agenci specjalistyczni
research = client.beta.agents.create(
model="mistral-large-latest",
name="research-agent",
description="Wyszukiwanie informacji online z podaniem źródeł.",
tools=[{"type": "web_search"}]
)
analyst = client.beta.agents.create(
model="mistral-large-latest",
name="analyst-agent",
description="Analiza danych i obliczenia w Pythonie.",
tools=[{"type": "code_interpreter"}]
)
writer = client.beta.agents.create(
model="mistral-large-latest",
name="writer-agent",
description="Tworzenie strukturalnych i profesjonalnych raportów.",
instructions="Pisz jasne raporty zawierające wstęp, analizę i rekomendacje."
)
# 2. Router z przekazaniami zadań
router = client.beta.agents.create(
model="mistral-large-latest",
name="router",
description="Orkiestruje złożone żądania.",
instructions="Analizuj żądanie i przekazuj je do odpowiedniego specjalisty.",
handoffs=[research.id, analyst.id, writer.id]
)
# 3. Uruchomienie
response = client.beta.conversations.start(
agent_id=router.id,
inputs="Przeanalizuj europejski rynek chmury obliczeniowej w 2026 roku: wielkość, gracze, trendy."
)
Kluczowe wnioski
- Twórz agentów specjalistycznych z precyzyjnymi opisami zorientowanymi na zadania
- Router używa opisów do wyboru agenta docelowego
client.beta.agents.update(handoffs=[...])definiuje cele przekazań- Przekazania zadań mogą być zagnieżdżone (agent A → agent B → agent C)
- Opis każdego agenta jest głównym mechanizmem wpływającym na jakość routowania