Use a ferramenta de funções

  • 5 minutos

A ferramenta de funções permite que o seu modelo chame funções definidas pelo programador para recuperar dados ou desencadear ações durante uma resposta.

Qual é a ferramenta funcional?

A ferramenta de função (chamada de função) permite que um modelo decida quando chamar ferramentas nomeadas que expõe na sua aplicação. O modelo não executa diretamente a sua lógica de negócio. Em vez disso, devolve uma chamada de função estruturada, o seu código executa a função e depois passa a saída da função de volta ao modelo.

Este padrão é ideal para ligar o raciocínio do modelo a sistemas do mundo real como APIs, bases de dados, fluxos de trabalho empresariais e funções utilitárias.

Os principais recursos incluem:

  • Chamadas estruturadas de ferramentas - O modelo emite pedidos explícitos de chamadas de função
  • Execução controlada pelo programador - A sua aplicação decide como e onde as funções correm
  • Padrão de integração fiável - Chamar APIs, serviços internos ou utilitários auxiliares de forma segura
  • Orquestração de múltiplas voltas - Devolver a saída da ferramenta e deixar o modelo continuar a raciocinar
  • Respostas fundamentadas - As respostas podem incluir dados em tempo real, gerados pelo sistema

Casos comuns de utilização

Caso de uso Exemplo
Integração de Sistemas Ligue para uma API interna para detalhes da conta ou da encomenda
Automação de Tarefas Ativar fluxos de trabalho como criação de tickets ou notificações
Pesquisa de Dados Consulte regras de negócio ou tabelas de referência antes de responder

Um exemplo simples

Aqui está um exemplo que expõe uma get_time função e permite ao modelo chamá-la quando necessário:

import time
from openai import OpenAI

# Function to get the current time
def get_time():
    return f"The time is {time.strftime('%Y-%m-%d %H:%M:%S', time.localtime())}"


# Main function
def main():
    client = OpenAI(
        base_url={openai_endpoint},
        api_key={auth_key_or_token}
    )

    function_tools = [
        {
            "type": "function",
            "name": "get_time",
            "description": "Get the current time"
        }
    ]

    # Initialize messages with a system prompt
    messages = [
        {"role": "developer", "content": "You are an AI assistant that provides information."},
    ]

    # Loop until the user types 'quit'
    while True:
        prompt = input("\nEnter a prompt (or type 'quit' to exit)\n")
        if prompt.lower() == "quit":
            break

        # Append the user prompt to the messages
        messages.append({"role": "user", "content": prompt})

        # Get initial response
        response = client.responses.create(
            model=model_deployment,
            input=messages,
            tools=function_tools
        )

        # Append model output to the messages
        messages += response.output

        # Was there a function call?
        for item in response.output:
            if item.type == "function_call" and item.name == "get_time":
                current_time = get_time()
                messages.append({
                    "type": "function_call_output",
                    "call_id": item.call_id,
                    "output": current_time
                })

                # Get a follow up response using the tool output
                response = client.responses.create(
                    model=model_deployment,
                    instructions="Answer only with the tool output.",
                    input=messages,
                    tools=function_tools
                )

        print(response.output_text)


# Run the main function when the script starts
if __name__ == '__main__':
    main()

Neste fluxo, o modelo decide quando chamar get_time, o seu código executa a função, e o modelo devolve então uma resposta final fundamentada. Como o utilizador pode introduzir qualquer prompt, o modelo deve determinar quando precisa de chamar a função. Se o fizer, a resposta ao prompt incluirá uma chamada de função, que o código da aplicação deve implementar antes de submeter um novo prompt com o resultado da função para o modelo processar.

O resultado pode parecer algo assim:

Enter a prompt (or type 'quit' to exit)
Hello

Hello! How can I help you today?

Enter a prompt (or type 'quit' to exit)
What time is it?

The time is 2026-03-19 17:17:41.

Enter a prompt (or type 'quit' to exit)

O primeiro prompt de utilizador ("Olá") não exigia o uso da ferramenta de função, por isso o modelo respondeu normalmente. O segundo prompt ("Que horas são?") levou o modelo a selecionar a função get_time, o que foi indicado na sua resposta. O código da aplicação executava então a função e devolveu os resultados ao modelo, que enviou uma segunda resposta com os resultados da função.

Sugestão

Este exemplo utiliza uma única função sem parâmetros. Pode configurar a ferramenta para usar múltiplas funções, com ou sem parâmetros. Para mais informações sobre como especificar detalhes da função, consulte o guia para desenvolvedores da OpenAI.

Como funciona a ferramenta de funções

O processo geral para utilizar a ferramenta de função é:

  1. Define ferramentas - Fornece uma ou mais definições de funções no array de ferramentas.
  2. O modelo avalia o prompt - Determina se é necessária uma chamada de função.
  3. O modelo emite uma chamada de função - A resposta inclui o nome da função e os metadados da chamada.
  4. A tua aplicação executa lógica - Executa a função de correspondência no teu código.
  5. Devolves a saída da função - Envias um function_call_output item com o resultado.
  6. O modelo completa a resposta - Incorpora os resultados da ferramenta na resposta final.

Melhores práticas

  • Mantém as ferramentas focadas – Funções pequenas e de propósito único são mais fáceis de controlar e testar
  • Validar entradas de funções - Nunca confiar cegamente nos argumentos das ferramentas em sistemas de produção
  • Lidar com erros de forma segura - Devolver resultados de erro claros sobre os quais o modelo pode raciocinar
  • Utilização de ferramentas de registo - Rastrear chamadas, latência e taxas de falha para depuração e governação
  • Limitar operações sensíveis - Requer autorização explícita para ações de alto impacto

Limitações a conhecer

  • O modelo pede chamadas de função, mas a sua aplicação tem de as executar
  • Argumentos incorretos ou inesperados sobre ferramentas podem ocorrer e devem ser validados
  • A latência da ferramenta pode aumentar o tempo de resposta de ponta a ponta
  • A chamada de funções melhora a fiabilidade, mas as saídas finais ainda precisam de revisão para decisões críticas

Bem utilizada, a ferramenta de funções transforma um modelo de gerador de texto num orquestrador que pode interagir com sistemas reais de forma controlada e auditável.