Chamadas de Funções com IA

Ao usar assistentes de IA na Turn.io, você pode definir uma lista de funções personalizadas que o modelo pode chamar. Essas funções precisam ser expostas por você em um endpoint HTTP, e a Turn.io chamará seu endpoint sempre que o assistente de IA decidir chamar uma das funções que você definiu.

A saída de texto da chamada da função será encaminhada ao assistente de IA e adicionada ao contexto que ele usa para gerar sua resposta.

Por exemplo, você pode definir uma função chamada get_weather e o assistente de IA chamará essa função sempre que o usuário quiser saber a previsão do tempo.

Definição de Função

Você pode definir a lista de funções disponíveis na página de Configurações de IA na Turn.io. As funções são definidas como uma lista de objetos JSON, onde cada objeto define as propriedades de uma função.

Uma função inclui três parâmetros principais: name, description e parameters. O parâmetro description orienta o modelo sobre quando e como invocar a função, por isso é crucial fornecer uma explicação clara e concisa sobre o propósito da função.

O parâmetro parameters é um objeto JSON schema que define os parâmetros que a função pode aceitar.

Por exemplo, o seguinte JSON define uma função chamada get_weather com um argumento obrigatório location e um argumento opcional unit. De acordo com a descrição, a função retornará o clima atual no local fornecido.

[
  {
    "description": "Retorna o clima atual para a localização especificada",
    "name": "get_weather",
    "parameters": {
      "properties": {
        "location": {
          "description": "A cidade e estado, por exemplo, São Francisco, CA",
          "type": "string"
        },
        "unit": {
          "enum": ["c", "f"],
          "type": "string"
        }
      },
      "required": ["location"],
      "type": "object"
    }
  }
]

Endpoint HTTP para Chamadas de Funções

A Turn.io enviará uma requisição HTTP POST para o endpoint da API que você especificou na página de Configurações de IA sempre que o assistente de IA decidir chamar uma das funções que você definiu. É vital que seu endpoint responda rapidamente; caso contrário, a conversa parecerá lenta para o usuário. Se seu endpoint não responder em menos de 10 segundos, a requisição será interrompida e uma saída vazia será passada para o assistente de IA.

A requisição POST da Turn.io conterá uma assinatura HMAC no header X-Turn-Hook-Signature. É importante que você verifique essa assinatura para garantir que a requisição foi realmente enviada pela Turn.io e que seu payload não foi adulterado. Consulte o exemplo abaixo para mais instruções sobre como verificar a assinatura. O segredo HMAC necessário para calcular a assinatura pode ser encontrado na página de configurações de IA.

O corpo da requisição conterá as seguintes chaves:

• function_name: O nome da função que o assistente de IA deseja chamar.
• function_args: Os argumentos que o assistente de IA decidiu passar para a função.
• context: Um contexto fornecido pela Turn.io (e não pelo assistente de IA) que contém informações úteis sobre o Contato que está enviando mensagens ao assistente de IA. Este contexto deve ser usado como a única fonte confiável quando você precisar identificar o Contato e acessar seus campos de perfil. Os argumentos fornecidos pelo assistente de IA (function_args) não podem ser confiáveis para fins de autenticação, pois os assistentes de IA são suscetíveis a alucinações e ataques de injeção de prompt.
• tool_call_id: O ID da chamada da função, que pode ser útil para fins de depuração.

Aqui está um exemplo do corpo JSON quando o assistente de IA decide chamar uma função como parte de uma execução de Jornada:

{
  "function_name": "get_weather",
  "function_args": {
    "location": "San Francisco, CA"
  },
  "wa_id": "+16506001008",
  "tool_call_id": "call_iIlPzTvI1DN00000yo0z5Rx",
  "context": {
    "context_type": "journey",
    "journey_uuid": "b5ddb14c-1ecb-49dd-a54d-1c343364e9e7",
    "contact": {
      "birthday": null,
      "first_message_received_at": "2024-04-30T09:18:12Z",
      "is_blocked": false,
      "language": null,
      "last_message_received_at": "2024-05-29T08:14:41Z",
      "last_message_sent_at": "2024-05-28T17:38:21.284541Z",
      "last_seen_at": "2024-05-29T08:14:41Z",
      "location": null,
      "name": null,
      "opted_in": false,
      "opted_in_at": null,
      "surname": null,
      "whatsapp_id": "16506001008",
      "whatsapp_profile_name": "Contact Name",
      "your_custom_profile_field_1": "value 1",
      "your_custom_profile_field_2": "value 2"
    }
  }
}

Exemplo em Python

O código Python a seguir mostra como você pode construir um endpoint HTTP que manipula as requisições de Chamadas de Funções do assistente de IA.

import base64
import hmac
from hashlib import sha256

from flask import Flask, request

app = Flask(__name__)

# Obtenha isso na página de configurações de IA da Turn.io
TURN_HMAC_SECRET = b'COLE-O-SEGREDO-AQUI'


@app.route('/')
def index():
    return 'Um olá da Flask!'


@app.route('/function-calling', methods=['POST'])
def function_calling():
    # Extraia a assinatura dos headers da solicitação
    request_signature = request.headers.get('X-Turn-Hook-Signature')

    # Calcule a assinatura do corpo da solicitação
    raw_request_body = request.get_data()
    hmac_object = hmac.new(TURN_HMAC_SECRET, raw_request_body, sha256)
    computed_signature = base64.b64encode(hmac_object.digest())

    # Verifique a assinatura
    if computed_signature.decode('ascii') != request_signature:
        print(f'Assinatura inválida: {request_signature}')
        print(f'Assinatura calculada é: {computed_signature}')
        return 'Assinatura inválida', 403

    # Obtenha o corpo JSON da solicitação
    request_body = request.get_json()
    print(request_body)

    # Extraia o nome da função, os argumentos e o contexto
    function_name = request_body.get('function_name')
    args = request_body.get('function_args')
    context = request_body.get('context')
    print(
        f'Função {function_name} foi chamada com os argumentos {args} e contexto {context}'
    )

    # Trate a chamada da função
    match function_name:
        case 'get_weather':
            return {'output': get_weather(args, context)}

        case 'some_other_function':
            return {'output': some_other_function(args, context)}

        case _:
            return {'output': 'Essa função não é suportada.'}


def get_weather(args, context):
    location = args.get('location')

    # Sempre obtenha o ID do WhatsApp do Contato a partir do contexto,
    # não confie nos argumentos fornecidos pelo assistente de IA para autenticar
    # o usuário.
    whatsapp_id = context.get('wa_id')
    print('WhatsApp ID', whatsapp_id)

    contact = context.get('contact', {})
    name = contact.get('name')
    print('Nome do contato', name)

    return f'O clima de {location} é ensolarado and está 22 graus'


def some_other_function(args, context):
    return 'Resultado de alguma outra função'


if __name__ == '__main__':
    app.run(host='0.0.0.0', port=5000)