Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Pozivanje API-ja s alatima

Lekcija 5 od 14 Ažurirano 2. studenoga 2026. Programer
Na ovoj stranici
  1. Slanje alata Mistral API-ju
  2. Prvi zahtjev
  3. Razumijevanje odgovora modela
  4. Raščlanjivanje odgovora i izdvajanje tool_calls
  5. Kada model zatraži nedostajuće informacije
  6. Rukovanje sistemskom porukom
  7. Cjeloviti kod za korake 2–3
  8. Ključne točke

Slanje alata Mistral API-ju

Definirao si svoje funkcije i njihove JSON specifikacije. Sada ih trebaš poslati Mistral API-ju i, što je još važnije, razumjeti što model vraća. Sada smo na koracima 2 i 3 procesa: model prima korisnički zahtjev zajedno s alatima i proizvodi poziv funkcije – ili odbija izvršiti ga, što je jednako poučno.

Prvi zahtjev

import os
import json
from mistralai.client import Mistral

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

# Alati definirani u prethodnoj lekciji
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"]
            }
        }
    }
]

# Korisnička poruka
messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

# API poziv s alatima
response = client.chat.complete(
    model="mistral-large-latest",
    messages=messages,
    tools=tools
)

Razumijevanje odgovora modela

Odgovor sadrži objekt message koji može imati dva oblika, a tvoj kod mora od prvog dana rukovati obama. U prvom slučaju, model odgovara izravno jer funkcija nije potrebna: content sadrži tekst, a tool_calls je None.

# response.choices[0].message.content sadrži tekstualni odgovor
# response.choices[0].message.tool_calls je None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"

U drugom slučaju, model želi pozvati funkciju. Situacija je obrnuta: content je prazan ili null, a tool_calls nosi podatke.

# response.choices[0].message.content je None ili prazan
# response.choices[0].message.tool_calls sadrži pozive
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}")

Tipičan ispis:

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

Raščlanjivanje odgovora i izdvajanje tool_calls

Evo cjelovitog koda za čisto izdvajanje informacija iz poziva alata:

message = response.choices[0].message

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

    # Izdvajanje naziva funkcije
    function_name = tool_call.function.name

    # Raščlanjivanje JSON argumenata u Python rječnik
    function_params = json.loads(tool_call.function.arguments)

    # Dohvaćanje jedinstvenog identifikatora poziva
    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 je odgovorio izravno
    print(f"Response: {message.content}")

Iz ovog bloka proizlaze tri podatka, a treći je onaj koji ljudi često zaborave. Naziv funkcije koristi se za usmjeravanje, raščlanjeni argumenti za poziv, ali tool_call_id je ono što modelu omogućuje povezivanje tvog rezultata s ispravnim pozivom kada ga pošalješ natrag. Ako ga izgubiš, taj okret razgovora postaje neopoziv.

Kada model zatraži nedostajuće informacije

Ponekad korisnik ne pruži dovoljno informacija. Model ima elegantan izlaz: uopće ne poziva funkciju, već postavlja razjašnjavajuće pitanje.

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?"

Ovo ponašanje je točno ono što želiš. Model zna da je transaction_id naveden u required; umjesto da izmisli uvjerljiv ID i pokrene zahtjev za nepostojećim podacima, prepusta riječ korisniku. Ovo je također najbolja demonstracija korisnosti polja required obrađenog u prethodnoj lekciji.

Rukovanje sistemskom porukom

Sistemska poruka omogućuje ti da okvirno odrediš ovo ponašanje umjesto da se nadaš da će se dogoditi samo od sebe.

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?"
    }
]

Pročitaj red po red: prva rečenica postavlja ulogu, druga ton i jezik asistenta, treća specificira kada koristiti funkcije, a zadnja daje eksplicitnu uputu za rubni slučaj – nedostatak informacija. To su tri slučaja upotrebe za koje se preporučuje sistemska poruka i oni u većini slučajeva sufficeiraju.

Cjeloviti kod za korake 2–3

Evo cjelovitog, višekratno upotrebljivog koda za slanje zahtjeva s alatima. On obuhvaća sve gore navedeno i normalizira odgovor u rječnik s dva oblika, štedeći ti raspršivanje provjera if message.tool_calls kroz cijelu aplikaciju.

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:
    """Sends a request to Mistral with tools and returns the parsed response."""
    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
    }

Imaj na umu da lista komprehenzije iterira kroz sve tool_calls, a ne samo kroz prvi. Model može proizvesti nekoliko odjednom; kasnija lekcija će to pokriti, ali tvoja pomoćna funkcija već je spremna rukovati njima.

Ključne točke

  • Pošalji tools i messages u client.chat.complete() kako bi omogućio pozivanje funkcija
  • Uvijek provjeri postoji li message.tool_calls prije pokušaja raščlanjivanja
  • tool_call_id je obavezan za slanje rezultata natrag modelu
  • Argumenti su JSON niz koji se mora raščlaniti s json.loads()
  • Model može odlučiti odgovoriti izravno ako ne treba funkciju ili ako nedostaju informacije