Gerar resposta do modelo

Obtém uma resposta de texto de um modelo de IA conforme o prompt do usuário.

Opções

• Nome da conta é uma expressão de texto para o nome da conta de IA a ser usada. No arquivo atual, use a etapa de script Etapa de script Configurar a conta de IA para configurar a conta e atribuir esse nome a ela antes que a etapa de script seja executada.

• Modelo é o nome do modelo de geração de texto a ser usado. Especifique o nome do modelo como uma expressão de texto. Para modelos compatíveis, consulte Especificações técnicas do FileMaker.

• Prompt do usuário é uma expressão de texto para a solicitação ou pergunta em linguagem natural para enviar ao modelo, que geralmente é a solicitação feita pelo usuário.

• Modo Agentic controla como esta etapa de script lida com interações automatizadas de ferramentas:

  • Ativado: permite a interação automatizada em várias etapas, onde o modelo pode chamar ferramentas repetidamente até atingir um resultado final.

  • Desativado: executa uma única interação e para após a primeira chamada de ferramenta sem executar a chamada de ferramenta ou retornar um resultado na Resposta, permitindo manuseio e depuração manuais. Se nenhuma chamada de ferramenta for feita, retorna o resultado do modelo na Resposta.

• Resposta especifica o campo ou variável onde o resultado da etapa de script deve ser armazenado. Se você especificar um campo e selecionar Fluxo, o campo deverá estar no layout atual.

• Instruções é uma expressão de texto que fornece contexto adicional ou diretrizes comportamentais para o modelo.

• Mensagens especifica o campo ou a variável que contém o histórico de mensagens para fornecer ao modelo o contexto de interações anteriores. As mensagens são uma matriz de objetos JSON. Cada objeto JSON deve conter pares chave-valor para o texto da mensagem (conteúdo) e quem forneceu o conteúdo (função), o usuário ("usuário") ou o modelo ("assistente"). Por exemplo:

  Copiar

  [ 
    {
      "content": "Qual é a temperatura em Cupertino?",
      "role": "user"
    },
    {
      "content": "A temperatura em Cupertino é de 72 graus Fahrenheit.",
      "role": "assistant"
    }
  ]

• Salvar histórico de mensagens em especifica a variável onde a etapa de script armazena o histórico de mensagens. O formato é o mesmo de Mensagens, com o par de mensagens da execução atual desta etapa de script adicionado ao final.

  Se você quiser que o histórico de mensagens persista após o término do script atual, use uma variável global (que persiste até que a sessão do cliente FileMaker termine) ou armazene o valor da variável em um campo. Consulte Utilização de variáveis ou a etapa de script Etapa de script Definir campo.

• Contagem do histórico de mensagens é uma expressão numérica que controla o número de pares de mensagens anteriores (pergunta do usuário e resposta do assistente) a serem incluídas na variável especificada por Salvar histórico de mensagens em.

• Temperatura controla a aleatoriedade ou criatividade da resposta de um modelo a um prompt. Valores baixos produzem resultados mais determinísticos e factuais. Valores altos geram resultados mais criativos, inesperados ou menos coerentes. Consulte a documentação do provedor do modelo para obter os intervalos válidos para o modelo específico que você está usando.

• Definições da ferramenta especifica uma matriz JSON de ferramentas disponíveis que o modelo pode chamar durante o processamento. Veja "Definições da ferramenta" abaixo.

• Chamadas da ferramenta do modelo especifica onde armazenar informações sobre as chamadas de ferramentas feitas pelo modelo. Isso pode ser útil para depuração ou para auditar o uso de ferramentas pelo modelo.

• Fluxo controla como a resposta é fornecida:

  • Ativado: a resposta é recuperada e entregue de forma incremental (palavra por palavra ou em frases). Isso pode fazer com que o cliente FileMaker pareça mais responsivo.

  • Desativado: toda a resposta é recuperada antes de ser disponibilizada. Isso pode fazer com que o cliente FileMaker pareça não responder enquanto aguarda a resposta completa.

