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 uma nova instância do OracleThread.

• 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 em um armazenamento de runtime do SchemaPolicy.NO_CHECK do BD, o nome de usuário do contexto de segurança do usuário final ativo será usado. Caso contrário, um UUID será gerado.
  • agent_id str – Identificador do agente associado ao thread. Se for omitido, um UUID é gerado.
  • metadata dict[str, Any] | None – Metadados opcionais semelhantes a JSON associados ao thread.
  • 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 registros de memória digitados ("memory", "guideline", "fact" ou "preference").
  • memory_extraction_config MemoryExtractionConfig – Configuração de extração de memória no nível de thread opcional. Use-o para controlar definições de extração automática, como modo de extração, comportamento de resumo, limites de extração e se a extração automática está ativada. Informe esta configuração agrupada ou os parâmetros de extração em linha obsoletos, não ambos. Quando omitido, o OracleThread() stand-alone usa padrões do SDK para os campos de extração e mantém os resumos de contexto ativados. Um contexto de imagem omitido é DISABLED.
  • image_input_limit_config ImageInputLimitConfig – Limites de solicitação de imagem raw-image e LLM opcionais para este thread standalone. Os campos omitidos usam padrões SDK. A validação não pode ser desativada.

  • 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.

    Obsoleto

    Obsoleto desde a versão 26.6.0: Este parâmetro foi preterido na versão 26.6.0 e será removido na versão 27.1. Em vez disso, use memory_extraction_config.

  • context_summary_update_frequency int –

    Número de mensagens após o último resumo válido antes de atualizá-lo automaticamente. Quando a extração de memória está ativada, a verificação é posterior a cada extração devida, para que a atualização possa ocorrer posteriormente. Valores menores ou iguais à atualização 0 em cada verificação. O padrão é -1.

    Obsoleto

    Obsoleto desde a versão 26.6.0: Este parâmetro foi preterido na versão 26.6.0 e será removido na versão 27.1. Em vez disso, use memory_extraction_config.

  • 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.

    Obsoleto

    Obsoleto desde a versão 26.6.0: Este parâmetro foi preterido na versão 26.6.0 e será removido na versão 27.1. Em vez disso, use memory_extraction_config.

  • memory_extraction_token_limit int –

    Tamanho máximo, em tokens, dos prompts do LLM usados para extração de memória e execução de atualizações resumidas. Os prompts mais longos são truncados. Se negativo ou 0, o truncamento do prompt será desativado.

    Obsoleto

    Obsoleto desde a versão 26.6.0: Este parâmetro foi preterido na versão 26.6.0 e será removido na versão 27.1. Em vez disso, use memory_extraction_config.

  • context_card_token_limit int – Orçamento máximo de token de entrada para o prompt LLM usado para criar a lista de tópicos e resumos incluídos no cartão de contexto. O padrão é 100_000; valores menores ou iguais a 0 desativam o truncamento de prompt.
  • context_card_type_search_concurrency int – Número máximo de pesquisas de registro semelhantes à memória a serem executadas simultaneamente ao criar um cartão de contexto com min_relevant_results_by_type. Assume 5 como padrão.
  • 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 compacto do thread. Quando ativado e fornecido um llm, o OAM o atualiza de acordo com o context_summary_update_frequency e usa um resumo de antes das mensagens de destino como contexto de extração. O padrão é True para OracleThread() autônomo.

    Obsoleto

    Obsoleto desde a versão 26.6.0: Este parâmetro foi preterido na versão 26.6.0 e será removido na versão 27.1. Em vez disso, use memory_extraction_config.

  • memory_extraction_custom_instructions str | None –

    Instruções personalizadas opcionais anexadas ao prompt do sistema de extração automática de memória para este thread.

    Obsoleto

    Obsoleto desde a versão 26.6.0: Este parâmetro foi preterido na versão 26.6.0 e será removido na versão 27.1. Em vez disso, use memory_extraction_config.

  • memory_extraction_inherit_message_metadata bool | Sequence[str] –

    Se as memórias extraídas automaticamente herdam metadados de mensagens de origem. Informe True para herdar todos os metadados da mensagem, uma sequência sem string de chaves de metadados de mensagem de nível superior para herdar somente essas chaves ou False para desativar a herança. O padrão é True. Se uma passagem de extração usar várias mensagens de origem, os metadados selecionados deverão corresponder a essas mensagens.

    Obsoleto

    Obsoleto desde a versão 26.6.0: Este parâmetro foi preterido na versão 26.6.0 e será removido na versão 27.1. Em vez disso, use memory_extraction_config.

  • search_config MemorySearchConfig – Configuração de pesquisa opcional para este thread. Quando omitido, as pesquisas usam uma configuração de pesquisa top-k fixa.
  • cliente OracleAgentMemory | None

Exemplos

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

método add_image

Persista uma imagem associada a este tópico.

description é armazenado como texto pesquisável da imagem. Quando é omitido ou None, um LLM anexado gera uma legenda. Os valores de escopo omitidos herdam os identificadores de usuário, agente e thread correspondentes deste thread.

• Parâmetros:
  • image bytes – Bytes de imagem brutos para persistir.
  • description str | None – Descrição ou legenda opcional. Omita-o para gerar uma legenda.
  • mime_type ImageMimeType – Tipo MIME opcional usado para persistência de imagem e geração de legenda. Quando omitido, o SDK detecta e valida o tipo dos bytes de imagem. Os tipos detectados suportados são PNG, JPEG e WEBP.
  • image_id str – Identificador opcional. Um é gerado quando omitido.
  • user_id str | None – Asserções de escopo opcionais. Os valores omitidos herdam o escopo deste thread; os valores fornecidos devem corresponder exatamente a ele.
  • agent_id str | None – Asserções de escopo opcionais. Os valores omitidos herdam o escopo deste thread; os valores fornecidos devem corresponder exatamente a ele.
  • thread_id str – Asserções de escopo opcionais. Os valores omitidos herdam o escopo deste thread; os valores fornecidos devem corresponder exatamente a ele.
  • metadados dict[str, Any] | None – Metadados opcionais armazenados com a imagem.
  • timestamp str | None – Timestamp de evento opcional para salvar essa imagem. Omita esse argumento ou informe None para armazenar um timestamp de evento NULL. Quando a imagem é lida, seu horário de criação é retornado como o carimbo de data/hora efetivo.
  • ttl_days int | None – Configurações de expiração opcionais.
  • ttl_anchor TimeToLiveAnchor – Configurações de expiração opcionais.
  • store_kwargs Any – Opções adicionais específicas do armazenamento.
• Retorna: O identificador de imagem persistente.
• Tipo de retorno: str

método add_image_async (assíncrono)

Persistir uma imagem associada a este thread de forma assíncrona.

description é armazenado como texto pesquisável da imagem. Quando é omitido ou None, um LLM anexado gera uma legenda. Os valores de escopo omitidos herdam os identificadores de usuário, agente e thread correspondentes deste thread.

• Parâmetros:
  • image bytes – Bytes de imagem brutos para persistir.
  • description str | None – Descrição ou legenda opcional. Omita-o para gerar uma legenda.
  • mime_type ImageMimeType – Tipo MIME opcional usado para persistência de imagem e geração de legenda. Quando omitido, o SDK detecta e valida o tipo dos bytes de imagem. Os tipos detectados suportados são PNG, JPEG e WEBP.
  • image_id str – Identificador opcional. Um é gerado quando omitido.
  • user_id str | None – Asserções de escopo opcionais. Os valores omitidos herdam o escopo deste thread; os valores fornecidos devem corresponder exatamente a ele.
  • agent_id str | None – Asserções de escopo opcionais. Os valores omitidos herdam o escopo deste thread; os valores fornecidos devem corresponder exatamente a ele.
  • thread_id str – Asserções de escopo opcionais. Os valores omitidos herdam o escopo deste thread; os valores fornecidos devem corresponder exatamente a ele.
  • metadados dict[str, Any] | None – Metadados opcionais armazenados com a imagem.
  • timestamp str | None – Timestamp de evento opcional para salvar essa imagem. Omita esse argumento ou informe None para armazenar um timestamp de evento NULL. Quando a imagem é lida, seu horário de criação é retornado como o carimbo de data/hora efetivo.
  • ttl_days int | None – Configurações de expiração opcionais.
  • ttl_anchor TimeToLiveAnchor – Configurações de expiração opcionais.
  • store_kwargs Any – Opções adicionais específicas do armazenamento.
