Threads

Esta página presenta el identificador de thread de Oracle concreto junto con el tipo de ayuda de mensaje orientado al desarrollador.

Thread de Oracle

clase oracleagentmemory.core.OracleThread

Bases: IThread

Thread respaldado por un almacén de Oracle.

Esta implantación incrusta y almacena tanto mensajes de thread como memorias agregadas manualmente y, a continuación, soporta la búsqueda de similitud en todos los registros almacenados.

Notas

Cree una nueva instancia de OracleThread.

Ejemplos

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

Mantener una imagen asociada a este thread.

description se almacena como texto que permite la búsqueda de la imagen. Cuando se omite o None, un LLM asociado genera un título. Los valores de ámbito omitidos heredan los identificadores de usuario, agente y thread correspondientes de este thread.

method add_image_async (async)

Mantener una imagen asociada a este thread de forma asíncrona.

description se almacena como texto que permite la búsqueda de la imagen. Cuando se omite o None, un LLM asociado genera un título. Los valores de ámbito omitidos heredan los identificadores de usuario, agente y thread correspondientes de este thread.

método add_memory

Agregue una entrada de memoria manual e indíquela.

Ejemplos

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

method add_memory_async (async)

Agregue una entrada de memoria manual e indíquela de forma asíncrona.

Ejemplos

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

Agregar mensajes al hilo y indexarlos.

En el modo de extracción en segundo plano, este método se devuelve después de insertar los mensajes raw y de intentar la extracción en segundo plano en segundo plano.

Los mensajes raw se almacenan antes de la extracción automática en cualquier modo. Si falla la extracción posterior o el almacenamiento de memoria derivada, los mensajes raw permanecen almacenados mientras faltan las memorias derivadas o las actualizaciones de resumen.

Notas

En MemoryExtractionMode.BACKGROUND, los mensajes raw se mantienen antes de que se almacenen las memorias extraídas. Si la extracción en segundo plano no se pone en cola o si una espera de capacidad de cola configurada alcanza su timeout, los mensajes raw insertados permanecen almacenados y la llamada continúa sin memorias extraídas o emite TimeoutError, según background_extraction_queue_full_behavior.

Ejemplos

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

method add_messages_async (async)

Agregar mensajes al thread de forma asíncrona e indexarlos.

En el modo de extracción en segundo plano, este método se devuelve después de insertar los mensajes raw y de intentar la extracción en segundo plano en segundo plano.

Los mensajes raw se almacenan antes de la extracción automática en cualquier modo. Si falla la extracción posterior o el almacenamiento de memoria derivada, los mensajes raw permanecen almacenados mientras faltan las memorias derivadas o las actualizaciones de resumen.

En MemoryExtractionMode.BACKGROUND, los mensajes raw se mantienen antes de que se almacenen las memorias extraídas. Si la extracción en segundo plano no se pone en cola o si una espera de capacidad de cola configurada alcanza su timeout, los mensajes raw insertados permanecen almacenados y la llamada continúa sin memorias extraídas o emite TimeoutError, según background_extraction_queue_full_behavior.

método delete_image

Borrar una imagen que pertenece a este tema.

method delete_image_async (async)

Suprimir una imagen propiedad de este thread de forma asíncrona.

método delete_memory

Eliminar un registro similar a la memoria (por ejemplo, una memoria, un hecho, una preferencia o una directriz) de este thread exacto por identificador.

Notas

Antes de suprimir el registro, este método espera a que se acepte una extracción en segundo plano anterior para este thread mediante el componente de memoria del agente asociado. No espera a que se acepte el trabajo después de que comience la espera o al trabajo iniciado por otro componente o proceso.

Ejemplos

thread.delete_memory("456")
0

method delete_memory_async (async)

Eliminar un registro similar a la memoria (por ejemplo, una memoria, un hecho, una preferencia o una directriz) de este thread exacto por identificador de forma asíncrona.

Notas

Este método sigue el comportamiento de simultaneidad y espera de extracción en segundo plano documentado por delete_memory().

Ejemplos

import asyncio
asyncio.run(thread.delete_memory_async("456"))
0

método delete_message

Eliminar un registro de mensaje de este hilo exacto por identificador.

Notas

Antes de suprimir el mensaje, este método espera a que se acepte una extracción en segundo plano anterior para este thread a través del componente de memoria del agente asociado. No espera a que se acepte el trabajo después de que comience la espera o al trabajo iniciado por otro componente o proceso.

Al eliminar un mensaje, solo se elimina el registro de mensaje sin formato. Las memorias derivadas no se eliminan porque todavía no rastreamos qué memorias extraídas provienen de qué mensaje, por lo que pueden seguir siendo buscables o aún afectar la salida de la tarjeta de contexto. Utilice OracleAgentMemory.delete_thread() para suprimir el thread junto con sus mensajes y memorias asociados.

