Salt la conținutul principal
Română— Alege o limbă
Meniu

Apelarea API-ului cu Instrumente

Lecția 5 din 14 Actualizată 2 noiembrie 2026 Dezvoltator
Pe această pagină
  1. Trimiterea instrumentelor către API-ul Mistral
  2. Prima cerere
  3. Înțelegerea răspunsului modelului
  4. Analiza răspunsului și extragerea tool_calls
  5. Când modelul solicită informații lipsă
  6. Gestionarea mesajului de sistem
  7. Cod complet pentru pașii 2–3
  8. Puncte cheie

Trimiterea instrumentelor către API-ul Mistral

Ați definit funcțiile și specificațiile lor JSON. Acum trebuie să le trimiteți către API-ul Mistral și, mai important, să înțelegeți ce returnează modelul. Ne aflăm acum la pașii 2 și 3 ai procesului: modelul primește cererea utilizatorului împreună cu instrumentele și produce un apel de funcție – sau refuză să facă unul, ceea ce este la fel de instructiv.

Prima cerere

import os
import json
from mistralai.client import Mistral

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

# Tools defined in the previous lesson
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"]
            }
        }
    }
]

# User message
messages = [
    {"role": "user", "content": "What is the status of payment T1001?"}
]

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

Înțelegerea răspunsului modelului

Răspunsul conține un obiect message care poate lua două forme, iar codul dumneavoastră trebuie să le gestioneze pe ambele încă de la început. În primul caz, modelul răspunde direct deoarece nu este necesară nicio funcție: content conține text, iar tool_calls este None.

# response.choices[0].message.content contains the text response
# response.choices[0].message.tool_calls is None
print(response.choices[0].message.content)
# → "Hello! How can I help you?"

În al doilea caz, modelul dorește să apeleze o funcție. Situația se inversează: content este gol sau null, iar tool_calls conține datele utile.

# response.choices[0].message.content is None or empty
# response.choices[0].message.tool_calls contains the calls
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}")

Ieșire tipică:

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

Analiza răspunsului și extragerea tool_calls

Iată codul complet pentru a extrage corect informațiile dintr-un apel de instrument:

message = response.choices[0].message

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

    # Extract the function name
    function_name = tool_call.function.name

    # Parse JSON arguments into a Python dictionary
    function_params = json.loads(tool_call.function.arguments)

    # Retrieve the unique call identifier
    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:
    # The model responded directly
    print(f"Response: {message.content}")

Din acest bloc rezultă trei informații, iar a treia este cea pe care oamenii o uită adesea. Numele funcției este utilizat pentru direcționare, argumentele analizate sunt folosite pentru apel, dar tool_call_id este ceea ce permite modelului să asocieze rezultatul dumneavoastră cu apelul corect atunci când îl trimiteți înapoi. Dacă îl pierdeți, turul de conversație devine irecuperabil.

Când modelul solicită informații lipsă

Uneori, utilizatorul nu furnizează suficiente informații. Modelul are o soluție elegantă: să nu apeleze deloc o funcție și, în schimb, să pună o întrebare de clarificare.

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

Acest comportament este exact ceea ce doriți. Modelul știe că transaction_id este listat în required; în loc să inventeze un ID plauzibil și să declanșeze o cerere pe date inexistente, cedează inițiativa utilizatorului. Aceasta este, de asemenea, cea mai bună demonstrație a utilității câmpului required abordat în lecția anterioară.

Gestionarea mesajului de sistem

Mesajul de sistem vă permite să încadrați acest comportament, în loc să sperați că va apărea natural.

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

Citiți-l linie cu linie: prima propoziție stabilește rolul, a doua stabilește tonul și limba asistentului, a treia specifică când să se utilizeze funcțiile, iar ultima oferă o instrucțiune explicită pentru un caz limită – informații lipsă. Acestea sunt cele trei cazuri de utilizare pentru care se recomandă un mesaj de sistem și sunt suficiente în majoritatea situațiilor.

Cod complet pentru pașii 2–3

Iată codul complet și reutilizabil pentru trimiterea unei cereri cu instrumente. Acesta încapsulează tot ce am văzut mai sus și normalizează răspunsul într-un dicționar cu două forme, scutindu-vă de necesitatea de a împrăștia verificări if message.tool_calls în întreaga aplicație.

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
    }

Rețineți că lista comprehensivă iterează peste toate tool_calls, nu doar peste primul. Modelul poate produce mai multe simultan; o lecție viitoare va aborda acest aspect, dar funcția utilitară este deja pregătită să le gestioneze.

Puncte cheie

  • Trimiteți tools și messages către client.chat.complete() pentru a activa apelarea funcțiilor
  • Verificați întotdeauna dacă message.tool_calls există înainte de a încerca analiza
  • tool_call_id este obligatoriu pentru a trimite rezultatul înapoi modelului
  • Argumentele sunt un șir JSON care trebuie analizat cu json.loads()
  • Modelul poate alege să răspundă direct dacă nu are nevoie de o funcție sau dacă informațiile lipsesc