• Retorna: O identificador de imagem persistente.
• Tipo de retorno: str

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.
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker – Categoria de memória a ser armazenada. Os valores suportados são "memory", "fact", "guideline" e "preference". Quando omitido, o conteúdo é armazenado como um "memory" geral.
  • 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.
  • metadados dict[str, Any] | None – Metadados opcionais para persistir com a memória armazenada.
  • timestamp str | None – Timestamp de evento opcional para salvar essa memória. Omita esse argumento ou informe None para armazenar um timestamp de evento NULL. Quando o registro é lido, seu horário de criação é retornado como o marcador de data/hora efetivo. Quando ttl_anchor for TimeToLiveAnchor.TIMESTAMP, forneça um valor de timestamp ISO-8601 concreto. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • ttl_days int | None – Duração opcional do tempo de vida útil em dias. Omita esse argumento para usar a duração de tempo de vida padrão do esquema. Informe None para usar MemoryRetentionConfig.max_ttl_days quando a configuração de retenção definir uma, ou para armazenar uma memória que não está expirando quando não estiver. Os valores acima de MemoryRetentionConfig.max_ttl_days são limitados a esse máximo com uma advertência.
  • ttl_anchor TimeToLiveAnchor – Âncora de tempo de vida opcional. Use TimeToLiveAnchor.CREATED_AT para o horário de criação do banco de dados ou TimeToLiveAnchor.TIMESTAMP para o timestamp da memória. A expiração ancorada no timestamp requer um timestamp ISO-8601 concreto para esta memória. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • status RecordStatus – status do ciclo de vida inicial. Omita-o para armazenar RecordStatus.VALID.
  • autonomous_linking bool – Se criar links dessa nova memória para memórias armazenadas relevantes usando o LLM do thread. Omitido o ativa quando existe um LLM; passe False para ignorar. A falha deixa a memória armazenada.
  • memory_id_to_link str – Juntos, criam um link direcionado da nova memória para essa memória de propriedade de thread existente. Os escopos de usuário, agente e thread omitidos herdam desse destino. Omita ambos para não criar nenhum link explícito.
  • link_type Literal['supersedes', 'contradicts', 'refines', 'supports', 'duplicates'] | ~oracleagentmemory._notset._NotSetMarker – Juntos, criam um link direcionado da nova memória para esta memória de propriedade de thread existente. Os escopos de usuário, agente e thread omitidos herdam desse destino. Omita ambos para não criar nenhum link explícito.
  • link_id str – Identificador, timestamp e metadados opcionais para o link explícito.
  • link_timestamp str | None – Identificador, timestamp e metadados opcionais para o link explícito.
  • link_metadata dict[str, Any] | None – Identificador, timestamp e metadados opcionais para o link explícito.
  • **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

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

método add_memory_async (assíncrono)

Adicione uma entrada de memória manual e indexe-a de forma assíncrona.

• Parâmetros:
  • content str – Conteúdo de texto a ser armazenado como memória.
  • memory_type Literal['memory', 'guideline', 'fact', 'preference'] | ~oracleagentmemory._notset._NotSetMarker – Categoria de memória a ser armazenada. Os valores suportados são "memory", "fact", "guideline" e "preference". Quando omitido, o conteúdo é armazenado como um "memory" geral.
  • 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.
  • metadados dict[str, Any] | None – Metadados opcionais para persistir com a memória armazenada.
  • timestamp str | None – Timestamp de evento opcional para salvar essa memória. Omita esse argumento ou informe None para armazenar um timestamp de evento NULL. Quando o registro é lido, seu horário de criação é retornado como o marcador de data/hora efetivo. Quando ttl_anchor for TimeToLiveAnchor.TIMESTAMP, forneça um valor de timestamp ISO-8601 concreto. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • ttl_days int | None – Duração opcional do tempo de vida útil em dias. Omita esse argumento para usar a duração de tempo de vida padrão do esquema. Informe None para usar MemoryRetentionConfig.max_ttl_days quando a configuração de retenção definir uma, ou para armazenar uma memória que não está expirando quando não estiver. Os valores acima de MemoryRetentionConfig.max_ttl_days são limitados a esse máximo com uma advertência.
  • ttl_anchor TimeToLiveAnchor – Âncora de tempo de vida opcional. Use TimeToLiveAnchor.CREATED_AT para o horário de criação do banco de dados ou TimeToLiveAnchor.TIMESTAMP para o timestamp da memória. A expiração ancorada no timestamp requer um timestamp ISO-8601 concreto para esta memória. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • status RecordStatus – status do ciclo de vida inicial. Omita-o para armazenar RecordStatus.VALID.
  • autonomous_linking bool – Se criar links dessa nova memória para memórias armazenadas relevantes usando o LLM do thread. Omitido o ativa quando existe um LLM; passe False para ignorar. A falha deixa a memória armazenada.
  • memory_id_to_link str – Juntos, criam um link direcionado da nova memória para essa memória de propriedade de thread existente. Os escopos de usuário, agente e thread omitidos herdam desse destino. Omita ambos para não criar nenhum link explícito.
  • link_type Literal['supersedes', 'contradicts', 'refines', 'supports', 'duplicates'] | ~oracleagentmemory._notset._NotSetMarker – Juntos, criam um link direcionado da nova memória para esta memória de propriedade de thread existente. Os escopos de usuário, agente e thread omitidos herdam desse destino. Omita ambos para não criar nenhum link explícito.
  • link_id str – Identificador, timestamp e metadados opcionais para o link explícito.
  • link_timestamp str | None – Identificador, timestamp e metadados opcionais para o link explícito.
  • link_metadata dict[str, Any] | None – Identificador, timestamp e metadados opcionais para o link explícito.
  • **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

import asyncio
asyncio.run(thread.add_memory_async(
    "Remember this preference", memory_id="mem-thread-docs-async"
))
'mem-thread-docs-async'

método add_messages

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

No modo de extração em segundo plano, esse método retorna após a inserção de mensagens brutas e a tentativa de extração em segundo plano devido.

As mensagens brutas são armazenadas antes da extração automática em qualquer modo. Se a extração posterior ou o armazenamento de memória derivada falhar, as mensagens brutas permanecerão armazenadas enquanto memórias derivadas ou atualizações resumidas poderão estar ausentes.

• Parâmetros:
  • mensagens Sequence[Message | ThreadMessageTypedDictT | Mapping[str, str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None]] – Lista de mensagens a serem anexadas. As mensagens podem ser objetos Message ou dicionários com role e content (e id opcional).
  • metadados dict[str, Any] | None | list[dict[str, Any] | None] – Metadados compartilhados ou por mensagem opcionais a serem persistidos. Quando omitidos, os metadados incorporados em cada mensagem são usados.
  • ttl_days int | None | list[int | None] – Duração opcional do tempo de vida útil em dias para mensagens anexadas. Omita esse argumento para usar a duração de tempo de vida padrão do esquema. Informe None para usar MemoryRetentionConfig.max_ttl_days quando a configuração de retenção definir uma, ou para criar mensagens que não estão expirando quando não o fizer. Os valores acima de MemoryRetentionConfig.max_ttl_days são limitados a esse máximo com uma advertência. Os valores escalares se aplicam ao lote completo.
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor] – Âncora de tempo de vida opcional. Use TimeToLiveAnchor.CREATED_AT para o horário de criação do banco de dados ou TimeToLiveAnchor.TIMESTAMP para cada timestamp de mensagem. A expiração ancorada no timestamp requer um timestamp ISO-8601 concreto para cada mensagem afetada. Quando omitidas, as mensagens expiram em relação a TimeToLiveAnchor.CREATED_AT. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • **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. No modo de extração em segundo plano, o trabalho de extração automática ainda pode estar em execução quando esses identificadores são retornados.
• Tipo de retorno: list[str]

Observações

No MemoryExtractionMode.BACKGROUND, as mensagens brutas são persistidas antes que as memórias extraídas sejam armazenadas. Se a extração em segundo plano não enfileirar, ou se uma espera de capacidade de fila configurada atingir seu timeout, as mensagens brutas inseridas permanecerão armazenadas e a chamada continuará sem memórias extraídas ou aumentará TimeoutError, dependendo de background_extraction_queue_full_behavior.

Exemplos

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.

No modo de extração em segundo plano, esse método retorna após a inserção de mensagens brutas e a tentativa de extração em segundo plano devido.

As mensagens brutas são armazenadas antes da extração automática em qualquer modo. Se a extração posterior ou o armazenamento de memória derivada falhar, as mensagens brutas permanecerão armazenadas enquanto memórias derivadas ou atualizações resumidas poderão estar ausentes.

No MemoryExtractionMode.BACKGROUND, as mensagens brutas são persistidas antes que as memórias extraídas sejam armazenadas. Se a extração em segundo plano não enfileirar, ou se uma espera de capacidade de fila configurada atingir seu timeout, as mensagens brutas inseridas permanecerão armazenadas e a chamada continuará sem memórias extraídas ou aumentará TimeoutError, dependendo de background_extraction_queue_full_behavior.

• Parâmetros:
  • mensagens Sequence[Message | ThreadMessageTypedDictT | Mapping[str, str | Sequence[Mapping[str, Any]] | Mapping[str, Any] | None]]
  • metadados dict[str, Any] | None | list[dict[str, Any] | None]
  • ttl_days int | None | list[int | None]
  • ttl_anchor TimeToLiveAnchor | list[TimeToLiveAnchor]
  • store_kwargs Any
• Tipo de retorno: list[str]

método delete_image

Excluir uma imagem pertencente a este tópico.

• Parâmetros: image_id str – O identificador da imagem a ser excluída.
• Retorna: 1 quando excluído; caso contrário, 0 quando a imagem não existe ou pertence a outro thread.
• Tipo de retorno: int
• Eleva: ValueError – Se a imagem estiver anexada a uma mensagem. Exclua ou atualize a mensagem pai.

método delete_image_async (assíncrono)

Exclua uma imagem pertencente a este thread de forma assíncrona.

• Parâmetros: image_id str – O identificador da imagem a ser excluída.
• Retorna: 1 quando excluído; caso contrário, 0 quando a imagem não existe ou pertence a outro thread.
• Tipo de retorno: int
• Eleva: ValueError – Se a imagem estiver anexada a uma mensagem. Exclua ou atualize a mensagem pai.

método delete_memory

