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

Definirea instrumentelor în JSON

Lecția 4 din 14 Actualizată 29 iulie 2026 Dezvoltator
Pe această pagină
  1. De la teorie la practică
  2. Structura cererii cu instrumente
  3. Cifre cheie ale implementării
  4. Gestionarea răspunsului tool_call
  5. Executarea și returnarea rezultatului
  6. Definirea mai multor instrumente
  7. Verificarea câmpului finish_reason
  8. Puncte cheie

De la teorie la practică

Ați înțeles acum conceptul de apelare a funcțiilor și structura schemelor JSON. Este momentul să treceți la implementarea concretă. În această lecție, veți învăța cum să construiți o cerere completă cu definiții de instrumente și cum să gestionați răspunsul modelului.

Structura cererii cu instrumente

Iată o cerere completă adresată API-ului Grok cu un instrument definit:

from openai import OpenAI

client = OpenAI(
    api_key="your-api-key",
    base_url="https://api.x.ai/v1"
)

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": {
                "type": "object",
                "properties": {
                    "city": {
                        "type": "string",
                        "description": "City name"
                    },
                    "unit": {
                        "type": "string",
                        "enum": ["celsius", "fahrenheit"],
                        "default": "celsius"
                    }
                },
                "required": ["city"]
            }
        }
    }
]

response = client.chat.completions.create(
    model="grok-4.5",
    messages=[
        {"role": "user", "content": "What's the weather like in Paris?"}
    ],
    tools=tools
)

Observați structura imbricată: obiectul tools conține un tablou, unde fiecare element are un type și un obiect function cu detaliile necesare.

Cifre cheie ale implementării

200
Număr maxim de instrumente per cerere
6
Tipuri JSON suportate
3
SDK-uri compatibile
1
O cerere = întregul flux

Gestionarea răspunsului tool_call

Când modelul decide să apeleze o funcție, răspunsul conține un tablou tool_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}")

Câmpul tool_call.function.arguments este un șir JSON (nu un obiect Python). Trebuie să îl analizați:

import json

args = json.loads(tool_call.function.arguments)
city = args["city"]
unit = args.get("unit", "celsius")

Executarea și returnarea rezultatului

Odată ce funcția este executată, trimiteți rezultatul înapoi modelului într-o a doua apelare:

import json

# 1. Executați funcția
weather_data = get_weather(city="Paris", unit="celsius")

# 2. Construiți mesajele cu rezultatul
messages = [
    {"role": "user", "content": "What's the weather like in Paris?"},
    message,  # Răspunsul modelului cu tool_calls
    {
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps(weather_data)
    }
]

# 3. Apelați din nou modelul cu rezultatul
final_response = client.chat.completions.create(
    model="grok-4.5",
    messages=messages,
    tools=tools
)

print(final_response.choices[0].message.content)

Mesajul cu rolul tool trebuie să conțină:

  • tool_call_id: identificatorul unic al tool_call-ului (pentru a-l lega de cerere)
  • content: rezultatul sub formă de șir JSON

Definirea mai multor instrumente

Puteți declara câte instrumente doriți în tabloul tools:

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_weather",
            "description": "Get the current weather for a city",
            "parameters": { ... }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_restaurants",
            "description": "Search for restaurants by city and cuisine type",
            "parameters": { ... }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "book_table",
            "description": "Book a table at a restaurant",
            "parameters": { ... }
        }
    }
]

Modelul va alege automat instrumentul sau instrumentele relevante în funcție de cererea utilizatorului.

Verificarea câmpului finish_reason

Câmpul finish_reason din răspuns indică dacă modelul și-a terminat răspunsul sau dacă așteaptă un rezultat de la un instrument:

finish_reason = response.choices[0].finish_reason

if finish_reason == "tool_calls":
    # Modelul așteaptă rezultatul unuia sau mai multor instrumente
    handle_tool_calls(response)
elif finish_reason == "stop":
    # Modelul și-a terminat răspunsul
    print(response.choices[0].message.content)

Puncte cheie

  • Cererea conține messages și tools (definiții)
  • Argumentele tool_call sunt un șir JSON care trebuie analizat
  • Trimiteți rezultatul într-un mesaj cu rolul tool, incluzând tool_call_id
  • Verificați finish_reason pentru a ști dacă modelul așteaptă un rezultat
  • Puteți declara multiple instrumente; modelul le alege automat