• Parâmetros é uma expressão de texto para um objeto JSON que consiste em pares chave-valor para parâmetros adicionais que são suportados pelo provedor do modelo. Por exemplo: {"temperature": 0,7, "seed": 42}. Consulte a documentação do provedor do modelo para obter nomes de parâmetros suportados e seus intervalos válidos.

• Executar JavaScript no Visualizador da Web especifica o código JavaScript para executar em um Visualizador da Web de destino após a conclusão da etapa de script. Essa opção é semelhante à execução da etapa de script Etapa de script Executar JavaScript no Visualizador da Web como a próxima etapa de script, exceto que a resposta pode ser passada para a função JavaScript e transmitida para o visualizador da Web quando a opção Fluxo está Ativada.

  • Visualizador da Web especifica o nome do objeto de um visualizador da Web no layout atual.

  • Nome da função é o nome da função JavaScript a ser chamada no visualizador da Web.

Originada na versão

22.0

Descrição

Essa etapa de script facilita a interação em várias etapas entre seu app personalizado e os modelos de IA, permitindo que o modelo acesse e manipule dados por meio de chamadas de ferramentas quando necessário. A etapa de script opera em dois modos distintos com base na opção Modo Agentic, sendo que cada um fornece diferentes níveis de automação e controle sobre a interação.

A interação entre essa etapa de script e o modelo normalmente segue estas etapas:

1. Essa etapa de script envia o Prompt do usuário, as Instruções, o contexto da conversa por meio de Mensagens e as Definições da ferramenta disponíveis para o Modelo configurado.

2. O modelo analisa o prompt e determina se ele pode fornecer uma resposta direta ou se precisa usar ferramentas para coletar informações adicionais ou executar ações.

3. Se as ferramentas forem necessárias, o modelo gera chamadas de ferramentas com parâmetros apropriados com base nas definições de ferramentas disponíveis e na solicitação do usuário.

4. Essa etapa de script recebe as chamadas de ferramenta do modelo e o cliente FileMaker as executa. A execução de ferramentas pode incluir as ferramentas predefinidas, como consultas SQL ou chamadas para suas próprias funções personalizadas.

5. Essa etapa de script envia os resultados da execução da ferramenta de volta ao modelo, fornecendo os dados ou a confirmação necessária para continuar o processamento.

6. Se o modelo determinar que ferramentas adicionais são necessárias para abordar totalmente o prompt, ele pode gerar mais chamadas de ferramentas (repetindo as etapas 3 a 5). Esse processo iterativo continua até que o modelo tenha informações suficientes para fornecer uma resposta abrangente.

7. Depois que o modelo conclui todas as interações necessárias com a ferramenta, ele gera uma resposta final que incorpora os resultados da ferramenta e aborda o prompt original do usuário.

8. Essa etapa de script recebe a resposta final, armazena-a no Destino de resposta especificado e, opcionalmente, atualiza o histórico de interações em Salvar histórico de mensagens em.

A opção Modo Agentic determina como a interação é tratada:

• Ativado: permite a interação automatizada de várias etapas com as ferramentas, executando o fluxo de trabalho completo (etapas 1 a 8) automaticamente. Quando o modelo de IA determina que ferramentas são necessárias para atender à solicitação, ele automaticamente chama as ferramentas apropriadas e continua o processamento até atingir um resultado final. O modelo pode fazer várias rodadas de chamadas de ferramentas conforme necessário, sendo que cada rodada se baseia nos resultados de execuções de ferramentas anteriores. Este modo é para tarefas complexas que exigem várias interações com ferramentas, como analisar dados em várias tabelas, gerar relatórios ou executar operações em várias etapas.

• Desativado: realiza uma única interação com o modelo de IA, executando apenas as etapas 1 a 3 e parando após a primeira chamada de ferramenta. Se o modelo determinar que ferramentas são necessárias, a etapa de script para e retorna as informações da chamada de ferramenta em Chamadas da ferramenta do modelo em vez de executar as ferramentas automaticamente. Esse modo é útil para depurar interações de ferramentas, entender quais ferramentas o modelo deseja usar ou quando você precisa ter controle manual sobre a execução das ferramentas. Você pode examinar as chamadas de ferramentas e decidir se as executa manualmente ou modifica a abordagem.

