Skip to content

MessageBag

A classe MessagesBag é um contêiner para gerenciar coleções de mensagens em uma conversa. Ela fornece métodos para adicionar, recuperar e manipular mensagens dentro de um contexto de chat.

Criando um MessageBag

Você pode criar um novo MessageBag de duas maneiras:

php
// Criar um MessageBag vazio
$messages = MessagesBag::create();

// Criar um MessageBag com mensagens iniciais
$messages = MessagesBag::create([
    Message::assistant('Estou bem! Como posso ajudá-lo hoje?')
    Message::user('Olá, como você está?')
]);

Adicionando Mensagens

Você pode adicionar novas mensagens a um MessageBag:

php
// Adicionar uma mensagem do usuário
$messages->add(Message::user('Qual é a capital da França?'));

// Adicionar uma mensagem do assistente
$messages->add(Message::assistant('A capital da França é Paris.'));

Limitando Mensagens

Você pode limitar o número de mensagens em uma conversa mantendo o contexto:

php
// Limitar às últimas 5 mensagens em ordem decrescente (mais recentes primeiro)
$messages->limit(5);

// Limitar às primeiras 5 mensagens em ordem crescente (mais antigas primeiro)
$messages->limit(5, 'asc');

TIP

Ao usar limit() com chamadas de função, se a última mensagem for uma chamada de função, a resposta da função será automaticamente incluída para manter o fluxo lógico da conversa. Isso significa que você pode receber um pouco mais de mensagens que o limite se forem respostas de funções.

Exemplo com chamadas de função:

php
// Conversa original com chamadas de função
$messages = MessagesBag::create([
    Message::user('Qual é o clima?'),
    Message::assistant(null, [
        [
            'id' => 'call_123',
            'type' => 'function',
            'function' => [
                'name' => 'getWeather',
                'arguments' => '{}'
            ]
        ]
    ]),
    Message::tool('Ensolarado, 25°C', 'call_123'),
]);

// Limitar às últimas 2 mensagens
$messages->limit(2);
// O resultado incluirá todas as 3 mensagens porque a última mensagem
// é uma resposta de função que completa a chamada de função

WARNING

O uso de limit() reduz o contexto disponível para o LLM, o que pode afetar sua capacidade de manter conversas coerentes. É importante encontrar o equilíbrio certo entre custo (menos mensagens = custos menores) e qualidade do contexto. Considere:

  • Testar diferentes limites para encontrar o número ideal para seu caso de uso
  • Estar ciente de que limitar mensagens pode cortar conversas pela metade
  • Monitorar se o contexto reduzido afeta a qualidade das respostas
  • Usar técnicas como resumir o contexto anterior quando necessário

Removendo Chamadas de Ferramentas

Você pode remover todas as chamadas de função e suas respostas da conversa:

php
// Remover todas as chamadas de função e suas respostas
$messages->removeTools();

Isso é útil quando você quer:

  • Manter apenas respostas diretas do LLM e mensagens do usuário
  • Limpar a conversa antes de aplicar um limite
  • Focar no fluxo principal da conversa

Exemplo:

php
// Conversa original com chamadas de função
$messages = MessagesBag::create([
    Message::user('Qual é o clima?'),
    Message::assistant(null, [
        [
            'id' => 'call_123',
            'type' => 'function',
            'function' => [
                'name' => 'getWeather',
                'arguments' => '{}'
            ]
        ]
    ]),
    Message::tool('Ensolarado, 25°C', 'call_123'),
    Message::assistant('O clima está ensolarado hoje, com temperatura de 25°C. Um ótimo dia para atividades ao ar livre!'),
    Message::user('Ótimo! E amanhã?'),
    Message::assistant('Vou verificar a previsão para amanhã.'),
    Message::assistant(null, [
        [
            'id' => 'call_124',
            'type' => 'function',
            'function' => [
                'name' => 'getWeather',
                'arguments' => '{"day": "tomorrow"}'
            ]
        ]
    ]),
    Message::tool('Chuvoso, 20°C', 'call_124'),
    Message::assistant('Para amanhã, a previsão indica chuva e temperatura mais amena, em torno de 20°C. Seria bom levar um guarda-chuva se precisar sair.')
]);