Exclua um registro semelhante à memória (por exemplo, uma memória, um fato, uma preferência ou uma diretriz) deste thread exato por identificador.

• Parâmetros: memory_id str – Identificador de memória. Somente registros semelhantes à memória (memory, guideline, fact, preference) cujo thread_id armazenado corresponde exatamente a esse thread são excluídos.
• 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
• Gera: TimeoutError – Gerado sem excluir o registro quando a extração em segundo plano aceita anteriormente para esse thread não termina em 300 segundos.

Observações

Antes de excluir o registro, este método aguarda a extração em segundo plano anterior aceita para este thread por meio do componente de memória do agente anexado. Ele não aguarda o trabalho aceito após o início da espera ou o trabalho iniciado por outro componente ou processo.

Exemplos

thread.delete_memory("456")
0

método delete_memory_async (assíncrono)

Exclua um registro semelhante à memória (por exemplo, uma memória, um fato, uma preferência ou uma diretriz) deste thread exato por identificador de forma assíncrona.

• Parâmetros: memory_id str – Identificador de memória. Somente registros semelhantes à memória (memory, guideline, fact, preference) cujo thread_id armazenado corresponde exatamente a esse thread são excluídos.
• 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
• Gera: TimeoutError – Gerado sem excluir o registro quando a extração em segundo plano aceita anteriormente para esse thread não termina em 300 segundos.

Observações

Este método segue o comportamento de espera e simultaneidade de extração em segundo plano documentado por delete_memory().

Exemplos