Ejemplos

thread.delete_message("123")
0

method delete_message_async (async)

Eliminar un registro de mensaje de este thread exacto por identificador de forma asíncrona.

Notas

Este método sigue el comportamiento de simultaneidad y espera de extracción en segundo plano documentado por delete_message().

Al eliminar un mensaje, solo se elimina el registro de mensaje sin formato. Las memorias derivadas no se eliminan porque todavía no rastreamos qué memorias extraídas provienen de qué mensaje, por lo que pueden seguir siendo buscables o aún afectar la salida de la tarjeta de contexto. Utilice OracleAgentMemory.delete_thread() para suprimir el thread junto con sus mensajes y memorias asociados.

Ejemplos

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

Suprima una relación propiedad de thread por ID o tupla de punto final completa.

Los selectores de tupla de punto final deben utilizar la orientación de origen a destino almacenada.

Ejemplos

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

Suprima de forma asíncrona una relación que sea propiedad de este thread.

método get_context_card

Devolver un objeto de tarjeta de contexto para el thread.

Preferir get_context_card_async cuando una implementación respaldada por LLM puede realizar E/S de red remota.

Notas

Esto utiliza el ámbito de búsqueda predeterminado del thread con exact_thread_match=False, por lo que se pueden incluir memorias relevantes de otros threads para el mismo usuario/agente.

Ejemplos

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

method get_context_card_async (async)

Devolver de forma asíncrona un objeto de tarjeta de contexto para el thread.

Ejemplos

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

Devolver un mensaje propiedad de este hilo.

Las partes de la imagen se devuelven con sus identificadores y descripciones por defecto. Transfiera included_image_ids para cargar bytes para las partes de imagen seleccionadas. Se ignoran los identificadores no relacionados.

method get_message_async (async)

Devolver un mensaje propiedad de thread de forma asíncrona.

included_image_ids selecciona opcionalmente partes de imagen adjuntas cuyos bytes se deben cargar; omite o None devuelve sólo metadatos de imagen.

método get_messages

Devolver mensajes almacenados para este tema.

Ejemplos

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

method get_messages_async (async)

Obtenga los mensajes sin procesar del thread como se han agregado con add_messages de forma asíncrona.

Ejemplos

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

Devolver un resumen del thread.

Una solicitud de thread completo reutiliza o refresca el resumen duradero. Una solicitud con except_last resume ese prefijo sin cambiar el resumen duradero de thread completo.

Preferir get_summary_async cuando una implementación respaldada por LLM puede realizar E/S de red remota.

Ejemplos

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

method get_summary_async (async)

Devuelve de forma asíncrona un resumen del thread.

Una solicitud de thread completo reutiliza o refresca el resumen duradero. Una solicitud con except_last resume ese prefijo sin cambiar el resumen duradero de thread completo.

Cree una relación dirigida entre dos registros que sean propiedad de este thread.

Actualmente, ambos puntos finales deben ser registros similares a la memoria: "memory", "fact", "guideline" o "preference". Los tipos de relación incorporados son "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") y "duplicates". "contradicts" y "duplicates" utilizan la misma etiqueta a la inversa.

Ambos puntos finales deben pertenecer a este thread exacto. Solo se puede almacenar una orientación para un par de puntos finales. opposite_relation_type nombra la relación al pasar del destino al origen; por ejemplo, new "supersedes" old se convierte en old "is_superseded_by" new en esa dirección.

Ejemplos

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

Cree de forma asíncrona una relación entre los registros que pertenecen a este thread.

Actualmente, ambos puntos finales deben ser registros similares a la memoria: "memory", "fact", "guideline" o "preference". Los tipos de relación incorporados son "supersedes" ("is_superseded_by"), "contradicts", "refines" ("is_refined_by"), "supports" ("is_supported_by") y "duplicates". "contradicts" y "duplicates" utilizan la misma etiqueta a la inversa.

método list_images

Mostrar registros de imagen propiedad de este thread.

Los registros devueltos contienen metadatos de imagen por defecto. Los bytes sin formato solo se cargan cuando se proporcionan include_bytes=True y image_id.

method list_images_async (async)

Mostrar registros de imágenes propiedad de este thread de forma asíncrona.

Los registros devueltos contienen metadatos de imagen por defecto. Los bytes sin formato solo se cargan cuando se proporcionan include_bytes=True y image_id. El ámbito de este thread se aplica automáticamente.

Búsqueda sincrónica de registros relevantes para una consulta.

Notas

