Tool Calling
Beschreiben Sie Funktionen, die Ihr eigener Code ausführen kann; das Modell entscheidet, wann es eine davon anfragt, und Ihr Code entscheidet, ob und wie sie tatsächlich ausgeführt wird. tAI führt niemals selbst ein Tool in Ihrem Namen aus.
tAI gibt jeweils einen Modell-Turn zurück und hält dann inne. Es ruft nie selbst ein Tool auf, läuft nie in einer Schleife und sieht das Ergebnis eines Tool-Aufrufs nie, es sei denn, Sie senden es in einer Folgeanfrage zurück. Ihr eigener Code besitzt die gesamte Ausführungsschleife: die Entscheidung, ob das vom Modell Angefragte tatsächlich ausgeführt wird, die Ausführung selbst und die Fortsetzung der Unterhaltung mit dem Ergebnis.
Tools definieren
Übergeben Sie ein tools-Array in der Anfrage, im selben Format, das die Function-Calling-API von OpenAI verwendet:
{
"model": "tai-4.1",
"messages": [{"role": "user", "content": "Ankara'da hava nasıl?"}],
"tools": [
{
"type": "function",
"function": {
"name": "get_weather",
"description": "Get the current weather for a city",
"parameters": {
"type": "object",
"properties": {"city": {"type": "string"}},
"required": ["city"]
}
}
}
]
}
description ist wichtiger, als es scheinen mag: Sie ist die einzige Information, die das Modell darüber hat, was ein Tool tut und wann es angemessen ist, darauf zurückzugreifen. Eine vage oder fehlende Beschreibung führt dazu, dass ein Tool zu den falschen Zeitpunkten aufgerufen wird, oder nicht aufgerufen wird, wenn es sollte. parameters ist ein JSON-Schema-Objekt, das die vom Tool akzeptierten Argumente beschreibt; die eigenen Argumente des Modells in einem Tool-Aufruf werden passend zu diesem Schema generiert.
Einen Tool-Aufruf empfangen
Wenn sich das Modell entscheidet, ein Tool aufzurufen, statt direkt zu antworten, ist der finish_reason der Antwort "tool_calls", und message.tool_calls ist befüllt, statt (oder zusätzlich zu) message.content:
{
"choices": [{
"index": 0,
"message": {
"role": "assistant",
"content": null,
"tool_calls": [{
"id": "call_a1b2c3",
"type": "function",
"function": {"name": "get_weather", "arguments": "{\"city\": \"Ankara\"}"}
}]
},
"finish_reason": "tool_calls"
}]
}
function.arguments ist ein JSON-kodierter String, kein verschachteltes Objekt; parsen Sie ihn, bevor Sie ihn verwenden. Das Modell kann im selben Turn mehr als einen Tool-Aufruf anfragen, wenn die Anfrage mehrere Tools definiert hat und die Aufgabe es erfordert, daher ist tool_calls immer ein Array, selbst wenn es genau einen Eintrag enthält.
Im Streaming-Modus trifft dieselbe Information als delta.tool_calls-Chunk ein, gefolgt von einem Finish-Chunk mit "finish_reason": "tool_calls"; die allgemeinen Chunk-Formate, auf denen das aufbaut, finden Sie unter Streaming.
Ausführen und die Unterhaltung fortsetzen
Was als Nächstes passiert, liegt vollständig bei Ihrem Code. Entscheiden Sie, ob der angefragte Aufruf etwas ist, das Sie ausführen möchten (genau das ist der Punkt, an dem eine Anwendung typischerweise ihr eigenes Berechtigungsmodell, Sandboxing oder eine Nutzerbestätigung anwendet, bevor irgendetwas ausgeführt wird). Wenn Sie ihn ausführen, senden Sie das Ergebnis als neue Nachricht mit role: "tool" zurück, unter Bezug auf den ursprünglichen Aufruf über dessen id:
{
"model": "tai-4.1",
"messages": [
{"role": "user", "content": "Ankara'da hava nasıl?"},
{"role": "assistant", "content": null, "tool_calls": [{"id": "call_a1b2c3", "type": "function", "function": {"name": "get_weather", "arguments": "{\"city\": \"Ankara\"}"}}]},
{"role": "tool", "tool_call_id": "call_a1b2c3", "content": "18°C, parçalı bulutlu"}
],
"tools": [/* same tools array as before */]
}
Das Modell setzt dann von dort fort, meist mit einer Antwort auf die ursprüngliche Frage unter Verwendung des Tool-Ergebnisses, kann aber auch einen weiteren Tool-Aufruf anfragen, wenn die Aufgabe das erfordert. Senden Sie dasselbe tools-Array bei jeder Anfrage in der Unterhaltung, nicht nur bei der ersten; das Modell hat keine Erinnerung daran, welche Tools in einem früheren Turn verfügbar waren, über das hinaus, was in der aktuellen Anfrage steht.
Einen Aufruf ablehnen
Nichts verpflichtet Sie dazu, tatsächlich auszuführen, worum das Modell gebeten hat. Wenn Sie sich dagegen entscheiden (die Anfrage liegt außerhalb des Geltungsbereichs, benötigt eine Bestätigung, die Sie noch nicht haben, oder ist schlicht etwas, das Ihre Anwendung nicht unterstützt), senden Sie stattdessen eine tool-Nachricht, die das erklärt, statt eines echten Ergebnisses, und das Modell wird das in seine nächste Antwort einbeziehen, typischerweise indem es dem Nutzer die Einschränkung erklärt, statt anzunehmen, dass die Aktion stattgefunden hat.
Warum genau dieses Design
Manche Agenten-Frameworks bündeln die Tool-Ausführung direkt in den API-Aufruf: Sie registrieren ein Tool einmal, und die eigene Infrastruktur des Anbieters führt es intern aus, in einer Schleife, bis eine endgültige Antwort bereit ist. tAI tut das bei Ihren eigenen, benutzerdefinierten Tools bewusst nicht. Ihre Tools sind Dinge, die nur Ihr Code auszuführen weiß, oft mit Zugriff auf Ihre eigene Infrastruktur, Ihre eigenen Zugangsdaten, Ihr eigenes Dateisystem; es gibt für tAI keine Möglichkeit, sie sicher auszuführen, selbst wenn es das wollte. Was tAI stattdessen bereitstellt, ist genau eine Sache: die aus einem einzelnen Modell-Turn erzeugte Entscheidung, wann ein Tool aufgerufen werden sollte und mit welchen Argumenten. Alles danach, Ausführung, Schleifenbildung, das Absichern gegen eine außer Kontrolle geratene Folge von Aufrufen, liegt eindeutig in der Verantwortung Ihrer Anwendung, mit genau dem Maß an Vorsicht und Eingrenzung, das dem entspricht, was Ihre Tools tatsächlich können.