Toolaanroepen in uw applicatie verwerken
Detecteer finish_reason tool_calls in het API-antwoord, haal functienamen en argumenten eruit, voer de bijbehorende Python-functie uit en stuur het resultaat terug naar het model.
Toolaanroepen in uw applicatie verwerken is een gratis AI Engineering Academy-les op CoddyKit. Dit is les 2 van 4. Je kunt de volledige les hieronder gratis lezen en daarna in de browser praktisch oefenen met een ingebouwde code-editor en een AI-begeleider die 24/7 beschikbaar is. Deze les maakt deel uit van het leertraject AI Engineering Academy. Je voortgang wordt gesynchroniseerd op het web en in de CoddyKit-app. De cursus AI Engineering Academy bevat in totaal 4 lessen.
Het antwoordobject van een toolaanroep
Wanneer het model besluit een functie aan te roepen, bevat het API-antwoord een lijst tool_calls in het berichtobject. Elke toolaanroep heeft een unieke id, de aan te roepen function.name en function.arguments: een JSON-tekenreeks met de argumenten die het model wil doorgeven. Uw toepassingscode moet deze tekenreeks parseren en de functie uitvoeren.
from openai import OpenAI
import json
client = OpenAI()
response = client.chat.completions.create(
model='gpt-4o',
messages=[{'role': 'user', 'content': 'What is the weather in Paris?'}],
tools=tools # defined previously
)
message = response.choices[0].message
if response.choices[0].finish_reason == 'tool_calls':
for tool_call in message.tool_calls:
print('Call ID:', tool_call.id)
print('Function name:', tool_call.function.name)
print('Arguments (JSON string):', tool_call.function.arguments)Functieargumenten parseren
Het veld function.arguments is een JSON-gecodeerde tekenreeks, geen Python-dict. U moet deze parseren met json.loads(). Plaats dit altijd in een try/except-blok: ondanks de aanwijzingen in het schema produceert het model soms ongeldige JSON en moet u dit op een nette manier afhandelen.
import json
def parse_tool_call(tool_call) -> dict:
'''Parse a tool call's arguments from JSON string to dict.'''
try:
args = json.loads(tool_call.function.arguments)
return args
except json.JSONDecodeError as e:
print(f'Failed to parse arguments for {tool_call.function.name}: {e}')
print(f'Raw arguments: {tool_call.function.arguments}')
return {}
# Usage
tool_call = message.tool_calls[0]
args = parse_tool_call(tool_call)
print('Parsed args:', args) # {'location': 'Paris', 'unit': 'celsius'}De juiste functie aanroepen
Gebruik function.name om de juiste Python-functie aan te roepen. Een overzichtelijk patroon is om uw functies in een woordenboek te bewaren dat namen aan aanroepbare objecten koppelt. Zo vermijdt u kwetsbare if/elif-ketens en kunt u later eenvoudig nieuwe tools toevoegen.
def get_current_weather(location: str, unit: str = 'celsius') -> str:
# Real implementation calls a weather API
return f'{location}: 18{chr(176)}C, partly cloudy'
def create_calendar_event(title: str, start_time: str, duration_minutes: int, **kwargs) -> str:
return f'Event created: {title} at {start_time} for {duration_minutes} minutes'
# Tool registry: maps function names to callables
TOOL_REGISTRY = {
'get_current_weather': get_current_weather,
'create_calendar_event': create_calendar_event
}
def execute_tool_call(tool_call) -> str:
name = tool_call.function.name
args = parse_tool_call(tool_call)
if name not in TOOL_REGISTRY:
return f'Unknown function: {name}'
try:
result = TOOL_REGISTRY[name](**args)
return str(result)
except Exception as e:
return f'Function {name} raised an error: {str(e)}'Resultaten terugsturen naar het model
Nadat u de functie hebt uitgevoerd, moet u het resultaat in een vervolgaanroep van de API terugsturen naar het model. Voeg het bericht van de assistent (dat de tool_calls bevat) toe aan het gesprek en voeg daarna een nieuw bericht toe met role='tool', de tool_call_id en het functieresultaat als inhoud. Roep de API vervolgens opnieuw aan.
def run_tool_call_loop(messages: list, tools: list) -> str:
response = client.chat.completions.create(
model='gpt-4o',
messages=messages,
tools=tools
)
message = response.choices[0].message
messages.append(message) # Add assistant's tool_calls message
# Execute all tool calls and collect results
for tool_call in (message.tool_calls or []):
result = execute_tool_call(tool_call)
# Add each tool result as a 'tool' role message
messages.append({
'role': 'tool',
'tool_call_id': tool_call.id,
'content': result
})
# Second API call with results appended
final_response = client.chat.completions.create(
model='gpt-4o',
messages=messages,
tools=tools
)
return final_response.choices[0].message.contentDe volledige gespreksronde
Een volledige interactie met een toolaanroep bevat vier berichten in de gespreksgeschiedenis: het bericht van de gebruiker, het bericht van de assistent waarin om een toolaanroep wordt gevraagd, het bericht met het toolresultaat en het uiteindelijke antwoord van de assistent waarin het resultaat is verwerkt. Inzicht in deze structuur is essentieel voor het bouwen van assistenten die tools in gesprekken met meerdere rondes gebruiken.
# The full message history for a tool-calling conversation:
conversation = [
{'role': 'user', 'content': 'What is the weather in Tokyo?'},
# Model requests a tool call (added by run_tool_call_loop)
# {'role': 'assistant', 'content': None, 'tool_calls': [...]},
# Application sends tool result back
# {'role': 'tool', 'tool_call_id': 'call_abc123', 'content': 'Tokyo: 22C, sunny'},
# Model produces final human-readable response
# {'role': 'assistant', 'content': 'The weather in Tokyo is 22 degrees Celsius and sunny.'}
]
final_answer = run_tool_call_loop(
[{'role': 'user', 'content': 'What is the weather in Tokyo?'}],
tools
)
print(final_answer)Het geval afhandelen waarin geen tool wordt aangeroepen
Soms antwoordt het model rechtstreeks zonder een tool aan te roepen: finish_reason is dan 'stop' in plaats van 'tool_calls'. Controleer dit geval altijd voordat u toolaanroepen probeert te verwerken. Een robuuste implementatie handelt beide vertakkingen netjes af.
def smart_complete(user_message: str) -> str:
messages = [{'role': 'user', 'content': user_message}]
response = client.chat.completions.create(
model='gpt-4o',
messages=messages,
tools=tools
)
choice = response.choices[0]
if choice.finish_reason == 'stop':
# Model answered directly without calling a tool
return choice.message.content
elif choice.finish_reason == 'tool_calls':
# Process tool calls
messages.append(choice.message)
for tc in choice.message.tool_calls:
result = execute_tool_call(tc)
messages.append({'role': 'tool', 'tool_call_id': tc.id, 'content': result})
# Get final answer
final = client.chat.completions.create(model='gpt-4o', messages=messages)
return final.choices[0].message.content
return 'Unexpected finish reason: ' + choice.finish_reasonArgumenten valideren vóór uitvoering
Het model kan soms argumenten doorgeven die niet slagen voor validatie van de bedrijfslogica: een negatieve duur, een ongeldig e-mailadres of een datum in het verleden. Valideer argumenten voordat u de echte functie aanroept en retourneer een beschrijvende fouttekenreeks als de validatie mislukt. Het model kan zijn argumenten dan in de volgende ronde corrigeren.
from pydantic import BaseModel, ValidationError
from datetime import datetime
class CreateEventArgs(BaseModel):
title: str
start_time: str # ISO 8601
duration_minutes: int
def safe_create_event(tool_call) -> str:
try:
raw_args = json.loads(tool_call.function.arguments)
validated = CreateEventArgs(**raw_args)
# Additional business rule
event_time = datetime.fromisoformat(validated.start_time)
if event_time < datetime.now():
return 'Error: start_time must be in the future.'
return create_calendar_event(**validated.dict())
except ValidationError as e:
return f'Invalid arguments: {e}'Interacties met toolaanroepen loggen
Log interacties met toolaanroepen altijd voor foutopsporing en analyse. Log de functienaam, argumenten, het resultaat en de uitvoeringstijd. Deze gegevens helpen u vast te stellen welke tools het vaakst worden aangeroepen, welke mislukken en welke argumentpatronen het model produceert. Dat is van onschatbare waarde voor het verbeteren van uw schema's en functie-implementaties.
import time
import logging
logger = logging.getLogger('tool_calls')
def logged_execute(tool_call) -> str:
name = tool_call.function.name
args_str = tool_call.function.arguments
start = time.time()
result = execute_tool_call(tool_call)
elapsed = time.time() - start
logger.info(
'Tool call executed',
extra={
'function': name,
'arguments': args_str,
'result_length': len(result),
'elapsed_ms': round(elapsed * 1000)
}
)
return resultBeveiligingsoverwegingen voor toolaanroepen
Voer nooit willekeurige functies uit op basis van modeluitvoer zonder validatie. Sta in uw TOOL_REGISTRY altijd alleen de exacte functienamen op de toelatingslijst toe, valideer alle argumenten en controleer de autorisatie voordat u acties uitvoert. Het model is een niet-vertrouwde aanroeper: een kwaadaardige prompt kan proberen destructieve functies aan te roepen als uw aanroepingslogica te soepel is.
- Sta alleen functies toe die expliciet in TOOL_REGISTRY staan
- Valideer invoer met Pydantic vóór uitvoering
- Vereis autorisatie voor schrijf- en verwijderbewerkingen
Uitgebreide gestructureerde resultaten retourneren
Toolresultaten hoeven geen gewone tekenreeksen te zijn. U kunt gegevens in JSON-indeling, tabellen of samenvattingen retourneren. Door gestructureerde gegevens als JSON te retourneren, kan het model specifieke velden in het uiteindelijke antwoord parsen en vermelden. Geef bij grote resultaten een samenvatting met de belangrijkste feiten terug in plaats van alle onbewerkte gegevens in de context te plaatsen.
def get_order_status(order_id: str) -> str:
# Fetch from real database
order = {'id': order_id, 'status': 'shipped', 'estimated_delivery': '2024-03-15', 'carrier': 'FedEx', 'tracking': 'FX123456'}
# Return concise summary, not raw DB record
return (
f'Order {order_id}: Status={order["status"]}, '
f'Estimated delivery: {order["estimated_delivery"]}, '
f'Carrier: {order["carrier"]}, Tracking: {order["tracking"]}'
)Gesprekken met meerdere rondes en toolgebruik
Een krachtig patroon is een gesprek met meerdere rondes waarin het model tools aanroept tijdens meerdere berichten van de gebruiker en zo context opbouwt. Houd altijd de volledige gespreksgeschiedenis bij, inclusief eerdere toolaanroepen en resultaten, zodat het model naar eerdere antwoorden kan verwijzen zonder onnodig opnieuw tools aan te roepen.
Korte controle
Test uw begrip van het verwerken van toolaanroepen in uw toepassing.
Samenvatting van de les
In deze les hebt u geleerd dat argumenten voor toolaanroepen als JSON-tekenreeks binnenkomen en met json.loads() moeten worden geparseerd, dat een TOOL_REGISTRY-woordenboek functienamen aan aanroepbare objecten koppelt voor een overzichtelijke aanroep en dat resultaten als berichten met role='tool' en overeenkomende tool_call_ids naar het model teruggaan. Vervolgens behandelen we het geval waarin het model meerdere functies tegelijk aanroept met parallelle functieaanroepen.
Leer Python met een AI-tutor — gratis
Schrijf echte code en voer die uit in je browser, krijg direct hulp van een AI-tutor die 24/7 beschikbaar is en ga verder waar je gebleven bent op het web of in de app.
- Cursussen
- 30
- Lessen
- 120
Veelgestelde vragen
Is de les “Toolaanroepen in uw applicatie verwerken” gratis?
Ja — de volledige tekst van “Toolaanroepen in uw applicatie verwerken” kun je hier gratis op het web lezen. Als je interactief wilt oefenen met een ingebouwde code-editor en een AI-begeleider die 24/7 beschikbaar is, en de rest van de cursus AI Engineering Academy wilt ontgrendelen, kun je upgraden naar CoddyKit PRO. De cursus AI Engineering Academy bevat in totaal 4 lessen.
Wat leer ik in “Toolaanroepen in uw applicatie verwerken”?
Detecteer finish_reason tool_calls in het API-antwoord, haal functienamen en argumenten eruit, voer de bijbehorende Python-functie uit en stuur het resultaat terug naar het model. Je oefent met AI Engineering Academy door code rechtstreeks in de browser uit te voeren. Een AI-begeleider die 24/7 beschikbaar is beantwoordt je vragen terwijl je de les doorwerkt.
Heb ik ervaring nodig om met AI Engineering Academy te beginnen?
Ervaring vooraf is niet nodig. AI Engineering Academy op CoddyKit is opgebouwd voor beginners tot gevorderden, zodat je hier of bij het begin kunt starten en in je eigen tempo kunt leren. Dit is les 2 van 4.
Hoe lang duurt de les “Toolaanroepen in uw applicatie verwerken”?
De meeste lessen van CoddyKit duren ongeveer 5–10 minuten. Elke les is kort en interactief, zodat je gestaag vooruitgaat en op het web en in de app precies verdergaat waar je was gebleven.
Kan ik code schrijven en uitvoeren in deze les over AI Engineering Academy?
Ja. Elke les over AI Engineering Academy bevat een ingebouwde code-editor, zodat je rechtstreeks in je browser echte code kunt schrijven en uitvoeren en direct feedback van AI krijgt — lokale installatie is niet nodig.
Alle lessen in deze cursus
- Functieschema's voor de API definiëren
- Toolaanroepen in uw applicatie verwerken
- Parallelle functieaanroepen
- Een interface voor databases in natuurlijke taal bouwen