Los campos de ámbito omitidos heredan el ámbito de búsqueda por defecto de este thread: coincidencia exacta de usuario y agente más los valores user_id, agent_id y thread_id actuales de este thread. La búsqueda de subprocesos predeterminada deja intencionadamente exact_thread_match=False, por lo que puede devolver registros relevantes de otros subprocesos para el mismo usuario/agente. Transfiera exact_thread_match=True para restringir los resultados al thread actual. Los valores de ámbito None explícitos siguen las reglas de coincidencia exacta resueltas: exact_*_match=False deja esa dimensión sin restricciones, mientras que exact_*_match=True solo coincide con los valores None almacenados.

Los valores max_results explícitos deben ser al menos 1; al omitir el argumento se utiliza el valor por defecto de 10. Este es un límite superior: la llamada puede devolver menos de max_results resultados cuando los filtros son demasiado restrictivos, cuando hay menos registros coincidentes o debido al comportamiento de búsqueda específico de la implementación.

method search_async (async)

Busque de forma asíncrona registros relevantes para una consulta.

Notas

Los campos de ámbito omitidos heredan el ámbito de búsqueda por defecto de este thread: coincidencia exacta de usuario y agente más los valores user_id, agent_id y thread_id actuales de este thread. La búsqueda de subprocesos predeterminada deja intencionadamente exact_thread_match=False, por lo que puede devolver registros relevantes de otros subprocesos para el mismo usuario/agente. Transfiera exact_thread_match=True para restringir los resultados al thread actual. Los valores de ámbito None explícitos siguen las reglas de coincidencia exacta resueltas: exact_*_match=False deja esa dimensión sin restricciones, mientras que exact_*_match=True solo coincide con los valores None almacenados.

Los valores max_results explícitos deben ser al menos 1; al omitir el argumento se utiliza el valor por defecto de 10. Este es un límite superior: la llamada puede devolver menos de max_results resultados cuando los filtros son demasiado restrictivos, cuando hay menos registros coincidentes o debido al comportamiento de búsqueda específico de la implementación.

método update_image

Actualice una imagen que sea propiedad de este thread.

Omita image para conservar los bytes existentes. Si se proporciona image, se debe proporcionar mime_type. Omita description para conservar la descripción existente. Transfiera None para generar una nueva descripción con el LLM configurado; una descripción no nula la reemplaza directamente. La caducidad de una imagen asociada a un mensaje se debe cambiar mediante update_message().

method update_image_async (async)

Actualice una imagen propiedad de este thread de forma asíncrona.

Omita image para conservar los bytes existentes. Si se proporciona image, se debe proporcionar mime_type. Omita description para conservar la descripción existente. Transfiera None para generar una nueva descripción con el LLM configurado; una descripción no nula la reemplaza directamente. Los metadatos, el registro de hora y la configuración de caducidad se actualizan cuando se proporcionan. La caducidad de una imagen asociada a un mensaje se debe cambiar mediante update_message_async().

método update_memory

Actualice un registro similar a la memoria que sea propiedad de este thread exacto.

method update_memory_async (async)

Actualice un registro similar a la memoria propiedad de este thread exacto de forma asíncrona.

Ejemplos

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

Actualizar un registro de mensaje raw propiedad de este thread exacto.

Notas

Los campos omitidos se conservan del registro almacenado. El rol almacenado y el registro de hora permanecen sin cambios. La edición del contenido actualiza el historial de mensajes raw y, cuando la extracción automática está activada, puede hacer que el SDK vuelva a extraer las memorias del mensaje editado y del historial anterior. En el modo INLINE, esa extracción finaliza antes de que se devuelva este método. En el modo BACKGROUND, este método se devuelve después de que la actualización del mensaje raw se realiza correctamente y se intenta la extracción en segundo plano. Este trabajo de seguimiento no afecta a la frecuencia de extracción normal que utilizan las llamadas add_messages() posteriores. Las memorias extraídas existentes permanecen en su lugar mientras que las memorias recién extraídas del contenido editado pueden agregarse. Debido a que la actualización del mensaje sin formato y las escrituras de memoria extraídas posteriores no se producen atómicamente, las memorias extraídas aún pueden reflejar el contenido del mensaje anterior si el trabajo en segundo plano no se pone en cola, si una espera de capacidad de cola configurada alcanza su timeout o si falla el trabajo de extracción posterior. Además, tenga en cuenta que las memorias extraídas existentes mantienen su caducidad original cuando cambia el TTL de un mensaje de origen.

Ejemplos

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

method update_message_async (async)

Actualice un registro de mensaje raw propiedad de este thread exacto de forma asíncrona.

Notas