// Remover todas as chamadas de função e suas respostas
$messages->removeTools();
// O resultado conterá apenas:
// - Usuário: "Qual é o clima?"
// - Assistente: "O clima está ensolarado hoje, com temperatura de 25°C. Um ótimo dia para atividades ao ar livre!"
// - Usuário: "Ótimo! E amanhã?"
// - Assistente: "Vou verificar a previsão para amanhã."
// - Assistente: "Para amanhã, a previsão indica chuva e temperatura mais amena, em torno de 20°C. Seria bom levar um guarda-chuva se precisar sair."

// Você pode então aplicar um limite se necessário
$messages->limit(2);

WARNING

Em agentes com grande interação com ferramentas, remover chamadas de ferramentas sem system prompts apropriados pode potencialmente enviesar o agente a responder sem usar ferramentas. Embora isso seja raro, é importante:

  • Testar como seu agente se comporta após remover chamadas de ferramentas
  • Considerar se seu caso de uso requer manter o histórico de chamadas de ferramentas
  • Usar system prompts apropriados para guiar o comportamento do agente
  • Monitorar se as respostas do agente mudam após remover chamadas de ferramentas

Gerenciando Conversas

O MessageBag facilita a manutenção do estado de uma conversa:

php
// Iniciar uma conversa
$messages = MessagesBag::create([
    Message::assistant('Estou bem! Como posso ajudá-lo hoje?')
]);

// Primeira pergunta do usuário
$messages->add(Message::user('O que é computação quântica?'));

// Enviar para o modelo e obter resposta
$execute = LabsLLM::text()
    ->using(new OpenAI('sua-chave-api', 'gpt-4o'))
    ->executeChat($messages);

$response = $execute->getResponseData();

// Obter o message bag atualizado
$messages = $execute->getMessagesBag();

// Usuário faz uma pergunta de acompanhamento
$messages->add(Message::user('Como ela é usada na criptografia?'));

// Enviar a conversa atualizada para o modelo
$execute = LabsLLM::text()
    ->using(new OpenAI('sua-chave-api', 'gpt-4o'))
    ->executeChat($messages);

// Obter a nova resposta
$response = $execute->getResponseData();
echo $response->response;

Convertendo para Array

Você pode converter o MessageBag para um formato de array para inspeção ou armazenamento:

php
// Obter todas as mensagens como um array
$messagesArray = $messages->toArray();

// Processar ou armazenar as mensagens
foreach ($messagesArray as $message) {
    echo $message['role'] . ': ' . $message['content'] . PHP_EOL;
}

Exportando e Importando Conversas

Você pode salvar e restaurar conversas usando JSON:

php
// Exportar conversa para JSON
$jsonHistory = $messages->asJson();

// Salvar em arquivo
file_put_contents('conversation_history.json', $jsonHistory);

// Ou salvar no banco de dados
// $db->query("INSERT INTO conversations (user_id, history) VALUES (?, ?)", [$userId, $jsonHistory]);

// Mais tarde, restaurar a conversa
$jsonHistory = file_get_contents('conversation_history.json');
// Ou do banco de dados
// $jsonHistory = $db->query("SELECT history FROM conversations WHERE user_id = ?", [$userId])->fetchColumn();

// Criar MessageBag a partir do JSON salvo
$messages = MessagesBag::createFromJson($jsonHistory);

// Continuar a conversa
$messages->add(Message::user('Me fale mais sobre portas quânticas.'));

$execute = LabsLLM::text()
    ->using(new OpenAI('sua-chave-api', 'gpt-4o'))
    ->executeChat($messages);

$response = $execute->getResponseData();
echo $response->response;

Trabalhando com Ferramentas

Ao usar ferramentas em uma conversa, o MessageBag ajuda a manter o contexto da chamada de ferramenta:

php
// Criar uma conversa com chamadas de ferramentas
$messages = MessagesBag::create([
    Message::assistant('Estou bem! Como posso ajudá-lo hoje?')
]);

$messages->add(Message::user('Qual é a data de hoje?'));

// O modelo pode responder com uma chamada de ferramenta
$assistantResponse = Message::assistant(null, [
    [
        'id' => 'call_12345',
        'type' => 'function',
        'function' => [
            'name' => 'getDate',
            'arguments' => '{}'
        ]
    ]
]);
$messages->add($assistantResponse);

// Adicionar a resposta da ferramenta
$messages->add(Message::tool('Hoje é 2024-05-05', 'call_12345'));

// Continuar a conversa
// ...

Para mais informações sobre os tipos individuais de mensagens, consulte a seção Mensagens.

Lançado sob a Licença MIT.