Chamada de ferramentas
Descreva funções que o seu próprio código pode executar; o modelo decide quando pedir uma, e o seu código decide se e como a executa de facto. A tAI nunca executa uma ferramenta em seu nome.
A tAI devolve um turno de modelo de cada vez e para aí. Nunca chama uma ferramenta por si própria, nunca entra em ciclo, e nunca vê o resultado de uma chamada de ferramenta a não ser que o envie de volta num pedido subsequente. O seu próprio código é dono de todo o ciclo de execução: decidir se deve realmente executar o que o modelo pediu, executá-lo, e continuar a conversa com o resultado.
Definir ferramentas
Passe um array tools no pedido, usando o mesmo formato que a API de function-calling da OpenAI usa:
{
"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 mais do que possa parecer: é a única informação que o modelo tem sobre o que uma ferramenta faz e quando é apropriado recorrer a ela. Uma descrição vaga ou em falta leva a que uma ferramenta seja chamada nos momentos errados, ou não seja chamada quando devia. parameters é um objeto JSON Schema que descreve os argumentos que a ferramenta aceita; os próprios argumentos do modelo numa chamada de ferramenta são gerados para corresponder a esse esquema.
Receber uma chamada de ferramenta
Quando o modelo decide chamar uma ferramenta em vez de responder diretamente, o finish_reason da resposta é "tool_calls" e message.tool_calls é preenchido em vez de (ou junto com) 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 é uma string codificada em JSON, não um objeto aninhado; interprete-a antes de a usar. O modelo pode pedir mais do que uma chamada de ferramenta no mesmo turno se o pedido tiver várias ferramentas definidas e a tarefa assim o exigir, pelo que tool_calls é sempre um array, mesmo quando contém exatamente uma entrada.
Em modo streaming, a mesma informação chega como um chunk delta.tool_calls seguido de um chunk final com "finish_reason": "tool_calls"; consulte Streaming para os formatos gerais de chunk sobre os quais isto assenta.
Executá-la e continuar a conversa
O que acontece a seguir é inteiramente decisão do seu código. Decida se a chamada pedida é algo que está disposto a executar (este é exatamente o ponto em que uma aplicação tipicamente aplica o seu próprio modelo de permissões, sandboxing, ou confirmação do utilizador, antes de executar seja o que for). Se a executar, envie o resultado de volta como uma nova mensagem com role: "tool", referenciando a chamada original pelo seu 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 */]
}
O modelo continua então a partir daí, normalmente respondendo à pergunta original usando o resultado da ferramenta, embora também possa pedir outra chamada de ferramenta se a tarefa precisar disso. Continue a enviar o mesmo array tools em todos os pedidos da conversa, não apenas no primeiro; o modelo não tem memória de que ferramentas estavam disponíveis num turno anterior, além do que está no pedido atual.
Recusar executar uma chamada
Nada o obriga a executar de facto o que o modelo pediu. Se decidir não o fazer (o pedido está fora do âmbito, precisa de confirmação que ainda não tem, ou simplesmente não é algo que a sua aplicação suporte), envie uma mensagem tool a explicar isso em vez de um resultado real, e o modelo terá isso em conta na sua próxima resposta, tipicamente explicando a limitação ao utilizador em vez de assumir que a ação aconteceu.
Porquê este design, especificamente
Algumas frameworks de agentes integram a execução de ferramentas na própria chamada à API: regista uma ferramenta uma vez, e a infraestrutura do próprio fornecedor executa-a internamente, em ciclo até uma resposta final estar pronta. A tAI deliberadamente não faz isto para as suas próprias ferramentas personalizadas. As suas ferramentas são coisas que só o seu código sabe como executar, muitas vezes tocando na sua própria infraestrutura, nas suas próprias credenciais, no seu próprio sistema de ficheiros; não há forma de a tAI as executar em segurança mesmo que o quisesse. O que a tAI fornece em vez disso é exatamente uma coisa: a decisão de quando uma ferramenta deve ser chamada e com que argumentos, produzida a partir de um único turno do modelo. Tudo o que vem depois disso, execução, ciclos, proteção contra uma sequência descontrolada de chamadas, é inteiramente responsabilidade da sua aplicação, com exatamente o grau de cautela e delimitação apropriado para o que as suas ferramentas podem realmente fazer.