Los campos omitidos se conservan del registro almacenado. El rol almacenado y el registro de hora permanecen sin cambios. La edición del contenido actualiza el historial de mensajes raw y, cuando la extracción automática está activada, puede hacer que el SDK vuelva a extraer las memorias del mensaje editado y del historial anterior. En el modo INLINE, esa extracción finaliza antes de que se devuelva este método. En el modo BACKGROUND, este método se devuelve después de que la actualización del mensaje raw se realiza correctamente y se intenta la extracción en segundo plano. Este trabajo de seguimiento no afecta a la frecuencia de extracción normal que utilizan las llamadas add_messages() posteriores. Las memorias extraídas existentes permanecen en su lugar mientras que las memorias recién extraídas del contenido editado pueden agregarse. Debido a que la actualización del mensaje sin formato y las escrituras de memoria extraídas posteriores no se producen atómicamente, las memorias extraídas aún pueden reflejar el contenido del mensaje anterior si el trabajo en segundo plano no se pone en cola, si una espera de capacidad de cola configurada alcanza su timeout o si falla el trabajo de extracción posterior. Además, tenga en cuenta que las memorias extraídas existentes mantienen su caducidad original cuando cambia el TTL de un mensaje de origen.

Ejemplos

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

Actualizar una relación cuyos puntos finales son propiedad de este thread.

Los valores omitidos se conservan. Cuando relation_type cambia a un tipo de relación de memoria incorporada, su etiqueta inversa fija sustituye a opposite_relation_type.

Ejemplos

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

Actualizar de forma asíncrona una relación cuyos puntos finales pertenecen a este thread.

método wait_for_memory_extraction

Espere a una extracción de memoria en segundo plano anterior para este thread.

Este método espera a que se inicie la extracción en segundo plano mediante llamadas add_messages(), add_messages_async(), update_message() o update_message_async() anteriores en este thread a través del mismo componente de memoria de agente. Si una de esas llamadas ya está terminando, este método incluye la extracción que comienza antes de esperar.

El método no espera a que se inicie la extracción después de que comience esta espera, a que se inicie la extracción por un componente de memoria de agente diferente o a que se ejecute la extracción en otro proceso. Los fallos de extracción cuentan como finalizados para esta espera.

Ejemplos

thread.wait_for_memory_extraction(timeout=10)

method wait_for_memory_extraction_async (async)

Espere de forma asíncrona la extracción de memoria en segundo plano anterior.

Este método sigue el mismo comportamiento que wait_for_memory_extraction().

Ejemplos

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

Nota: delete_message() solo suprime la fila de mensaje raw. Los recuerdos derivados pueden seguir siendo buscables o aparecer en las tarjetas de contexto. Utilice OracleAgentMemory.delete_thread() para suprimir el thread junto con sus mensajes y memorias asociados. La supresión de mensajes y memoria a través de un identificador de thread espera a una extracción en segundo plano anterior ya aceptada por el cliente asociado para ese thread. Esta no es una barrera de simultaneidad global para otras instancias, procesos o trabajos de cliente aceptados después de que comience la espera.

Mensajes y contenido del mensaje

clase oracleagentmemory.apis.message.Message

Bases: object

Mensaje en memoria compartido por threads y adaptadores de LLM.

clase oracleagentmemory.apis.message.MessageContent

Bases: ABC

Clase base para contenido de mensaje estructurado.

clase oracleagentmemory.apis.message.TextContent

Bases: MessageContent

Parte de texto de un mensaje multimodal.

clase oracleagentmemory.apis.message.ImageContent

Bases: MessageContent

Parte de una imagen en un mensaje multimodal.

clase oracleagentmemory.apis.message.ImageMimeType

Bases: str, Enum

Tipos MIME soportados para el contenido de imagen.

No se admiten los formatos PNG y WebP animados.

JPEG = 'image/JPEG'

PNG = 'image/PNG'

WEBP = 'image/WEBP'

Tarjetas de contexto

clase oracleagentmemory.apis.contextcard.ContextCard

Bases: ABC

Objeto abstracto de tarjeta de contexto devuelto por las API de thread.

property content (resumen)

clase oracleagentmemory.core.contextcard.OracleContextCard

Bases: ContextCard

Tarjeta de contexto devuelta por un thread de Oracle.

propiedad content

Ejemplos

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

propiedad formatted_content

Ejemplos

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

Resúmenes

clase oracleagentmemory.apis.summary.Summary

Bases: ABC

Objeto abstracto de resumen de thread devuelto por las API de thread.

property content (resumen)

clase oracleagentmemory.core.summary.OracleSummary

Bases: Summary

Resumen devuelto por un thread de Oracle.

Ejemplos

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

propiedad content

Ejemplos

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

propiedad formatted_content

Ejemplos

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