O fluxo de informações entre esta etapa de script e o modelo garante que dados confidenciais permaneçam seguros enquanto possibilitam a funcionalidade da IA. O modelo recebe apenas as informações explicitamente fornecidas por meio de prompts, instruções e resultados de ferramentas; ele não tem acesso direto ao seu banco de dados ou aos arquivos do FileMaker. As chamadas de ferramentas são executadas dentro do ambiente controlado do FileMaker. Assim, você mantém controle total sobre o acesso e as operações de dados por meio de contas e privilégios do FileMaker, aproveitando os recursos analíticos e lógicos do modelo.

Definições da ferramenta

O Uso da ferramenta (também conhecido como chamada de função por alguns provedores de modelo) permite que o modelo chame novamente seu app FileMaker Pro para fazer ou fornecer algo que o modelo precisa para gerar sua resposta final. No modo Agentic, o modelo pode chamar várias ferramentas repetidamente até concluir. Na opção Definições da ferramenta, você pode definir as seguintes ferramentas:

• execute_sql: uma ferramenta predefinida que executa a consulta SQL especificada, capaz de executar uma instrução SQL passada pelo modelo da mesma forma que a etapa de script Etapa de script Executar Consulta SQL por Linguagem Natural.

• retrieve_image: uma ferramenta predefinida que recupera uma imagem do campo de container especificado por uma consulta SQL, nome da tabela e nome do campo do container.

• Funções personalizadas: quaisquer funções personalizadas definidas em seu arquivo. Veja Uso de funções personalizadas.

As definições da ferramenta são especificadas usando o formato JSON exigido pelo provedor do modelo. Em geral, a definição é uma matriz de objetos em que cada objeto especifica o nome de uma ferramenta, uma descrição detalhada do que a ferramenta faz e quais regras o modelo deve seguir ao usá-la e, para cada parâmetro de entrada, seu nome, tipo de dados e descrição. As descrições devem ser tão detalhadas quanto necessário para que o modelo use a ferramenta de forma confiável. Se você usar as ferramentas predefinidas, comece usando as definições fornecidas abaixo. Se necessário, modifique-as para obter os melhores resultados para os modelos que você usa.

Para ajudá-lo a depurar suas definições de ferramentas, defina a opção Chamadas da ferramenta do modelo para um campo ou variável que permita ver como ou se o modelo chamou as ferramentas. Isso pode ajudar a revelar o que você pode precisar adicionar ou alterar nas descrições fornecidas nas definições da ferramenta.

Para o formato JSON específico usado para definições de ferramentas e chamadas de ferramentas, consulte a documentação do provedor de modelo — por exemplo, Anthropic, Cohere e OpenAI.

execute_sql

Retorna: o resultado da consulta SQL como uma string.

retrieve_image

Retorna: dados JSON no formato abaixo, contendo a imagem como uma string codificada em Base64.

[
  {
    "dados": "/9j/4AAQ...//2Q=="
  }
]

Funções personalizadas

Siga estas diretrizes de definição de ferramenta para chamar funções personalizadas:

• Para a função:

  • Na chave nome, use exatamente o nome da função personalizada, conforme definido na caixa de diálogo Editar função personalizada.

  • Na chave descrição, forneça uma descrição detalhada do que a função personalizada faz e quais regras o modelo deve seguir ao usá-la.

• Para os parâmetros:

  • Defina exatamente o mesmo número de parâmetros e na mesma ordem dos parâmetros definidos na caixa de diálogo Editar função personalizada. Os nomes dos parâmetros não precisam ser os mesmos.

  • Na chave descrição, forneça uma descrição detalhada do que o modelo deve fornecer no parâmetro.

  • Defina o valor da chave tipo como "string" (os parâmetros são sempre tratados como texto).

Notas

• Mensagens de erro comuns incluem "Não existe chamada de ferramenta para o prompt" quando o modelo não consegue determinar as ferramentas apropriadas para usar e "Função não encontrada" quando uma definição de ferramenta faz referência a uma função personalizada que não existe.

Exemplo 1

