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:
// 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á?')
]);
2
3
4
5
6
7
8
Adicionando Mensagens
Você pode adicionar novas mensagens a um MessageBag:
// 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.'));
2
3
4
5
Limitando Mensagens
Você pode limitar o número de mensagens em uma conversa mantendo o contexto:
// 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');
2
3
4
5
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:
// 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
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
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:
// Remover todas as chamadas de função e suas respostas
$messages->removeTools();
2
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:
// 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);
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
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:
// 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;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
Convertendo para Array
Você pode converter o MessageBag para um formato de array para inspeção ou armazenamento:
// 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;
}
2
3
4
5
6
7
Exportando e Importando Conversas
Você pode salvar e restaurar conversas usando JSON:
// 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;
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
Trabalhando com Ferramentas
Ao usar ferramentas em uma conversa, o MessageBag ajuda a manter o contexto da chamada de ferramenta:
// 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
// ...
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
Para mais informações sobre os tipos individuais de mensagens, consulte a seção Mensagens.