Siirry pääsisältöön
Suomi— Valitse kieli
Valikko

Määritä työkalut JSON-muodossa

Oppitunti 4 / 14 Päivitetty 29. heinäkuuta 2026 Kehittäjä
Tällä sivulla
  1. Teoriasta käytäntöön
  2. Pyynnön rakenne työkalujen kanssa
  3. Toteutuksen avainluvut
  4. Käsittele tool_call-vastaus
  5. Suorita ja palauta tulos
  6. Määritä useita työkaluja
  7. Tarkista finish_reason
  8. Keskeiset asiat

Teoriasta käytäntöön

Ymmärrät nyt funktion kutsumisen käsitteen ja JSON-skeemojen rakenteen. On aika siirtyä konkreettiseen toteutukseen. Tässä oppitunnissa opit rakentamaan täydellisen pyynnön työkalumäärityksineen ja käsittelemään mallin vastauksen.

Pyynnön rakenne työkalujen kanssa

Tässä on täydellinen pyyntö Grok API:lle määritellyllä työkalulla:

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
)

Huomaa sisäkkäinen rakenne: tools-objekti sisältää taulukon, jossa jokaisella alkiolla on type ja function-objekti, joka sisältää yksityiskohdat.

Toteutuksen avainluvut

200
Työkalujen enimmäismäärä pyyntöä kohden
6
Tuetut JSON-tyypit
3
Yhteensopivat SDK:t
1
Pyyntö = koko vuorovaikutus

Käsittele tool_call-vastaus

Kun malli päättää kutsua funktion, vastaus sisältää tool_calls-taulukon:

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}")

Kenttä tool_call.function.arguments on JSON-merkkijono (ei Python-objekti). Sinun on jäsennettävä se:

import json

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

Suorita ja palauta tulos

Kun funktio on suoritettu, lähetät tuloksen takaisin mallille toisessa pyynnössä:

import json

# 1. Suorita funktio
weather_data = get_weather(city="Paris", unit="celsius")

# 2. Rakenna viestit tuloksen kanssa
messages = [
    {"role": "user", "content": "What's the weather like in Paris?"},
    message,  # Mallin vastaus, jossa on tool_calls
    {
        "role": "tool",
        "tool_call_id": tool_call.id,
        "content": json.dumps(weather_data)
    }
]

# 3. Kutsu mallia uudelleen tuloksen kanssa
final_response = client.chat.completions.create(
    model="grok-4.5",
    messages=messages,
    tools=tools
)

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

Viestin, jonka rooli on tool, on sisällettävä:

  • tool_call_id: työkalukutsun yksilöllinen tunniste (sen linkittämiseksi pyyntöön)
  • content: tulos JSON-merkkijonona

Määritä useita työkaluja

Voit määrittää tarvittavan määrän työkaluja tools-taulukkoon:

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": { ... }
        }
    }
]

Malli valitsee automaattisesti asiaankuuluvat työkalut käyttäjän pyynnön perusteella.

Tarkista finish_reason

Vastauksen finish_reason-kenttä ilmoittaa, onko malli päättänyt vastauksensa vai odottaako se työkalun tulosta:

finish_reason = response.choices[0].finish_reason

if finish_reason == "tool_calls":
    # Malli odottaa yhden tai useamman työkalun tulosta
    handle_tool_calls(response)
elif finish_reason == "stop":
    # Malli on päättänyt vastauksensa
    print(response.choices[0].message.content)

Keskeiset asiat

  • Pyyntö sisältää messages- ja tools-osat (määritykset)
  • tool_call-argumentit ovat jäsennettävä JSON-merkkijono
  • Lähetä tulos viestissä, jonka rooli on tool ja joka sisältää tool_call_id:n
  • Tarkista finish_reason selvittääksesi, odottaako malli tulosta
  • Voit määrittää useita työkaluja – malli valitsee ne automaattisesti