Configura uma conta de IA, vai para o layout Contatos e exibe uma caixa de diálogo para o usuário inserir uma pergunta. A etapa de script Gerar resposta do modelo envia o prompt e o histórico de mensagens recentes para o modelo e transmite o resultado para o campo Resposta. Para uma interação simples de perguntas e respostas como esta, o Modo Agentic não foi selecionado. Para manter o contexto com o modelo durante a sessão atual do cliente FileMaker, a etapa de script armazena as 10 mensagens mais recentes na variável global $$Messages por meio da opção Salvar histórico de mensagens em. Por meio da opção Mensagens, a etapa de script envia o valor da variável $$Messages para o modelo quando o script é executado posteriormente na mesma sessão. Como a opção Definições da ferramenta não é usada, o modelo não poderá responder a perguntas sobre seus dados.

Configurar conta de IA [ Nome da conta: "minha-conta" ; Provedor do modelo: OpenAI ; Chave de API: Global::API_Key ] 

Ir para layout [ "Contatos" (Contatos) ]

Mostrar caixa de diálogo personalizada [ "Digite uma pergunta" ; $UserPrompt ]

Gerar resposta do modelo [ Nome da conta: "minha-conta" ; Modelo: Global::ModelName ; Prompt do usuário: $UserPrompt ; Resposta: Contatos::Resposta ; Mensagens: $$Mensagens ; Salvar histórico de mensagens em: $$Mensagens ; Contagem do histórico de mensagens: 10 ; Fluxo ]

Exemplo 2

Configura uma conta de IA, vai para o layout Contatos e, em seguida, envia um prompt perguntando sobre dados na tabela Contatos para o modelo, que usa ferramentas para gerar uma resposta. Como até 10 mensagens são salvas via $$Messages no campo global Mensagens, o contexto é preservado nas sessões do cliente FileMaker.

Configurar a conta de IA [ Nome da conta: "minha-conta" ; Provedor de modelos: OpenAI ; Chave de API: Global::API_Key ] 

Ir para layout [ "Contatos" (Contatos) ]

Definir variável [ $Instructions ; Valor: "Você é um assistente útil que pode consultar informações de banco de dados. Sempre forneça respostas claras e formatadas." ]

Definir variável [ $UserPrompt ; "Quantos contatos temos da Acme Anvils, e quais são seus nomes e endereços de email? Adicione um asterisco após os contatos que estão localizados em uma cidade onde temos um escritório de vendas." ]

Gerar resposta do modelo [ Nome da conta: "minha-conta" ; Modelo: Global::ModelName ; Prompt do usuário: $UserPrompt ; Resposta: Contatos::Resposta ; Chamadas da ferramenta do modelo: $$ToolCalls ; Instruções: $Instructions ; Mensagens: Global::Mensagens ; Salvar histórico de mensagens em: $$Mensagens ; Contagem do histórico de mensagens: 10 ; Definições da ferramenta: Global::ToolDefinitions ; Fluxo ]

Definir campo [ Global::Mensagens ; $$Messages ]

O campo ToolDefinitions contém o seguinte usando o formato JSON para o provedor de modelo OpenAI:

[
  {
    "function": {
      "description": "Respond to the user’s questions by executing the appropriate SQL query using this function. Strictly follow these rules:\r 1. The input should be a fully formed SQL query.\r 2. Perform separate SQL instead of one nested SQL.\r 3. Escaping special characters for SQL query.\r 4. If the result of the toolCall is a raw string that reads 'empty' or 'null', the answer should contain the quoted raw string, which is case sensitive.\r 5. Convert the user’s request into an SQL query using standard SQL syntax only. Ensure that table names and field names match exactly as they appear in the database schema.",
        "name": "execute_sql",
        "parameters": {
          "properties": {
            "sql_query": {
              "description": "Generate a fully formed SQL query based on following rules:\r 1. Enclose all table and field names in double quotes.\r 2. Format dates as \"DATE 'YYYY-MM-DD'\", times as \"TIME 'HH:MM:SS'\" and timestamps as \"TIMESTAMP 'YYYY-MM-DD HH:MM:SS'\".\r 3. Return queries in plain text (not JSON).\r 4. Use \"FETCH FIRST n ROW ONLY\" instead of \"LIMIT\".\r 5. Support single queries only.\r 6. No semicolon is needed at the end of SQL query.\r 7. Don't generate nested SQL queries.\r 8. Use \"LIKE\" instead of \"ILIKE\".\r 9. Keep all comparisons case-sensitive.\r 10. Do not include fields that are not included in the question.\r 11. Use unquoted ROWID in queries.\r 12. Only utilize the following database schema:\rCREATE TABLE \"Contacts\" (\r\"First Name\" varchar(255),\r\"Last Name\" varchar(255),\r\"Email\" varchar(255),\r\r\"City\" varchar(255),\r\"Company\" varchar(255)\r);\r\r",
              "type": "string"
            }
          },
          "type": "object",
          "required": ["sql_query"]
        }
      },
      "type": "function"
  },
  {
    "function": {
      "description": "Verifica se nossa empresa tem um escritório de vendas em uma cidade específica. Se isso acontecer, essa função retorna 'sim'; caso contrário, retorna 'não'.",
        "name": "CityHasSalesOffice",
        "parameters": {
          "properties": {
            "city": {
              "description": "O nome de uma cidade",
              "type": "string"
            }
          },
          "type": "object",
          "required": ["city"]
        }
      },
      "type": "function"
  }
]

Para execute_sql, use a descrição da função e a descrição do parâmetro fornecidas acima. No parâmetro sql_query, use a descrição fornecida acima, seguida pelo esquema para a tabela Contatos.

A função personalizada CityHasSalesOffice retorna "sim" ou "não", dependendo se a cidade especificada tem um escritório de vendas.

Possível resposta transmitida para o campo Resposta:

Temos 4 contatos na Acme Anvils. Aqui estão os nomes, endereços de email e um asterisco indicando se estão em uma cidade com um escritório de vendas:

1. Alea Marks, aleamarks165@example.com
2. Kelly Holden, kellyholden1361@example.com *
3. Kelsey Cummings, kelseycummings1396@example.com
4. Kuame Savage, kuamesavage7146@example.com

A variável $$ToolCalls contém várias chamadas para execute_sql e CityHasSalesOffice.

[
  {
    "índice": 0,
    "id": "call_e7...",
    "tipo": "função",
    "função": {
      "nome": "execute_sql",
      "argumentos": "{\"sql_query\":\"SELECIONAR CONTAGEM(*) DE \\\"Contatos\\\" ONDE \\\"Empresa\\\" = 'Acme Anvils'\"}"
    }
  },
  {
    "índice": 0,
    "id": "call_o0...",
    "tipo": "função",
    "função": {
      "nome": "execute_sql",
      "argumentos": "{\"sql_query\":\"SELECIONAR \\\"Nome\\\", \\\"Sobrenome\\\", \\\"Email\\\", \\\"Cidade\\\" DE \\\"Contatos\\\" ONDE \\\"Empresa\\\" = 'Acme Anvils'\"}"
    }
  },
  {
    "índice": 0,
    "id": "call_ev...",
    "tipo": "função",
    "função": {
      "nome": "CityHasSalesOffice",
      "argumentos": "{\"cidade\": \"Onitsha\"}"
    }
  },
  {
    "índice": 1,
    "id": "call_IC...",
    "tipo": "função",
    "função": {
      "nome": "CityHasSalesOffice",
      "argumentos": "{\"cidade\": \"Berlim\"}"
    }
  },
  {
    "índice": 2,
    "id": "call_Pw...",
    "tipo": "função",
    "função": {
      "nome": "CityHasSalesOffice",
      "argumentos": "{\"cidade\": \"Saint-Malo\"}"
    }
  },
  {
    "índice": 3,
    "id": "call_Uy...",
    "tipo": "função",
    "função": {
      "nome": "CityHasSalesOffice",
      "argumentos": "{\"cidade\": \"Wanneroo\"}"
    }
  }
]

Tópicos relacionados

• Etapa de script Configurar a conta de IA

• Etapa de script Executar JavaScript no Visualizador da Web

• Função GetTableDDL

• Sobre funções personalizadas

• Referência de etapas de script