Llamadas a herramientas
Describa funciones que su propio código puede ejecutar; el modelo decide cuándo pedir una, y su código decide si la ejecuta realmente y cómo. tAI nunca ejecuta una herramienta en su nombre.
tAI devuelve un solo turno del modelo a la vez y se detiene ahí. Nunca invoca una herramienta por sí mismo, nunca itera en bucle, y nunca ve el resultado de una llamada a herramienta a menos que usted se lo envíe de vuelta en una solicitud posterior. Su propio código es dueño de todo el bucle de ejecución: decidir si realmente ejecuta lo que el modelo pidió, ejecutarlo, y continuar la conversación con el resultado.
Definir herramientas
Envíe un array tools en la solicitud, usando la misma forma que usa la API de function-calling de OpenAI:
{
"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 importa más de lo que podría parecer: es la única información que tiene el modelo sobre qué hace una herramienta y cuándo conviene recurrir a ella. Una descripción vaga o ausente hace que una herramienta se invoque en los momentos equivocados, o que no se invoque cuando debería. parameters es un objeto JSON Schema que describe los argumentos que acepta la herramienta; los propios argumentos del modelo en una llamada a herramienta se generan para ajustarse a ese esquema.
Recibir una llamada a herramienta
Cuando el modelo decide invocar una herramienta en lugar de responder directamente, el finish_reason de la respuesta es "tool_calls" y message.tool_calls se completa en lugar de (o junto con) 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 es una cadena codificada en JSON, no un objeto anidado; interprétela antes de usarla. El modelo puede pedir más de una llamada a herramienta en el mismo turno si la solicitud tiene varias herramientas definidas y la tarea lo requiere, así que tool_calls siempre es un array, incluso cuando contiene exactamente una entrada.
En modo streaming, la misma información llega como un chunk delta.tool_calls seguido de un chunk de finalización con "finish_reason": "tool_calls"; vea Streaming para las formas generales de chunk sobre las que se construye esto.
Ejecutarla y continuar la conversación
Lo que ocurre después depende enteramente de su código. Decida si la llamada solicitada es algo que está dispuesto a ejecutar (este es exactamente el punto donde una aplicación normalmente aplica su propio modelo de permisos, sandboxing, o confirmación del usuario, antes de ejecutar nada). Si la ejecuta, envíe el resultado de vuelta como un nuevo mensaje con role: "tool", haciendo referencia a la llamada original mediante su 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 */]
}
El modelo entonces continúa desde ahí, normalmente respondiendo a la pregunta original usando el resultado de la herramienta, aunque también puede pedir otra llamada a herramienta si la tarea lo requiere. Siga enviando el mismo array tools en cada solicitud de la conversación, no solo en la primera; el modelo no tiene memoria de qué herramientas estaban disponibles en un turno anterior más allá de lo que está en la solicitud actual.
Rechazar ejecutar una llamada
Nada le obliga a ejecutar realmente lo que el modelo pidió. Si decide no hacerlo (la solicitud está fuera de alcance, necesita una confirmación que aún no tiene, o simplemente no es algo que su aplicación admita), envíe un mensaje tool explicando eso en lugar de un resultado real, y el modelo lo tendrá en cuenta en su siguiente respuesta, normalmente explicando la limitación al usuario en lugar de asumir que la acción ocurrió.
Por qué este diseño, específicamente
Algunos frameworks de agentes integran la ejecución de herramientas en la propia llamada a la API: usted registra una herramienta una vez, y la infraestructura del propio proveedor la ejecuta internamente, iterando en bucle hasta que una respuesta final está lista. tAI deliberadamente no hace esto con sus herramientas personalizadas. Sus herramientas son cosas que solo su código sabe ejecutar, a menudo tocando su propia infraestructura, sus propias credenciales, su propio sistema de archivos; no hay forma de que tAI las ejecute de forma segura aunque quisiera. Lo que tAI ofrece en cambio es exactamente una cosa: la decisión de cuándo debe invocarse una herramienta y con qué argumentos, producida en un único turno del modelo. Todo lo que viene después, ejecución, iteración en bucle, protegerse contra una secuencia de llamadas descontrolada, es responsabilidad directa de su aplicación, con exactamente el nivel de cautela y de alcance apropiado para lo que sus herramientas realmente pueden hacer.