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, um UUID é 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.

  • 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 as quais o resumo do contexto de extração deve ser atualizado. Defina como -1 para resumir apenas uma vez por chamada add_messages usando o batch completo de mensagens recém-adicionadas. O padrão é -1.

    Info: Obsoleto desde a versão 26.6.0: Este parâmetro estava obsoleto 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.

    Info: Obsoleto desde a versão 26.6.0: Este parâmetro estava obsoleto 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.

    Info: Obsoleto desde a versão 26.6.0: Este parâmetro estava obsoleto 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 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. O padrão é True para OracleThread() autônomo.

    Info: Obsoleto desde a versão 26.6.0: Este parâmetro estava obsoleto 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.

    Info: Obsoleto desde a versão 26.6.0: Este parâmetro estava obsoleto 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.

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

  • cliente OracleAgentMemory | None

Exemplos de

from oracleagentmemory.core import OracleAgentMemory
import oracledb
db_pool = oracledb.SessionPool(
    user="YOUR DB USER",
    password="YOUR DB PASSWORD",
    dsn="YOUR DB CONNECT STRING",
)
client = OracleAgentMemory(connection=db_pool, embedder=embedder)
thread = client.create_thread(
    thread_id="c1",
    llm=llm,
    memory_extraction_config=MemoryExtractionConfig(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.
  • 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 opcional para salvar essa memória. Representa quando a memória foi criada. Quando omitido ou None, o armazenamento usa a hora atual. 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.
  • **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_memory_async (assíncrono)

Adicione uma memória de forma assíncrona.

• Parâmetros:
  • content str – Conteúdo na memória a ser armazenado.
  • 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 escopo do usuário opcional.
  • agent_id str – Substituição do escopo do agente opcional.
  • thread_id str – Substituição de escopo de thread opcional.
  • memory_id str – Identificador de memória fornecido pelo chamador opcional. Quando omitido, as lojas geram um ID.
  • metadados dict[str, Any] | None – Metadados opcionais para persistir com a memória armazenada.
  • timestamp str | None – Timestamp opcional para salvar essa memória. Representa quando a memória foi criada. Quando omitido ou None, o armazenamento usa a hora atual.
  • 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 ou passe None para uma memória que não expire.
  • ttl_anchor TimeToLiveAnchor – Âncora de tempo de vida opcional. Use TimeToLiveAnchor.CREATED_AT ou TimeToLiveAnchor.TIMESTAMP.
  • **store_kwargs (Qualquer) – Opções de gravação específicas de implementação encaminhadas para o armazenamento de apoio.
• Tipo de retorno: str

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.

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

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.

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 list[Message | MessageT]
  • 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_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

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

Observações

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 de

thread.delete_message("123")
0

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 duráveis recuperados a serem incluídos. Quando omitido, isso é resolvido para 5, a menos que min_relevant_results_by_type seja fornecido; nesse caso, ele é resolvido para o maior de 5 e a soma dos mínimos por tipo solicitados.
  • max_recent_messages int – Número máximo de mensagens brutas posteriores a serem incorporadas textualmente. Quando omitido, isso é resolvido para 5.
  • min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker – Mínimos opcionais por tipo para registros semelhantes à memória 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" e "preference".
  • **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 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().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 duráveis recuperados a serem incluídos. Quando omitido, isso é resolvido para 5, a menos que min_relevant_results_by_type seja fornecido; nesse caso, ele é resolvido para o maior de 5 e a soma dos mínimos por tipo solicitados.
  • max_recent_messages int – Número máximo de mensagens brutas posteriores a serem incorporadas textualmente. Quando omitido, isso é resolvido para 5.
  • min_relevant_results_by_type Mapping[Literal['memory', 'guideline', 'fact', 'preference'], int] | None | ~oracleagentmemory._notset._NotSetMarker – Mínimos opcionais por tipo para registros semelhantes à memória 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" e "preference".
  • **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 de

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

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_messages_async (assíncrono)

Retornar mensagens de tópico brutas de forma assíncrona.

• Parâmetros:
  • start int | None – Índice de início opcional.
  • end int | None – Índice final opcional.
• Retorna: Objetos de mensagem bruta.
• Tipo de retorno: list[Mensagem]

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: Objeto de resumo que contém o texto de resumo do thread sintetizado.
• Tipo da devolução: OracleSummary

Exemplos de

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 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) – 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 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.
  • record_types list[str] – Lista opcional de tipos de registro a incluir, como "memory" ou "message".

  • 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"},
        },
    }

  • 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.
  • record_types list[str] – Lista opcional de tipos de registro a incluir, como "memory" ou "message".

  • 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"},
        },
    }

  • 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_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. Não há suporte para informar None; 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.
  • **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)

Atualizar um registro semelhante a memória de forma assíncrona.

• Parâmetros:
  • memory_id str – Identificador do registro semelhante à memória a ser atualizado.
  • 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. Não há suporte para informar None; 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.
  • ttl_days int | None – Atualização de expiração opcional em dias. Omita esse argumento junto com ttl_anchor para preservar o timestamp de expiração atual. Informe None para limpar a expiração.
  • ttl_anchor TimeToLiveAnchor – Âncora opcional de tempo de vida útil para uma atualização de expiração. O fornecimento de ttl_anchor sem ttl_days usa a duração de tempo de vida padrão do esquema.
  • **kwargs (Qualquer) – Argumentos de palavra-chave inesperados são rejeitados.
• Retorna: Identificador do registro semelhante à memória atualizado.
• Tipo de retorno: str

Exemplos de

from functools import partial
from oracleagentmemory._async_helpers import run_async_in_sync
memory_id = thread.add_memory("Original memory")
run_async_in_sync(
    partial(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 – Conteúdo de mensagem de substituição opcional. Forneça uma string para substituir o conteúdo armazenado. Quando omitido, o conteúdo armazenado é preservado. A transmissão de None não é suportada.
  • 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 de

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 – Conteúdo de mensagem de substituição opcional. Forneça uma string para substituir o conteúdo armazenado. Quando omitido, o conteúdo armazenado é preservado. A transmissão de None não é suportada.
  • 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 de

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

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 de

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 de

await 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 thread no nível do cliente aguarda a extração em segundo plano aceita anteriormente já conhecida para esse thread, mas não é uma barreira de simultaneidade global para outras operações no mesmo thread enquanto a exclusão está em andamento.

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

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 de

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 de

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 de

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 de

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 de

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