import asyncio
asyncio.run(thread.delete_memory_async("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.
• Retorna: Número de registros de mensagem excluídos (0 ou 1). Retorna 0 quando o identificador não existe ou pertence a um thread diferente.
• Tipo de retorno: int
• Gera: TimeoutError – Gerado sem excluir a mensagem quando a extração em segundo plano aceita anteriormente para este thread não termina em 300 segundos.

Observações

Antes de excluir a mensagem, este método aguarda a extração em segundo plano anterior aceita para este thread por meio do componente de memória do agente anexado. Ele não aguarda o trabalho aceito após o início da espera ou o trabalho iniciado por outro componente ou processo.

A exclusão de uma mensagem remove apenas o registro de mensagem bruta. Memórias derivadas não são excluídas porque ainda não rastreamos quais memórias extraídas vieram de qual mensagem, então elas podem permanecer pesquisáveis ou ainda afetar a saída do cartão de contexto. Use OracleAgentMemory.delete_thread() para excluir o thread junto com suas mensagens e memórias associadas.

Exemplos

thread.delete_message("123")
0

método delete_message_async (assíncrono)

Exclua um registro de mensagem deste thread exato por identificador de forma assíncrona.

• Parâmetros: message_id str – Identificador de mensagem Somente mensagens cujo thread_id armazenado corresponde exatamente a este thread são excluídas.
• Retorna: Número de registros de mensagem excluídos (0 ou 1). Retorna 0 quando o identificador não existe ou pertence a um thread diferente.
• Tipo de retorno: int
• Gera: TimeoutError – Gerado sem excluir a mensagem quando a extração em segundo plano aceita anteriormente para este thread não termina em 300 segundos.

Observações

Este método segue o comportamento de espera e simultaneidade de extração em segundo plano documentado por delete_message().

A exclusão de uma mensagem remove apenas o registro de mensagem bruta. Memórias derivadas não são excluídas porque ainda não rastreamos quais memórias extraídas vieram de qual mensagem, então elas podem permanecer pesquisáveis ou ainda afetar a saída do cartão de contexto. Use OracleAgentMemory.delete_thread() para excluir o thread junto com suas mensagens e memórias associadas.

Exemplos

import asyncio
asyncio.run(thread.delete_message_async("123"))
0

método delete_record_link

Exclua uma relação de thread por ID ou complete a tupla do ponto final.

Os seletores de tupla de ponto final devem usar a orientação de origem para destino armazenada.

• Parâmetros:
  • source_record_id str – Identificador de origem de um seletor de tupla de ponto final.
  • source_record_type str – Tipo de registro de origem lógica para um seletor de tupla de ponto final.
  • target_record_id str – Identificador de destino de um seletor de tupla de ponto final.
  • target_record_type str – Tipo de registro de destino lógico para um seletor de tupla de ponto final.
  • relation_type str – Label de origem para destino para um seletor de tupla de ponto final.
  • relation_id str – Identificador de relação a ser selecionado diretamente. Forneça esse argumento sozinho.
• Retorna: Número de relações excluídas, 0 ou 1.
• Tipo de retorno: int

Exemplos

thread.delete_record_link(relation_id="relation-id")
1

método delete_record_link_async (assíncrono)

Exclua de forma assíncrona uma relação pertencente a este thread.

• Parâmetros:
  • source_record_id str,
  • source_record_type str
  • target_record_id str
  • tipo_registro_alvo str
  • tipo_relação str
  • id_relação str
• Tipo de retorno: int

método get_context_card

Retorna um objeto de cartão de contexto 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. Quando omitido, isso é resolvido para 5.

  • max_relevant_results int –

    Número máximo de registros relevantes (como memória, por exemplo, fato/preferências, bem como mensagens) a serem incluídos na seção <relevant_information> do cartão de contexto.

    • Se esse valor e min_relevant_results_by_type forem omitidos, o max_relevant_results será resolvido como 5.
    • Se min_relevant_results_by_type for fornecido, o max_relevant_results será resolvido como max(max_relevant_results, sum(min_relevant_results_by_type.values())).
  • token_budget int | None – Limite rígido opcional para a contagem estimada de tokens de resultados relevantes formatados no cartão de contexto. Quando omitida, a configuração de pesquisa de thread é usada. Os valores positivos mantêm os resultados completos na ordem de classificação, enquanto sua estimativa cumulativa se ajusta ao orçamento. Se o primeiro resultado não se encaixar, nenhum resultado relevante será incluído. Valores não positivos desativam o limite.
  • soft_token_budget int | None – Destino opcional para a contagem de tokens estimada de resultados relevantes formatados. Quando omitida, a configuração de pesquisa de thread é usada. O resultado completo que atinge ou excede este alvo é mantido. Valores não positivos desativam esse destino. Defina token_budget como um valor maior quando a saída também tiver um limite absoluto.
  • max_recent_messages int – Número máximo de mensagens de conversa recentes a serem incluídas na seção <recent_messages> do cartão de contexto. Quando omitido, max_recent_messages é resolvido como 0.

  • exceto_last_messages int –

    Número de mensagens finais a serem excluídas da pesquisa de resumo e informações relevantes geradas incluídas no cartão de contexto. Isso impede que as mensagens fornecidas separadamente nos prompts do LLM sejam duplicadas no cartão de contexto. Use um destes padrões:

    • Cauda bruta externa (recomendado para cache de prompt):

      get_context_card(except_last_messages=N, max_recent_messages=0) O prompt contém o cartão de contexto seguido pelas últimas N mensagens brutas.

    • Cartão de contexto independente:

      get_context_card(except_last_messages=N, max_recent_messages=N) O cartão de contexto contém as últimas N mensagens em si.

    Quando diferente de zero, max_recent_messages deve ser 0 ou o mesmo valor.

  • min_relevant_results_by_type Mapping[Literal['message', 'memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker – Mínimos opcionais por tipo para registros relevantes incluídos no cartão de contexto. Os tipos solicitados são pesquisados primeiro e os slots max_relevant_results restantes são preenchidos de todos os tipos de registro compatíveis com memória. As chaves suportadas são "memory", "fact", "guideline", "preference" e "message". Resultados da mensagem estão limitados ao thread atual.

  • metadata_filter dict[str, Any] | None –

    Mapeamento de filtro de metadados opcional usado como um filtro adicional após a filtragem de escopo e tipo de registro ao procurar registros semelhantes à memória para incluir no cartão de contexto. As entradas no metadata_filter são combinadas com a semântica AND. As entradas cujo valor não é um dicionário de operador de nível de campo usam semântica de correspondência exata: a chave solicitada deve existir nos metadados de registro armazenados. Os dicionários aninhados correspondem recursivamente a objetos de metadados aninhados. Os valores escalares e de lista devem corresponder exatamente; a ordem e o tamanho da lista também devem corresponder. Omita esse argumento ou passe None para pesquisar sem filtragem de metadados. Os exemplos incluem metadata_filter={"source": "chat"} para um campo escalar, metadata_filter={"travel": {"need": "transit"}} para um campo aninhado e metadata_filter={"tags": ["trip", "urgent"]} para uma correspondência de lista exata. Combine condições para exigir todas elas:

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    Para testar a associação de array, use um dicionário do operador no nível do campo. "$array_contains" corresponde a um valor ou a todos os valores em uma lista. "$array_contains_any" corresponde a pelo menos um valor de uma lista. "$not" nega outra expressão no nível do campo no mesmo campo, incluindo um dicionário do operador ou um valor bruto de correspondência exata. As expressões negativas correspondem quando a expressão positiva falharia, incluindo campos ausentes; a associação de matriz negada também corresponde a campos que não são de matriz:

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool – Se os registros relevantes no status de ciclo de vida inválido estão incluídos no cartão de contexto. Omita esse argumento ou passe True para incluí-los. Informe False para excluí-los.
  • **kwargs (Qualquer um) – Reservado para futuras opções de cartão de contexto. Argumentos de palavra-chave inesperados geram TypeError.
• Retorna: Um objeto de cartão de contexto que contém um resumo de contexto de thread com base nas mensagens mais recentes. Use OracleContextCard.content para acessar o texto XML renderizado.
• Tipo da devolução: OracleContextCard

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

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().content
True
card = thread.get_context_card(
    max_relevant_results=4,
    min_relevant_results_by_type={"memory": 1},
)
len(card.relevant_results or []) <= 4
True

método get_context_card_async (assíncrono)

Retorna assincronicamente um objeto de cartão de contexto 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. Quando omitido, isso é resolvido para 5.

  • max_relevant_results int –

    Número máximo de registros relevantes (como memória, por exemplo, fato/preferências, bem como mensagens) a serem incluídos na seção <relevant_information> do cartão de contexto.

    • Se esse valor e min_relevant_results_by_type forem omitidos, o max_relevant_results será resolvido como 5.
    • Se min_relevant_results_by_type for fornecido, o max_relevant_results será resolvido como max(max_relevant_results, sum(min_relevant_results_by_type.values())).
  • token_budget int | None – Limite rígido opcional para a contagem estimada de tokens de resultados relevantes formatados no cartão de contexto. Quando omitida, a configuração de pesquisa de thread é usada. Os valores positivos mantêm os resultados completos na ordem de classificação, enquanto sua estimativa cumulativa se ajusta ao orçamento. Se o primeiro resultado não se encaixar, nenhum resultado relevante será incluído. Valores não positivos desativam o limite.
  • soft_token_budget int | None – Destino opcional para a contagem de tokens estimada de resultados relevantes formatados. Quando omitida, a configuração de pesquisa de thread é usada. O resultado completo que atinge ou excede este alvo é mantido. Valores não positivos desativam esse destino. Defina token_budget como um valor maior quando a saída também tiver um limite absoluto.
  • max_recent_messages int – Número máximo de mensagens de conversa recentes a serem incluídas na seção <recent_messages> do cartão de contexto. Quando omitido, max_recent_messages é resolvido como 0.

  • exceto_last_messages int –

    Número de mensagens finais a serem excluídas da pesquisa de resumo e informações relevantes geradas incluídas no cartão de contexto. Isso impede que as mensagens fornecidas separadamente nos prompts do LLM sejam duplicadas no cartão de contexto. Use um destes padrões:

    • Cauda bruta externa (recomendado para cache de prompt):

      get_context_card(except_last_messages=N, max_recent_messages=0) O prompt contém o cartão de contexto seguido pelas últimas N mensagens brutas.

    • Cartão de contexto independente:

      get_context_card(except_last_messages=N, max_recent_messages=N) O cartão de contexto contém as últimas N mensagens em si.

    Quando diferente de zero, max_recent_messages deve ser 0 ou o mesmo valor.

  • min_relevant_results_by_type Mapping[Literal['message', 'memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker – Mínimos opcionais por tipo para registros relevantes incluídos no cartão de contexto. Os tipos solicitados são pesquisados primeiro e os slots max_relevant_results restantes são preenchidos de todos os tipos de registro compatíveis com memória. As chaves suportadas são "memory", "fact", "guideline", "preference" e "message". Resultados da mensagem estão limitados ao thread atual.

  • metadata_filter dict[str, Any] | None –

    Mapeamento de filtro de metadados opcional usado como um filtro adicional após a filtragem de escopo e tipo de registro ao procurar registros semelhantes à memória para incluir no cartão de contexto. As entradas no metadata_filter são combinadas com a semântica AND. As entradas cujo valor não é um dicionário de operador de nível de campo usam semântica de correspondência exata: a chave solicitada deve existir nos metadados de registro armazenados. Os dicionários aninhados correspondem recursivamente a objetos de metadados aninhados. Os valores escalares e de lista devem corresponder exatamente; a ordem e o tamanho da lista também devem corresponder. Omita esse argumento ou passe None para pesquisar sem filtragem de metadados. Os exemplos incluem metadata_filter={"source": "chat"} para um campo escalar, metadata_filter={"travel": {"need": "transit"}} para um campo aninhado e metadata_filter={"tags": ["trip", "urgent"]} para uma correspondência de lista exata. Combine condições para exigir todas elas:

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    Para testar a associação de array, use um dicionário do operador no nível do campo. "$array_contains" corresponde a um valor ou a todos os valores em uma lista. "$array_contains_any" corresponde a pelo menos um valor de uma lista. "$not" nega outra expressão no nível do campo no mesmo campo, incluindo um dicionário do operador ou um valor bruto de correspondência exata. As expressões negativas correspondem quando a expressão positiva falharia, incluindo campos ausentes; a associação de matriz negada também corresponde a campos que não são de matriz:

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool – Se os registros relevantes no status de ciclo de vida inválido estão incluídos no cartão de contexto. Omita esse argumento ou passe True para incluí-los. Informe False para excluí-los.
  • **kwargs (Qualquer um) – Reservado para futuras opções de cartão de contexto. Argumentos de palavra-chave inesperados geram TypeError.
• Retorna: Um objeto de cartão de contexto para o thread.
• Tipo da devolução: OracleContextCard

Exemplos

import asyncio
card = asyncio.run(thread.get_context_card_async(
    min_relevant_results_by_type={"preference": 1, "guideline": 1},
))
len(card.relevant_results or []) <= 5
True

método get_message

Retornar uma mensagem de propriedade deste tópico.

As partes da imagem são retornadas com seus identificadores e descrições por padrão. Informe included_image_ids para carregar bytes para partes de imagem selecionadas. Os identificadores não relacionados são ignorados.

• Parâmetros:
  • message_id str – Identificador da mensagem a ser recuperada. A mensagem deve pertencer a este tópico.
  • included_image_ids list[str] – Lista opcional de identificadores de imagem anexados cujos bytes devem ser carregados. Omita esse argumento ou informe None para retornar metadados de imagem sem carregar bytes.
• Retorna: A mensagem solicitada, incluindo quaisquer partes de imagem anexadas.
• Tipo de retorno: Mensagem
• Gera: KeyError – Se a mensagem não existir ou pertencer a outro thread.

método get_message_async (assíncrono)

Retorna uma mensagem de thread pertencente de forma assíncrona.

included_image_ids opcionalmente seleciona partes de imagem anexadas cujos bytes devem ser carregados; omitido ou None retorna somente metadados de imagem.

• Parâmetros:
  • message_id str – Identificador da mensagem a ser recuperada. A mensagem deve pertencer a este tópico.
  • included_image_ids list[str] – Lista opcional de identificadores de imagem anexados a hidratar.
• Retorna: A mensagem solicitada, incluindo quaisquer partes de imagem anexadas.
• Tipo de retorno: Mensagem
• Gera: KeyError – Se a mensagem não existir ou pertencer a outro thread.

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.
  • include_image_bytes bool – Se deseja carregar bytes de partes de imagem anexadas às mensagens retornadas. Omita esse argumento ou informe False para retornar metadados de imagem sem carregar valores BLOB.
• Retorna: Mensagens em ordem cronológica.
• Tipo de retorno: list[Mensagem]

Exemplos

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

método get_messages_async (assíncrono)

Obtenha as mensagens não processadas do thread, conforme adicionado com add_messages de forma assíncrona.

• 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.
  • include_image_bytes bool – Se deseja carregar bytes de partes de imagem anexadas às mensagens retornadas. Omita esse argumento ou informe False para retornar metadados de imagem sem carregar valores BLOB.
• Retorna: Mensagens em ordem cronológica.
• Tipo de retorno: list[Mensagem]

Exemplos

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Stored message example"}]
))
len(message_ids)
1
messages = asyncio.run(thread.get_messages_async())
messages[-1].content
'Stored message example'

método get_summary

Retorna um resumo do thread.

Uma solicitação de thread inteiro reutiliza ou atualiza o resumo durável. Uma solicitação com except_last resume esse prefixo sem alterar o resumo durável do thread inteiro.

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. Valores não positivos desativam o truncamento baseado em orçamento; as substituições de histórico escolar permanecem limitadas a 4.000 caracteres.
  • **kwargs (Qualquer) – Reservado para opções de resumo futuras. Argumentos de palavra-chave inesperados geram TypeError.
• Retorna: Objeto de resumo que contém o texto de resumo do thread sintetizado.
• Tipo da devolução: OracleSummary

Exemplos

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

método get_summary_async (assíncrono)

Retorna assincronicamente um resumo do thread.

Uma solicitação de thread inteiro reutiliza ou atualiza o resumo durável. Uma solicitação com except_last resume esse prefixo sem alterar o resumo durável do thread inteiro.

• 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. Valores não positivos desativam o truncamento baseado em orçamento; as substituições de histórico escolar permanecem limitadas a 4.000 caracteres.
  • **kwargs (Qualquer) – Reservado para opções de resumo futuras. Argumentos de palavra-chave inesperados geram TypeError.
• Retorna: Objeto de resumo que contém o texto de resumo do thread sintetizado.
• Tipo da devolução: OracleSummary

método link_records

Crie uma relação direcionada entre dois registros pertencentes a este thread.

No momento, os dois pontos finais devem ser registros semelhantes à memória: "memory", "fact", "guideline" ou "preference". Os tipos de relação incorporados são "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") e "duplicates". "contradicts" e "duplicates" usam o mesmo label invertido.

Ambos os pontos finais devem pertencer a este thread exato. Somente uma orientação pode ser armazenada para um par de pontos finais. opposite_relation_type nomeia a relação ao percorrer do destino para a origem; por exemplo, new "supersedes" old torna-se old "is_superseded_by" new nessa direção.

• Parâmetros:
  • source_record_id str – Identificador do registro de origem de propriedade do thread.
  • source_record_type str – Tipo lógico do registro de origem.
  • target_record_id str – Identificador do registro de destino pertencente ao thread.
  • target_record_type str – Tipo lógico do registro de destino.
  • relation_type str – Rótulo de relação de origem para destino.
  • opposite_relation_type str – Rótulo de inversão opcional. Para um tipo de relação de memória incorporado, omissão usa seu rótulo reverso predefinido; para um tipo de relação personalizada, omissão usa o mesmo rótulo em ambas as direções.
  • relation_id str – Identificador de relação estável opcional. Omita-o para gerar um.
  • timestamp str | None – Timestamp opcional armazenado na relação.
  • metadados dict[str, Any] | None – Metadados de relação opcionais.
• Retorna: Identificador da relação criada.
• Tipo de retorno: str

Exemplos

thread.link_records(
    "fact-1", "fact", "memory-1", "memory", "supports"
)
'relation-id'

método link_records_async (assíncrono)

Crie de forma assíncrona uma relação entre registros pertencentes a este thread.

No momento, os dois pontos finais devem ser registros semelhantes à memória: "memory", "fact", "guideline" ou "preference". Os tipos de relação incorporados são "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") e "duplicates". "contradicts" e "duplicates" usam o mesmo label invertido.

• Parâmetros:
  • source_record_id str,
  • source_record_type str
  • target_record_id str
  • tipo_registro_alvo str
  • tipo_relação str
  • opposite_relation_type str
  • id_relação str
  • marcador de data/hora str | None
  • metadados dict[str, Any] | None
• Tipo de retorno: str

método list_images

Listar registros de imagem pertencentes a este thread.

Por padrão, os registros retornados contêm metadados de imagem. Os bytes brutos são carregados somente quando include_bytes=True e image_id são fornecidos.

• Parâmetros:
  • image_id str – Identificador opcional usado para filtrar as imagens. Quando omitido, nenhum filtro de identificador é aplicado.
  • metadata_filter dict[str, Any] | None – Filtro opcional aplicado aos metadados de imagem.
  • include_bytes bool – Se deve carregar bytes brutos. Isso requer um image_id.
  • limit int | None – Número máximo opcional de registros. Informe None para desativar o limite padrão do armazenamento.
• Retorna: imagens correspondentes na ordem da loja.
• Tipo de retorno: list[ImageRecord]

método list_images_async (assíncrono)

Liste registros de imagem pertencentes a este thread de forma assíncrona.

Por padrão, os registros retornados contêm metadados de imagem. Os bytes brutos são carregados somente quando include_bytes=True e image_id são fornecidos. O escopo deste thread é aplicado automaticamente.

• Parâmetros:
  • image_id str – Identificador opcional usado para filtrar as imagens. Quando omitido, nenhum filtro de identificador é aplicado.
  • metadata_filter dict[str, Any] | None – Filtro opcional aplicado aos metadados de imagem.
  • include_bytes bool – Se deve carregar bytes brutos. Isso requer um image_id.
  • limit int | None – Número máximo opcional de registros. Informe None para desativar o limite padrão do armazenamento.
• Retorna: imagens correspondentes na ordem da loja.
• Tipo de retorno: list[ImageRecord]

método search

Pesquise de forma síncrona registros relevantes para uma consulta.

• Parâmetros:
  • query str – String de consulta em linguagem natural.
  • user_id str | None – Substituição do escopo do usuário opcional. Os valores omitidos herdam o escopo do usuário padrão do thread.
  • agent_id str | None – Substituição do escopo do agente opcional. Os valores omitidos herdam o escopo do agente padrão do thread.
  • thread_id str | None – Substituição de escopo de thread opcional. Os valores omitidos herdam o identificador de thread atual do thread.
  • exact_user_match bool – Se a correspondência do usuário deve ser rigorosa.
  • exact_agent_match bool – Se a correspondência de agente deve ser rigorosa.
  • exact_thread_match bool – Se a correspondência de threads deve ser rigorosa.
  • max_results int – Número máxima opcional de resultados a retornar. Quando fornecido, deve ser pelo menos 1. A omissão desse argumento usa o valor padrão de 10. A chamada poderá retornar menos de max_results quando existirem menos registros correspondentes não expirados.
  • token_budget int – Limite rígido opcional para a contagem de tokens estimada dos resultados formatados finais. Quando omitida, a configuração de pesquisa resolvida é usada. Os valores positivos mantêm os resultados completos na ordem de classificação, enquanto sua estimativa cumulativa se ajusta ao orçamento. Se o primeiro resultado não for adequado, nenhum resultado será retornado. Valores não positivos desativam esse limite de saída.
  • soft_token_budget int – Destino opcional para a contagem de tokens estimada dos resultados formatados finais. Quando omitida, a configuração de pesquisa resolvida é usada. O resultado completo que atinge ou excede este alvo é mantido. Valores não positivos desativam esse destino. Defina token_budget como um valor maior quando a saída também tiver um limite absoluto.
  • record_types list[str] – Lista opcional de tipos de registro a incluir, como "memory", "message" ou "image".

  • metadata_filter dict[str, Any] | None –

    Mapeamento de filtro de metadados opcional usado como um filtro adicional após a filtragem de escopo e tipo de registro. As entradas no metadata_filter são combinadas com a semântica AND. As entradas cujo valor não é um dicionário de operador de nível de campo usam semântica de correspondência exata: a chave solicitada deve existir nos metadados de registro armazenados. Os dicionários aninhados correspondem recursivamente a objetos de metadados aninhados. Os valores escalares e de lista devem corresponder exatamente; a ordem e o tamanho da lista também devem corresponder. Omita esse argumento ou passe None para pesquisar sem filtragem de metadados. Os exemplos incluem metadata_filter={"source": "chat"} para um campo escalar, metadata_filter={"travel": {"need": "transit"}} para um campo aninhado e metadata_filter={"tags": ["trip", "urgent"]} para uma correspondência de lista exata. Combine condições para exigir todas elas:

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    Para testar a associação de array, use um dicionário do operador no nível do campo. "$array_contains" corresponde a um valor ou a todos os valores em uma lista. "$array_contains_any" corresponde a pelo menos um valor de uma lista. "$not" nega outra expressão no nível do campo no mesmo campo, incluindo um dicionário do operador ou um valor bruto de correspondência exata. As expressões negativas correspondem quando a expressão positiva falharia, incluindo campos ausentes; a associação de matriz negada também corresponde a campos que não são de matriz:

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool – Se os resultados incluem registros no status inválido. Omita esse argumento ou passe True para incluí-los. Informe False para excluí-los.
  • num_hops int – Número de bordas de link de memória a serem seguidas de cada resultado direto de memória. Os valores de 0 a 5 são suportados; omita apenas para resultados diretos. Os resultados de mensagem direta, imagem e perfil são retidos, mas não são expandidos por gráfico.
  • max_linked_results int – Máximo de memórias vinculadas em todos os saltos anexados a cada resultado direto. Omita o padrão de 100; passe 0 para não retornar contexto vinculado.
  • escopo SearchScope – Escopo de pesquisa pré-criado opcional. Forneça scope ou o identificador explícito e os argumentos de correspondência exata, não ambos.
• Devoluções: resultados da pesquisa ordenados por relevância decrescente.
• Tipo de retorno: list[SearchResult]
• Gera: ValueError – Se scope for combinado com identificador explícito ou argumentos de correspondência exata, se max_results for menor que 1 ou se metadata_filter não for um dicionário nem None.

Observações

Os campos de escopo omitidos herdam o escopo de pesquisa padrão deste thread: correspondência exata de usuário e agente mais o user_id, agent_id e thread_id atuais deste thread. A pesquisa de thread padrão sai intencionalmente de exact_thread_match=False, para que possa retornar registros relevantes de outros threads para o mesmo usuário/agente. Informe exact_thread_match=True para restringir os resultados ao thread atual. Os valores explícitos do escopo None ainda seguem as regras de correspondência exata resolvidas: exact_*_match=False deixa essa dimensão sem restrições, enquanto exact_*_match=True corresponde apenas aos valores None armazenados.

Os valores max_results explícitos devem ser pelo menos 1; a omissão do argumento usa o valor padrão de 10. Este é um limite superior: a chamada pode retornar menos de max_results resultados quando os filtros são muito restritivos, quando há menos registros correspondentes ou por causa do comportamento de pesquisa específico da implementação.

método search_async (assíncrono)

Pesquise registros relevantes para uma consulta de forma assíncrona.

• Parâmetros:
  • query str – String de consulta em linguagem natural.
  • user_id str | None – Substituição do escopo do usuário opcional. Os valores omitidos herdam o escopo do usuário padrão do thread.
  • agent_id str | None – Substituição do escopo do agente opcional. Os valores omitidos herdam o escopo do agente padrão do thread.
  • thread_id str | None – Substituição de escopo de thread opcional. Os valores omitidos herdam o identificador de thread atual do thread.
  • exact_user_match bool – Se a correspondência do usuário deve ser rigorosa.
  • exact_agent_match bool – Se a correspondência de agente deve ser rigorosa.
  • exact_thread_match bool – Se a correspondência de threads deve ser rigorosa.
  • max_results int – Número máxima opcional de resultados a retornar. Quando fornecido, deve ser pelo menos 1. A omissão desse argumento usa o valor padrão de 10.
  • token_budget int – Limite rígido opcional para a contagem de tokens estimada dos resultados formatados finais. Quando omitida, a configuração de pesquisa resolvida é usada. Os valores positivos mantêm os resultados completos na ordem de classificação, enquanto sua estimativa cumulativa se ajusta ao orçamento. Se o primeiro resultado não for adequado, nenhum resultado será retornado. Valores não positivos desativam esse limite de saída.
  • soft_token_budget int – Destino opcional para a contagem de tokens estimada dos resultados formatados finais. Quando omitida, a configuração de pesquisa resolvida é usada. O resultado completo que atinge ou excede este alvo é mantido. Valores não positivos desativam esse destino. Defina token_budget como um valor maior quando a saída também tiver um limite absoluto.
  • record_types list[str] – Lista opcional de tipos de registro a incluir, como "memory", "message" ou "image".

  • metadata_filter dict[str, Any] | None –

    Mapeamento de filtro de metadados opcional usado como um filtro adicional após a filtragem de escopo e tipo de registro. As entradas no metadata_filter são combinadas com a semântica AND. As entradas cujo valor não é um dicionário de operador de nível de campo usam semântica de correspondência exata: a chave solicitada deve existir nos metadados de registro armazenados. Os dicionários aninhados correspondem recursivamente a objetos de metadados aninhados. Os valores escalares e de lista devem corresponder exatamente; a ordem e o tamanho da lista também devem corresponder. Omita esse argumento ou passe None para pesquisar sem filtragem de metadados. Os exemplos incluem metadata_filter={"source": "chat"} para um campo escalar, metadata_filter={"travel": {"need": "transit"}} para um campo aninhado e metadata_filter={"tags": ["trip", "urgent"]} para uma correspondência de lista exata. Combine condições para exigir todas elas:

    metadata_filter={
        "source": "chat",
        "travel": {"need": "transit"},
        "tags": ["trip", "urgent"],
    }

    Para testar a associação de array, use um dicionário do operador no nível do campo. "$array_contains" corresponde a um valor ou a todos os valores em uma lista. "$array_contains_any" corresponde a pelo menos um valor de uma lista. "$not" nega outra expressão no nível do campo no mesmo campo, incluindo um dicionário do operador ou um valor bruto de correspondência exata. As expressões negativas correspondem quando a expressão positiva falharia, incluindo campos ausentes; a associação de matriz negada também corresponde a campos que não são de matriz:

    metadata_filter={
        "source": "chat",
        "tags": {
            "$array_contains": "trip",
            "$not": {"$array_contains": "archived"},
        },
    }

  • include_invalid_results bool – Se os resultados incluem registros no status inválido. Omita esse argumento ou passe True para incluí-los. Informe False para excluí-los.
  • num_hops int – Número de bordas de link de memória a serem seguidas de cada resultado direto de memória. Os valores de 0 a 5 são suportados; omita apenas para resultados diretos. Os resultados de mensagem direta, imagem e perfil são retidos, mas não são expandidos por gráfico.
  • max_linked_results int – Máximo de memórias vinculadas em todos os saltos anexados a cada resultado direto. Omita o padrão de 100; passe 0 para não retornar contexto vinculado.
  • escopo SearchScope – Escopo de pesquisa pré-criado opcional. Forneça scope ou o identificador explícito e os argumentos de correspondência exata, não ambos.
• Devoluções: resultados da pesquisa ordenados por relevância decrescente.
• Tipo de retorno: list[SearchResult]
• Gera: ValueError – Se scope for combinado com identificador explícito ou argumentos de correspondência exata, se max_results for menor que 1 ou se metadata_filter não for um dicionário nem None.

Observações

Os campos de escopo omitidos herdam o escopo de pesquisa padrão deste thread: correspondência exata de usuário e agente mais o user_id, agent_id e thread_id atuais deste thread. A pesquisa de thread padrão sai intencionalmente de exact_thread_match=False, para que possa retornar registros relevantes de outros threads para o mesmo usuário/agente. Informe exact_thread_match=True para restringir os resultados ao thread atual. Os valores explícitos do escopo None ainda seguem as regras de correspondência exata resolvidas: exact_*_match=False deixa essa dimensão sem restrições, enquanto exact_*_match=True corresponde apenas aos valores None armazenados.

Os valores max_results explícitos devem ser pelo menos 1; a omissão do argumento usa o valor padrão de 10. Este é um limite superior: a chamada pode retornar menos de max_results resultados quando os filtros são muito restritivos, quando há menos registros correspondentes ou por causa do comportamento de pesquisa específico da implementação.

método update_image

Atualize uma imagem pertencente a este thread.

Omita image para preservar os bytes existentes. Se image for fornecido, mime_type deverá ser fornecido com ele. Omita description para preservar a descrição existente. Informe None para gerar uma nova descrição com o LLM configurado; uma descrição não nula a substitui diretamente. A expiração de uma imagem anexada a uma mensagem deve ser alterada por meio de update_message().

• Retorna: O identificador de imagem atualizado.
• Tipo de retorno: str
• Raises: ValueError – Se as definições de expiração forem fornecidas para uma imagem anexada a uma mensagem.
• Parâmetros:
  • id_imagem str
  • imagem bytes
  • descrição str | None
  • mime_type ImageMimeType
  • metadados dict[str, Any] | None
  • marcador de data/hora str | None
  • ttl_days int | None
  • ttl_anchor TimeToLiveAnchor
  • kwargs Any

método update_image_async (assíncrono)

Atualize uma imagem pertencente a este thread de forma assíncrona.

Omita image para preservar os bytes existentes. Se image for fornecido, mime_type deverá ser fornecido com ele. Omita description para preservar a descrição existente. Informe None para gerar uma nova descrição com o LLM configurado; uma descrição não nula a substitui diretamente. As definições de metadados, timestamp e expiração são atualizadas quando fornecidas. A expiração de uma imagem anexada a uma mensagem deve ser alterada por meio de update_message_async().

• Retorna: O identificador de imagem atualizado.
• Tipo de retorno: str
• Raises: ValueError – Se as definições de expiração forem fornecidas para uma imagem anexada a uma mensagem.
• Parâmetros:
  • id_imagem str
  • imagem bytes
  • descrição str | None
  • mime_type ImageMimeType
  • metadados dict[str, Any] | None
  • marcador de data/hora str | None
  • ttl_days int | None
  • ttl_anchor TimeToLiveAnchor
  • kwargs Any

método update_memory

Atualize um registro semelhante à memória pertencente a este thread exato.

• Parâmetros:
  • memory_id str – Identificador de memória. Somente registros semelhantes à memória (memory, guideline, fact, preference) cujo thread_id armazenado corresponde exatamente a esse thread são atualizados.
  • content str – Conteúdo de substituição opcional. Forneça uma string para substituir o conteúdo armazenado. Quando omitido, o conteúdo armazenado é preservado. Omita content para manter o valor atual ou use delete_memory() para remover o registro.
  • metadata dict[str, Any] | None – Mapeamento de metadados de substituição opcional. Quando omitidos, os metadados armazenados são preservados. Quando fornecido, ele substitui o objeto de metadados armazenado; essa API não mescla metadados profundamente.
  • timestamp str | None – Novo timestamp opcional para essa memória. Representa quando a memória foi criada. Quando omitido, o timestamp armazenado é preservado. Informe None para limpar o timestamp salvo e usar o horário em que o registro foi criado no armazenamento. Quando ttl_anchor for TimeToLiveAnchor.TIMESTAMP, os timestamps de substituição deverão ser strings ISO-8601. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • ttl_days int | None – Atualização de expiração opcional em dias. Omita este argumento para deixar a expiração atual inalterada, a menos que ttl_anchor seja fornecido. Informe None para usar MemoryRetentionConfig.max_ttl_days quando a configuração de retenção definir uma, ou para limpar a expiração quando não o fizer. Os valores acima de MemoryRetentionConfig.max_ttl_days são limitados a esse máximo com uma advertência. Memórias expiradas não estão disponíveis para esta API de thread e não podem ser atualizadas.
  • ttl_anchor TimeToLiveAnchor – Âncora opcional de tempo de vida útil para uma atualização de expiração. Use TimeToLiveAnchor.CREATED_AT para o horário de criação da memória ou TimeToLiveAnchor.TIMESTAMP para o timestamp de substituição fornecido na mesma atualização ou o timestamp de evento armazenado quando timestamp for omitido. O fornecimento de ttl_anchor sem ttl_days usa a duração de tempo de vida padrão do esquema. Quando ttl_anchor é omitido durante uma atualização, o thread usa TimeToLiveAnchor.CREATED_AT. As atualizações com data/hora ancoradas exigem um timestamp ISO-8601 de substituição na mesma chamada ou um timestamp de evento armazenado existente nesse formato. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • status RecordStatus – Status do ciclo de vida de substituição opcional para este registro semelhante a memória. Omita-o para preservar o status atual.
  • **kwargs (Qualquer) – Argumentos de palavra-chave inesperados são rejeitados.
• Retorna: Identificador do registro semelhante à memória atualizado.
• Tipo de retorno: str

método update_memory_async (assíncrono)

Atualize um registro semelhante à memória pertencente a este thread exato de forma assíncrona.

• Parâmetros:
  • memory_id str – Identificador de memória. Somente registros semelhantes à memória (memory, guideline, fact, preference) cujo thread_id armazenado corresponde exatamente a esse thread são atualizados.
  • content str – Conteúdo de substituição opcional. Forneça uma string para substituir o conteúdo armazenado. Quando omitido, o conteúdo armazenado é preservado. Omita content para manter o valor atual ou use delete_memory() para remover o registro.
  • metadata dict[str, Any] | None – Mapeamento de metadados de substituição opcional. Quando omitidos, os metadados armazenados são preservados. Quando fornecido, ele substitui o objeto de metadados armazenado; essa API não mescla metadados profundamente.
  • timestamp str | None – Novo timestamp opcional para essa memória. Representa quando a memória foi criada. Quando omitido, o timestamp armazenado é preservado. Informe None para limpar o timestamp salvo e usar o horário em que o registro foi criado no armazenamento. Quando ttl_anchor for TimeToLiveAnchor.TIMESTAMP, os timestamps de substituição deverão ser strings ISO-8601. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • ttl_days int | None – Atualização de expiração opcional em dias. Omita este argumento para deixar a expiração atual inalterada, a menos que ttl_anchor seja fornecido. Informe None para usar MemoryRetentionConfig.max_ttl_days quando a configuração de retenção definir uma, ou para limpar a expiração quando não o fizer. Os valores acima de MemoryRetentionConfig.max_ttl_days são limitados a esse máximo com uma advertência. Memórias expiradas não estão disponíveis para esta API de thread e não podem ser atualizadas.
  • ttl_anchor TimeToLiveAnchor – Âncora opcional de tempo de vida útil para uma atualização de expiração. Use TimeToLiveAnchor.CREATED_AT para o horário de criação da memória ou TimeToLiveAnchor.TIMESTAMP para o timestamp de substituição fornecido na mesma atualização ou o timestamp de evento armazenado quando timestamp for omitido. O fornecimento de ttl_anchor sem ttl_days usa a duração de tempo de vida padrão do esquema. Quando ttl_anchor é omitido durante uma atualização, o thread usa TimeToLiveAnchor.CREATED_AT. As atualizações com data/hora ancoradas exigem um timestamp ISO-8601 de substituição na mesma chamada ou um timestamp de evento armazenado existente nesse formato. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • status RecordStatus – Status do ciclo de vida de substituição opcional para este registro semelhante a memória. Omita-o para preservar o status atual.
  • **kwargs (Qualquer) – Argumentos de palavra-chave inesperados são rejeitados.
• Retorna: Identificador do registro semelhante à memória atualizado.
• Tipo de retorno: str

Exemplos

import asyncio
memory_id = asyncio.run(thread.add_memory_async("Original memory"))
(
    asyncio.run(thread.update_memory_async(
        memory_id, content="Updated memory"
    ))
    == memory_id
)
True

método update_message

Atualize um registro de mensagem bruta pertencente a este thread exato.

• Parâmetros:
  • message_id str – Identificador da mensagem. Somente mensagens cujo thread_id armazenado corresponde exatamente a este thread são atualizadas.
  • content str | list[Mapping[str, Any]] – Conteúdo de mensagem de substituição opcional. Forneça uma string para substituir o conteúdo armazenado ou uma sequência ordenada de partes de conteúdo de texto e imagem. Quando omitido, o conteúdo armazenado é preservado. Use uma string vazia para substituí-la pelo conteúdo de texto vazio.
  • metadata dict[str, Any] | None – Mapeamento de metadados de substituição opcional. Quando omitidos, os metadados armazenados são preservados. Quando fornecido, ele substitui o objeto de metadados armazenado; essa API não mescla metadados profundamente.
  • ttl_days int | None – Atualização de expiração opcional em dias. Omita este argumento para deixar a expiração atual inalterada, a menos que ttl_anchor seja fornecido. Informe None para usar MemoryRetentionConfig.max_ttl_days quando a configuração de retenção definir uma, ou para limpar a expiração quando não o fizer. Os valores acima de MemoryRetentionConfig.max_ttl_days são limitados a esse máximo com uma advertência. As mensagens expiradas estão indisponíveis para esta API de thread e não podem ser atualizadas.
  • ttl_anchor TimeToLiveAnchor – Âncora opcional de tempo de vida útil para uma atualização de expiração. Use TimeToLiveAnchor.CREATED_AT para o horário de criação da mensagem ou TimeToLiveAnchor.TIMESTAMP para o timestamp de evento armazenado. O fornecimento de ttl_anchor sem ttl_days usa a duração de tempo de vida padrão do esquema. Quando ttl_anchor é omitido durante uma atualização, o thread usa TimeToLiveAnchor.CREATED_AT. As atualizações vinculadas ao timestamp exigem um timestamp de mensagem ISO-8601 armazenado existente. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • **kwargs (Qualquer) – Argumentos de palavra-chave inesperados são rejeitados.
• Devoluções: Identificador do registro de mensagem atualizado.
• Tipo de retorno: str

Observações

Os campos omitidos são preservados do registro armazenado. A atribuição armazenada e o timestamp permanecem inalterados. A edição de conteúdo atualiza o histórico de mensagens brutas e, quando a extração automática é ativada, pode fazer com que o SDK extraia novamente memórias da mensagem editada e do histórico anterior. No modo INLINE, essa extração é concluída antes que esse método seja retornado. No modo BACKGROUND, esse método retorna depois que a atualização da mensagem bruta é bem-sucedida e a extração em segundo plano é tentada. Este trabalho de acompanhamento não afeta a frequência de extração normal usada por chamadas add_messages() posteriores. As memórias extraídas existentes permanecem no lugar, enquanto as memórias recém-extraídas do conteúdo editado podem ser adicionadas. Como a atualização da mensagem bruta e quaisquer gravações de memória extraída posteriores não acontecem de forma atômica, as memórias extraídas ainda poderão refletir o conteúdo da mensagem anterior se o trabalho em segundo plano não for enfileirado, se uma espera de capacidade de fila configurada atingir seu timeout ou se o trabalho de extração posterior falhar. Além disso, observe que as memórias extraídas existentes mantêm sua expiração original quando o TTL de uma mensagem de origem é alterado.

Exemplos

message_id = thread.add_messages([{"role": "user", "content": "Draft message"}])[0]
thread.update_message(message_id, content="Edited message") == message_id
True

método update_message_async (assíncrono)

Atualize um registro de mensagem bruta pertencente a este thread exato de forma assíncrona.

• Parâmetros:
  • message_id str – Identificador da mensagem. Somente mensagens cujo thread_id armazenado corresponde exatamente a este thread são atualizadas.
  • content str | list[Mapping[str, Any]] – Conteúdo de mensagem de substituição opcional. Forneça uma string para substituir o conteúdo armazenado ou uma sequência ordenada de partes de conteúdo de texto e imagem. Quando omitido, o conteúdo armazenado é preservado. Use uma string vazia para substituí-la pelo conteúdo de texto vazio.
  • metadata dict[str, Any] | None – Mapeamento de metadados de substituição opcional. Quando omitidos, os metadados armazenados são preservados. Quando fornecido, ele substitui o objeto de metadados armazenado; essa API não mescla metadados profundamente.
  • ttl_days int | None – Atualização de expiração opcional em dias. Omita este argumento para deixar a expiração atual inalterada, a menos que ttl_anchor seja fornecido. Informe None para usar MemoryRetentionConfig.max_ttl_days quando a configuração de retenção definir uma, ou para limpar a expiração quando não o fizer. Os valores acima de MemoryRetentionConfig.max_ttl_days são limitados a esse máximo com uma advertência. As mensagens expiradas estão indisponíveis para esta API de thread e não podem ser atualizadas.
  • ttl_anchor TimeToLiveAnchor – Âncora opcional de tempo de vida útil para uma atualização de expiração. Use TimeToLiveAnchor.CREATED_AT para o horário de criação da mensagem ou TimeToLiveAnchor.TIMESTAMP para o timestamp de evento armazenado. O fornecimento de ttl_anchor sem ttl_days usa a duração de tempo de vida padrão do esquema. As atualizações vinculadas ao timestamp exigem um timestamp de mensagem ISO-8601 armazenado existente. Os timestamps ISO-8601 sem fuso horário são tratados como UTC.
  • **kwargs (Qualquer) – Argumentos de palavra-chave inesperados são rejeitados.
• Devoluções: Identificador do registro de mensagem atualizado.
• Tipo de retorno: str

Observações

Os campos omitidos são preservados do registro armazenado. A atribuição armazenada e o timestamp permanecem inalterados. A edição de conteúdo atualiza o histórico de mensagens brutas e, quando a extração automática é ativada, pode fazer com que o SDK extraia novamente memórias da mensagem editada e do histórico anterior. No modo INLINE, essa extração é concluída antes que esse método seja retornado. No modo BACKGROUND, esse método retorna depois que a atualização da mensagem bruta é bem-sucedida e a extração em segundo plano é tentada. Este trabalho de acompanhamento não afeta a frequência de extração normal usada por chamadas add_messages() posteriores. As memórias extraídas existentes permanecem no lugar, enquanto as memórias recém-extraídas do conteúdo editado podem ser adicionadas. Como a atualização da mensagem bruta e quaisquer gravações de memória extraída posteriores não acontecem de forma atômica, as memórias extraídas ainda poderão refletir o conteúdo da mensagem anterior se o trabalho em segundo plano não for enfileirado, se uma espera de capacidade de fila configurada atingir seu timeout ou se o trabalho de extração posterior falhar. Além disso, observe que as memórias extraídas existentes mantêm sua expiração original quando o TTL de uma mensagem de origem é alterado.

Exemplos

import asyncio
message_ids = asyncio.run(thread.add_messages_async(
    [{"role": "user", "content": "Draft message"}]
))
(
    asyncio.run(thread.update_message_async(
        message_ids[0], content="Edited message"
    ))
    == message_ids[0]
)
True

método update_record_link

Atualize uma relação cujos pontos finais pertencem a este thread.

Os valores omitidos são preservados. Quando relation_type muda para um tipo de relação de memória incorporado, seu label reverso fixo substitui opposite_relation_type.

• Parâmetros:
  • relation_id str – Identificador da relação de propriedade do thread.
  • relation_type str – Rótulo de origem para destino de substituição opcional.
  • opposite_relation_type str – Rótulo de inversão de substituição opcional. Omita-o para preservar o rótulo armazenado.
  • timestamp str | None – Timestamp de substituição opcional. Informe None para limpá-lo.
  • metadata dict[str, Any] | None – Metadados de substituição opcionais. Ele substitui o objeto armazenado.
• Retorna: Número de relações atualizadas, 0 ou 1.
• Tipo de retorno: int

Exemplos

thread.update_record_link("relation-id", relation_type="supports")
1

método update_record_link_async (assíncrono)

Atualizar assincronicamente uma relação cujos pontos finais pertencem a este thread.

• Parâmetros:
  • id_relação str
  • tipo_relação str
  • opposite_relation_type str
  • marcador de data/hora str | None
  • metadados dict[str, Any] | None
• Tipo de retorno: int

método wait_for_memory_extraction

Aguarde a extração de memória em segundo plano anterior para este thread.

Esse método aguarda a extração em segundo plano iniciada por chamadas add_messages(), add_messages_async(), update_message() ou update_message_async() anteriores nesse thread por meio do mesmo componente de memória do agente. Se uma dessas chamadas já está terminando, este método inclui a extração que começa antes de esperar.

O método não aguarda o início da extração após o início dessa espera, a extração iniciada por um componente de memória de agente diferente ou a extração em execução em outro processo. As falhas de extração contam como concluídas para esta espera.

• Parâmetros: timeout float | None – Número máximo opcional de segundos para aguardar. Assume 300 como padrão. Informe None para aguardar até que a extração pendente deste thread seja concluída.
• Gera: TimeoutError – Gerado quando o timeout expira antes da conclusão da extração em segundo plano anterior.
• Tipo de retorno: Nenhum

Exemplos

thread.wait_for_memory_extraction(timeout=10)

método wait_for_memory_extraction_async (assíncrono)

Aguarde assincronamente a extração de memória em segundo plano anterior.

Este método segue o mesmo comportamento de wait_for_memory_extraction().

• Parâmetros: timeout float | None – Número máximo opcional de segundos para aguardar. Assume 300 como padrão. Informe None para aguardar indefinidamente.
• Gera: TimeoutError – Gerado quando o timeout expira antes da conclusão da extração em segundo plano anterior.
• Tipo de retorno: Nenhum

Exemplos

import asyncio
asyncio.run(thread.wait_for_memory_extraction_async(timeout=10))

Observação: delete_message() exclui somente a linha de mensagem bruta. Memórias derivadas ainda podem ser pesquisadas ou aparecer em cartões de contexto. Use OracleAgentMemory.delete_thread() para excluir o thread junto com suas mensagens e memórias associadas. A exclusão de mensagem e memória por meio de um identificador de thread aguarda a extração em segundo plano anterior já aceita pelo cliente anexado para esse thread. Essa não é uma barreira de simultaneidade global para outras instâncias, processos ou trabalhos do cliente aceitos após o início da espera.

Mensagens e conteúdo da mensagem

classe oracleagentmemory.apis.message.Message

Bases: object

A mensagem na memória compartilhada por threads e adaptadores LLM.

• Parâmetros:
  • função str – A função de mensagem. Nomes de função personalizados são permitidos para mensagens de thread.
  • conteúdo str | collections.abc.Sequence[oracleagentmemory.apis.message.MessageContent] – O texto da mensagem ou uma sequência ordenada de partes de TextContent e ImageContent. Uma sequência de conteúdo não deve ficar vazia e é armazenada como uma tupla imutável.
  • timestamp str | None – Timestamp opcional associado à mensagem.
  • metadata dict[str, Any] | None – Metadados opcionais compatíveis com JSON associados à mensagem.
  • id str | None – Identificador de mensagem estável opcional. As lojas geram uma quando a mensagem é adicionada sem um identificador.

classe oracleagentmemory.apis.message.MessageContent

Bases: ABC

Classe base para conteúdo de mensagem estruturada.

• Parâmetros:
  • id str – Identificador estável para esta parte de conteúdo. Gerado automaticamente quando omitido.
  • timestamp str | None – Timestamp opcional associado a essa parte do conteúdo.

classe oracleagentmemory.apis.message.TextContent

Bases: MessageContent

Uma parte de texto em uma mensagem multimodal.

• Parâmetros:
  • texto str – Texto transportado por essa parte do conteúdo.
  • id str – Identificador estável herdado de MessageContent. Gerado automaticamente quando omitido.
  • timestamp str | None – Timestamp opcional herdado de MessageContent.

classe oracleagentmemory.apis.message.ImageContent

Bases: MessageContent

Uma parte da imagem em uma mensagem multimodal.

• Parâmetros:
  • bytes bytes | None – Os dados da imagem quando disponíveis. None é permitido quando uma mensagem contém metadados de imagem sem carregar os bytes de imagem.
  • mime_type oracleagentmemory.apis.message.ImageMimeType – O tipo MIME da imagem.
  • description str | None – Texto opcional descrevendo a imagem. Quando None, as APIs de imagem e mensagem de alto nível podem gerar uma descrição usando seu LLM configurado.
  • id str – Identificador estável herdado de MessageContent. Gerado automaticamente quando omitido.
  • timestamp str | None – Timestamp opcional herdado de MessageContent.

classe oracleagentmemory.apis.message.ImageMimeType

Bases: str, Enum

Tipos MIME suportados para conteúdo de imagem.

PNG e WebP animados não são suportados.

JPEG = 'image/JPEG'

PNG = 'image/PNG'

WEBP = 'imagem/WEBP'

Cartões de Contexto

classe oracleagentmemory.apis.contextcard.ContextCard

Bases: ABC

Objeto de cartão de contexto abstrato retornado por APIs de thread.

propriedade content (abstrato)

• Tipo de Retorno: str
• Descrição: Retorna o texto do cartão de contexto renderizado.

classe oracleagentmemory.core.contextcard.OracleContextCard

Bases: ContextCard

Cartão de contexto retornado por um thread Oracle.

• Parâmetros:
  • resumo str – Texto resumido incorporado ao cartão.
  • tópicos Sequence[str] | None – Tópicos de recuperação opcionais associados ao thread.
  • relevant_results Sequence[SearchResult] | None – Registros duráveis recuperados opcionais incluídos no cartão.
  • recent_messages Sequence[Message] | None – Mensagens brutas recentes opcionais renderizadas no cartão.
  • message_format str – Modelo interno usado ao renderizar recent_messages.

propriedade content

• Tipo de Retorno: str

• Descrição: Retorna o texto do cartão de contexto renderizado.

• Retorna: Texto de cartão de contexto renderizado semelhante a XML adequado para montagem de prompt.
• Tipo de retorno: str

Exemplos

card = OracleContextCard(summary="ctx")
"<summary>" in card.content and "ctx" in card.content
True

propriedade formatted_content

• Tipo de Retorno: str

• Descrição: Retorna o texto do cartão de contexto renderizado usado em fluxos de criação de prompt.

• Retorna: texto de cartão de contexto renderizado semelhante a XML.
• Tipo de retorno: str

Exemplos

OracleContextCard(summary="").formatted_content
''
card = OracleContextCard(summary="ctx", topics=["travel"])
"<topics>" in card.formatted_content
True

Resumos

classe oracleagentmemory.apis.summary.Summary

Bases: ABC

Objeto de resumo de thread resumido retornado por APIs de thread.

propriedade content (abstrato)

• Tipo de Retorno: str
• Descrição: Retorna o texto de resumo sintetizado.

classe oracleagentmemory.core.summary.OracleSummary

Bases: Summary

Resumo retornado por um thread Oracle.

• Parâmetros: content str – Texto de resumo sintetizado a partir da transcrição do thread.

Exemplos

summary = OracleSummary(content="Plan the Rome itinerary.")
summary.content
'Plan the Rome itinerary.'
str(summary)
'Plan the Rome itinerary.'

propriedade content

• Tipo de Retorno: str

• Descrição: Retorna o texto de resumo sintetizado.

• Retorna: Texto de resumo do thread.
• Tipo de retorno: str

Exemplos

OracleSummary(content="Keep the tea preference in mind.").content
'Keep the tea preference in mind.'

propriedade formatted_content

• Tipo de Retorno: str

• Descrição: Retorna o texto resumido renderizado usado em fluxos de criação de prompt.

• Retorna: Texto de resumo renderizado.
• Tipo de retorno: str

Exemplos

OracleSummary(content="Thread recap").formatted_content
'Thread recap'