Threads

Esta página apresenta o identificador de thread concreto do Oracle junto com o tipo de auxiliar de mensagem voltado para o desenvolvedor.

Thread Oracle

classe oracleagentmemory.core.OracleThread

Bases: IThread

Thread apoiado por um armazenamento Oracle.

Esta implementação incorpora e armazena mensagens de thread e memórias adicionadas manualmente e, em seguida, suporta pesquisa de similaridade em todos os registros armazenados.

Observações

• As mensagens são armazenadas como registros individuais (um registro por mensagem).
• A pesquisa pode ser restrita ao thread atual ou pode retornar resultados de qualquer thread (controlado pelo cliente).

Crie um novo identificador de thread.

• Parâmetros:
  • store OracleMemoryStore – Back-end de armazenamento compartilhado usado para persistir registros incorporados.
  • thread_id str – Identificador de thread. Se não for fornecido, um UUID será gerado.
  • user_id str – Identificador do usuário associado ao thread. Se for omitido, um UUID é gerado.
  • agent_id str – Identificador do agente associado ao thread. Se for omitido, um UUID é gerado.
  • persist_messages_in_config bool – Se _to_config deve incluir instantâneos de mensagens brutas recentes. Definido automaticamente como False para threads que usam o armazenamento do BD para evitar a exportação do conteúdo da tabela de mensagens por meio da configuração do thread.
  • LLM ILlm | None – Adaptador LLM opcional usado para extração de memória e atualizações de resumo de contexto. Quando fornecido, o add_messages extrairá memórias relevantes de cada mensagem adicionada e as armazenará como record_type="memory".
  • memory_extraction_window int - Número de mensagens mais recentes (incluindo a recém-adicionada) para fornecer como contexto ao LLM durante a extração. Defina como -1 para extrair somente uma vez por chamada add_messages usando o batch completo de mensagens recém-adicionadas. O padrão é -1.
  • context_summary_update_frequency int – Número de mensagens após as quais o resumo de contexto deve ser atualizado. Defina como -1 para resumir apenas uma vez por chamada add_messages usando o batch completo de mensagens recém-adicionadas. A mesma cadência é reutilizada para atualizar metadados de consolidação de thread durante gravações de transcrição.
  • memory_extraction_frequency int – Número de mensagens após as quais a extração de memória é acionada. Defina como -1 para extrair somente uma vez por chamada add_messages usando o batch completo de mensagens recém-adicionadas.
  • memory_extraction_token_limit int – Tamanho máximo, em tokens, dos prompts usados na extração de memória. Os prompts mais longos serão truncados. Se negativo ou 0, nenhum truncamento será executado.
  • max_message_token_length int – Tamanho máximo, em tokens, da cópia de tempo imediato de cada mensagem usada durante a extração de memória suportada pelo LLM e atualizações de resumo de contexto. O conteúdo da mensagem armazenada permanece inalterado. Se negativo ou 0, nenhuma redução de tempo imediato é realizada. Se um LLM for fornecido, cópias de prompt grandes serão resumidas em vez de truncadas.
  • message_shortening_input_token_limit int – Tamanho máximo, em tokens, do trecho de mensagem enviado ao LLM ao encurtar cópias de prompt grandes. O padrão é tokens 30_000. Se for negativo ou 0, nenhum limite de saída será aplicado durante a redução baseada em LLM.
  • enable_context_summary bool – Se deve manter um resumo de execução compacto do thread. Quando ativado e fornecido um llm, o resumo é atualizado de acordo com o context_summary_update_frequency. O resumo atual é fornecido como contexto ao extrair memórias.
  • cliente Any | None

Exemplos de

from oracleagentmemory.core import OracleAgentMemory
db_pool = ...
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c1",
    llm=llm,
    enable_context_summary=True,
)
len(thread.add_messages([{"role": "user", "content": "I love pizza."}]))
1

método add_memory

Adicione uma entrada de memória manual e indexe-a.

• Parâmetros:
  • content str – Conteúdo de texto a ser armazenado como memória.
  • user_id str – Substituição do identificador de usuário opcional.
  • agent_id str – Substituição do identificador de agente opcional.
  • thread_id str – Substituição de identificador de thread opcional.
  • memory_id str – Identificador estável fornecido pelo chamador opcional para esta linha de memória.
  • **store_kwargs (Qualquer) – Opções de gravação específicas da loja encaminhadas para o armazenamento de apoio.
• Retorna: Identificador do registro de memória inserido.
• Tipo de retorno: str

Exemplos de

thread.add_memory("Remember this preference", memory_id="mem-thread-docs")
'mem-thread-docs'

método add_messages

Adicionar mensagens ao tópico e indexá-las.

• Parâmetros:
  • mensagens list[Message | MessageT] – Lista de mensagens a serem anexadas. As mensagens podem ser objetos Message ou dicionários com role e content (e id opcional).
  • **store_kwargs (Qualquer) – Opções de gravação específicas da loja encaminhadas para o armazenamento de apoio.
• Retorna: Identificadores de registros de mensagem inseridos.
• Tipo de retorno: list[str]

Exemplos de

len(thread.add_messages([{"role": "user", "content": "Thread message from docs"}]))
1

método add_messages_async (assíncrono)

Adicione mensagens de forma assíncrona ao tópico e indexe-as.

• Parâmetros:
  • mensagens list[Message | MessageT]
  • store_kwargs Any
• Tipo de retorno: list[str]

método delete_memory

Exclua um registro de memória deste thread exato por identificador.

• Parâmetros: memory_id str – Identificador de memória. Somente as memórias cujo thread_id armazenado corresponde exatamente a este thread são excluídas.
• Devoluções: Número de registros excluídos (0 ou 1). Retorna 0 quando o identificador não existe ou pertence a um thread diferente.
• Tipo de retorno: int

