Přejít na hlavní obsah
Čeština— Vyberte jazyk
Menu

Volání API pomocí nástrojů

Lekce 5 z 14 Aktualizováno 2. listopadu 2026 Vývojář
Na této stránce
  1. Odeslání nástrojů do API Mistral
  2. První požadavek
  3. Pochopení odpovědi modelu
  4. Parsování odpovědi a extrakce tool_calls
  5. Když model požaduje chybějící informace
  6. Zpracování systémové zprávy
  7. Kompletní kód pro kroky 2–3
  8. Klíčové poznatky

Odeslání nástrojů do API Mistral

Definoval jsi své funkce a jejich specifikace ve formátu JSON. Nyní je musíš odeslat do API Mistral a co je důležitější, pochopit, co model vrátí. Právě teď se nacházíme ve krocích 2 a 3 celého procesu: model obdrží uživatelský požadavek spolu s nástroji a vytvoří volání funkce – nebo se rozhodne žádné neprovést, což je stejně poučné.

První požadavek

import os
import json
from mistralai.client import Mistral

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

# Nástroje definované v předchozí lekci
tools = [
    {
        "type": "function",
        "function": {
            "name": "retrieve_payment_status",
            "description": "Retrieves the status of a payment based on the transaction ID.",
            "parameters": {
                "type": "object",
                "properties": {
                    "transaction_id": {
                        "type": "string",
                        "description": "Unique transaction identifier (e.g., T1001)"
                    }
                },
                "required": ["transaction_id"]
            }
        }
    }
]

# Zpráva od uživatele
messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

# Volání API s nástroji
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

Pochopení odpovědi modelu

Odpověď obsahuje objekt message, který může nabývat dvou forem, a tvůj kód musí od prvního dne umět zpracovat obě. V prvním případě model odpoví přímo, protože není potřeba žádná funkce: content obsahuje text a tool_calls má hodnotu None.

# response.choices[0].message.content obsahuje textovou odpověď
# response.choices[0].message.tool_calls je None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"

Ve druhém případě chce model zavolat funkci. Situace se obrátí: content je prázdné nebo null a tool_calls nese datový obsah.

# response.choices[0].message.content je None nebo prázdné
# response.choices[0].message.tool_calls obsahuje volání
message = response.choices[0].message

if message.tool_calls:
    for tool_call in message.tool_calls:
        print(f"Function: {tool_call.function.name}")
        print(f"Arguments: {tool_call.function.arguments}")
        print(f"ID: {tool_call.id}")

Typický výstup:

Function: retrieve_payment_status
Arguments: {"transaction_id": "T1001"}
ID: call_abc123xyz

Parsování odpovědi a extrakce tool_calls

Zde je kompletní kód pro čistou extrakci informací z volání nástroje:

message = response.choices[0].message

if message.tool_calls and len(message.tool_calls) > 0:
    tool_call = message.tool_calls[0]

    # Extrahování názvu funkce
    function_name = tool_call.function.name

    # Parsování argumentů JSON do Python slovníku
    function_params = json.loads(tool_call.function.arguments)

    # Získání unikátního identifikátoru volání
    tool_call_id = tool_call.id

    print(f"The model wants to call: {function_name}")
    print(f"With parameters: {function_params}")
    print(f"Call ID: {tool_call_id}")
else:
    # Model odpověděl přímo
    print(f"Response: {message.content}")

Z tohoto bloku vyplývají tři klíčové informace, přičemž na tu třetí lidé často zapomínají. Název funkce slouží k směrování (dispatching), parsované argumenty se použijí pro samotné volání, ale tool_call_id je to, co umožňuje modelu při zpětném odeslání výsledku přiřadit odpověď ke správnému volání. Pokud ho ztratíš, celý krok konverzace se stane neobnovitelným.

Když model požaduje chybějící informace

Někdy uživatel neposkytne dostatek informací. Model má elegantní řešení: nezavolá žádnou funkci, ale místo toho položí upřesňující otázku.

messages = [
    {"role": "user", "content": "What is the status of my payment?"}
]

response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

message = response.choices[0].message
print(message.content)
# → "I need the transaction ID to check the status.
#     Could you please provide the transaction number?"

Toto chování je přesně to, co chceš. Model ví, že transaction_id je uvedeno v poli required; místo aby si vymyslel pravděpodobné ID a spustil požadavek na neexistujících datech, přenechá slovo uživateli. Je to také nejlepší demonstrace užitečnosti pole required, které jsme probírali v předchozí lekci.

Zpracování systémové zprávy

Systémová zpráva ti umožňuje toto chování rámecovat, místo abys na něj jen doufal.

messages = [
    {
        "role": "system",
        "content": "You are a payment tracking assistant. "
                   "Respond in English. "
                   "Use the available tools to answer questions "
                   "about transactions. If the user does not provide "
                   "the transaction ID, ask for it politely."
    },
    {
        "role": "user",
        "content": "What is the status of payment T1001?"
    }
]

Přečti si to řádek po řádku: první věta nastavuje roli, druhá určuje tón a jazyk asistenta, třetí specifikuje, kdy používat funkce, a poslední dává explicitní instrukci pro okrajový případ – chybějící informace. To jsou tři hlavní případy použití, pro které se systémová zpráva doporučuje, a ve většině případů zcela stačí.

Kompletní kód pro kroky 2–3

Zde je kompletní, znovu použitelný kód pro odeslání požadavku s nástroji. Zapouzdřuje vše výše uvedené a normalizuje odpověď do slovníku se dvěma formami, což tě ušetří roztroušených kontrol if message.tool_calls v celé tvé aplikaci.

import os
import json
from mistralai.client import Mistral

def call_mistral_with_tools(
    messages: list,
    tools: list,
    model: str = "mistral-large-latest",
    tool_choice: str = "auto"
) -> dict:
    """Odešle požadavek do Mistral s nástroji a vrátí parsovanou odpověď."""
    client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])

    response = client.chat.complete(
        model=model,
        messages=messages,
        tools=tools,
        tool_choice=tool_choice
    )

    message = response.choices[0].message

    if message.tool_calls and len(message.tool_calls) > 0:
        return {
            "type": "tool_call",
            "message": message,
            "tool_calls": [
                {
                    "id": tc.id,
                    "function_name": tc.function.name,
                    "arguments": json.loads(tc.function.arguments)
                }
                for tc in message.tool_calls
            ]
        }

    return {
        "type": "text",
        "message": message,
        "content": message.content
    }

Všimni si, že list comprehension iteruje přes všechna tool_calls, nejen přes první. Model jich může najednou vygenerovat několik; pozdější lekce se tím bude zabývat, ale tvá pomocná funkce je již připravena je zpracovat.

Klíčové poznatky

  • Odešli tools a messages do client.chat.complete(), abys povolil volání funkcí.
  • Vždy zkontroluj, zda message.tool_calls existuje, než se pokusíš o parsování.
  • tool_call_id je povinný pro odeslání výsledku zpět modelu.
  • Argumenty jsou JSON řetězec, který musíš parsovat pomocí json.loads().
  • Model se může rozhodnout odpovědět přímo, pokud nepotřebuje funkci nebo pokud chybí informace.