Exemplos de

thread.delete_memory("456")
0

método delete_message

Exclua um registro de mensagem deste thread exato por identificador.

• Parâmetros: message_id str – Identificador de mensagem Somente mensagens cujo thread_id armazenado corresponde exatamente a este thread são excluídas.
• Devoluções: Número de registros excluídos (0 ou 1). Retorna 0 quando o identificador não existe ou pertence a um thread diferente.
• Tipo de retorno: int

Observações

A exclusão bem-sucedida limpa o estado de resumo de thread derivado para que as chamadas de resumo e de cartão de contexto posteriores sejam recriadas a partir da transcrição restante. As memórias derivadas não são excluídas automaticamente porque as memórias extraídas não persistem atualmente por proveniência de mensagem.

Exemplos de

thread.delete_message("123")
0

método get_context_card

Retorna um cartão de contexto semelhante a XML para o thread.

Preferir get_context_card_async quando uma implementação suportada por LLM puder executar E/S de rede remota.

• Parâmetros:
  • fallback_message_count int – Número de mensagens recentes a serem usadas ao derivar o texto de resumo de fallback para recuperação e renderização.
  • max_relevant_results int – Número máximo de registros duráveis recuperados a serem incluídos.
  • max_recent_messages int – Número máximo de mensagens brutas posteriores a serem incorporadas textualmente.
  • **kwargs (Qualquer um) – Reservado para futuras opções de cartão de contexto. Argumentos de palavra-chave inesperados geram TypeError.
• Retorna: Um cartão que contém um resumo de contexto de thread com base nas mensagens mais recentes.
• Tipo de retorno: str

Observações

Isso usa o escopo de pesquisa padrão do thread com exact_thread_match=False, para que memórias relevantes de outros threads para o mesmo usuário/agente possam ser incluídas.

Exemplos de

thread.add_memory("User likes pizza", memory_id="mem-context-docs")
'mem-context-docs'
len(thread.add_messages([{"role": "user", "content": "Tell me about pizza"}]))
1
"User likes pizza" in thread.get_context_card()
True

método get_context_card_async (assíncrono)

Retorna assincronicamente um cartão de contexto semelhante a XML para o thread.

• Parâmetros:
  • fallback_message_count int – Número de mensagens recentes a serem usadas ao derivar o texto de resumo de fallback para recuperação e renderização.
  • max_relevant_results int – Número máximo de registros duráveis recuperados a serem incluídos.
  • max_recent_messages int – Número máximo de mensagens brutas posteriores a serem incorporadas textualmente.
  • **kwargs (Qualquer um) – Reservado para futuras opções de cartão de contexto. Argumentos de palavra-chave inesperados geram TypeError.
• Retorna: Um cartão que contém um resumo de contexto de thread com base nas mensagens mais recentes.
• Tipo de retorno: str

método get_messages

Retornar mensagens armazenadas para este tópico.

• Parâmetros:
  • start int | None – Índice de inicialização (com base em 0). Quando omitida junto com end, a janela delimitada mais recente é retornada.
  • end int | None – Índice de término (exclusivo). Quando omitido, uma janela delimitada das mensagens mais recentes é retornada. Informe None ou -1 para solicitar explicitamente todas as mensagens de start em diante.
• Retorna: Mensagens em ordem cronológica.
• Tipo de retorno: list[Mensagem]

Exemplos de

len(thread.add_messages([{"role": "user", "content": "Stored message example"}]))
1
messages = thread.get_messages()
messages[-1].content
'Stored message example'

método get_summary

Retorna um resumo do melhor esforço do thread.

Preferir get_summary_async quando uma implementação suportada por LLM puder executar E/S de rede remota.

• Parâmetros:
  • except_last int – Número de mensagens mais recentes a serem excluídas do resumo.
  • token_budget int – Orçamento de token temporário. Quando omitido, um padrão limitado é aplicado. Os valores positivos são truncados somente quando o resumo formatado excede o orçamento, conforme estimado por _estimate_tokens(); o texto retornado é limitado a int(token_budget * 3.5) caracteres. Valores não positivos desativam o limite de saída.
  • **kwargs (Qualquer) – Reservado para opções de resumo futuras. Argumentos de palavra-chave inesperados geram TypeError.
• Retorna: Uma mensagem do assistente contendo o resumo ou uma lista vazia se o thread não tiver mensagens.
• Tipo de retorno: list[Mensagem]

Exemplos de

len(thread.add_messages([{"role": "assistant", "content": "Summary source message"}]))
1
summary = thread.get_summary()
len(summary) >= 1
True

método get_summary_async (assíncrono)

Retorna assincronicamente um resumo do melhor esforço do thread.

• Parâmetros:
  • except_last int – Número de mensagens mais recentes a serem excluídas do resumo.
  • token_budget int – Orçamento de token temporário. Quando omitido, um padrão limitado é aplicado. Os valores positivos são truncados somente quando o resumo formatado excede o orçamento, conforme estimado por _estimate_tokens(); o texto retornado é limitado a int(token_budget * 3.5) caracteres. Valores não positivos desativam o limite de saída.
  • **kwargs (Qualquer um) – Reservado para opções de resumo futuras. Argumentos de palavra-chave inesperados geram TypeError.
• Retorna: Uma mensagem do assistente contendo o resumo ou uma lista vazia se o thread não tiver mensagens.
• Tipo de retorno: list[Mensagem]

Mensagens

classe oracleagentmemory.apis.thread.Message

Bases: object

• Parâmetros:
  • função str
  • conteúdo str
  • marcador de data/hora str | None
  • metadados dict[str, Any] | None
  • id str | None