Pesquisar

Esta página apresenta os ajudantes de escopo voltados para o desenvolvedor junto com o tipo de resultado concreto da pesquisa Oracle.

Resolução do Escopo

Para cada campo de escopo, você pode fazer uma das três coisas:

• omita-o para usar o padrão dessa camada de API. Em assinaturas Python e em SearchScope, esse estado omitido é representado por NOT_SET_MARKER.
• especificar uma identificação concreta para utilizar esse valor;
• especifique None para indicar que o registro não tem escopo nessa dimensão. Por exemplo, agent_id=None significa que o registro não está vinculado a um agente.

Cada registro armazenado tem três campos de escopo independentes: user_id, agent_id e thread_id. Cada campo pode conter um ID concreto ou None.

Exemplos de:

• thread_id=None significa que o registro não está vinculado a um thread.
• agent_id=None significa que o registro não está vinculado a um agente.
• user_id="u1", agent_id=None, thread_id=None significa que o registro tem como escopo o usuário u1, mas não qualquer agente ou thread específico.

As mesmas regras de escopo se aplicam a APIs de pesquisa síncronas e assíncronas.

Na tabela a seguir, ID significa qualquer user_id, agent_id ou thread_id junto com seu flag de correspondência exata correspondente.

Resolução do Escopo de Pesquisa por Camada de API

Caso	thread.search()	OracleAgentMemory.search()	store.search()
ID omitido	Usa os padrões de thread: user_id e agent_id exatos, mais o thread_id atual com exact_thread_match=False.	Usa os padrões do cliente. user_id Omitido foi rejeitado. Omitido agent_id e thread_id permanecem amplos.	Usa os padrões de armazenamento: ID=None e exact_*_match=False, para que a dimensão não seja filtrada.
Valor explícito, incluindo None + exact_*_match=False	Essa dimensão não é filtrada. Os registros cujo valor corresponde ao especificado podem ter uma classificação superior à de outros registros.	Para user_id, rejeitado porque as pesquisas do cliente exigem escopo de usuário exato explícito. Para agent_id e thread_id, essa dimensão não é filtrada. Os registros cujo valor corresponde ao especificado podem ter uma classificação superior à de outros registros.	Essa dimensão não é filtrada. Os registros cujo valor corresponde ao especificado podem ter uma classificação superior à de outros registros.
ID Explícito + exact_*_match=True	Corresponde exatamente a esse ID.	Corresponde exatamente a esse ID.	Corresponde exatamente a esse ID.
None Explícito + exact_*_match=True	Corresponde somente a registros sem escopo nessa dimensão.	Corresponde somente a registros sem escopo nessa dimensão.	Corresponde somente a registros sem escopo nessa dimensão.

Use None explícito junto com exact_*_match=True quando quiser apenas registros sem escopo nessa dimensão e a API permitir. Omita o campo quando desejar o padrão da operação.

Escopos

classe oracleagentmemory.apis.scope.Scope

Bases: object

Representa um escopo para inserção de informações ou pesquisas.

• Parâmetros:
  • id_usuário str | None
  • id_agente str | None
  • thread_id str | None

user_id

ID do usuário final. NOT_SET_MARKER significa que o campo foi omitido e deve ser resolvido pelo padrão específico da operação. O None explícito é preservado e interpretado pelas regras específicas da operação. APIs de cliente de nível superior, como OracleAgentMemory.search(), podem exigir que o escopo do usuário seja explícito. Nessas APIs, None só pode ser usado para direcionar registros sem escopo.

• Tipo: str | Nenhum

id_agente

ID do Agente. NOT_SET_MARKER significa que o campo foi omitido e deve ser resolvido pelo padrão específico da operação. O None explícito é preservado e interpretado pelas regras específicas da operação.

• Tipo: str | Nenhum

thread_id

ID de Thread. NOT_SET_MARKER significa que o campo foi omitido e deve ser resolvido pelo padrão específico da operação. O None explícito é preservado e interpretado pelas regras específicas da operação.

• Tipo: str | Nenhum

classe oracleagentmemory.apis.searchscope.SearchScope

Bases: Scope

Representa o escopo de uma consulta de pesquisa e, portanto, restringe o que pode ser retornado.

• Parâmetros:
  • id_usuário str | None
  • id_agente str | None
  • thread_id str | None
  • exact_user_match bool
  • exact_agent_match bool
  • exact_thread_match bool

user_id

ID do usuário final. Quando o valor exact_user_match resolvido é True, esse ID é correspondido exatamente, incluindo None. Quando é False, a dimensão do usuário é irrestrita. NOT_SET_MARKER é substituído por um padrão específico da operação. APIs de cliente de nível superior, como OracleAgentMemory.search(), podem exigir que o escopo do usuário seja explícito. Nessas APIs, None direciona somente registros sem escopo quando o exact_user_match é resolvido como True.

• Tipo: str | Nenhum

id_agente

ID do Agente. Quando o valor exact_agent_match resolvido é True, esse ID é correspondido exatamente, incluindo None. Quando é False, a dimensão do agente é irrestrita. NOT_SET_MARKER é substituído por um valor padrão, dependendo da operação que usa o escopo.

• Tipo: str | Nenhum

thread_id

ID de Thread. Quando o valor exact_thread_match resolvido é True, esse ID é correspondido exatamente, incluindo None. Quando é False, a dimensão de thread é irrestrita. NOT_SET_MARKER é substituído por um valor padrão, dependendo da operação que usa o escopo.

• Tipo: str | Nenhum

exact_user_match

Se deve corresponder exatamente ao user_id resolvido. True corresponde exatamente, incluindo None. False deixa a dimensão do usuário sem restrições. NOT_SET_MARKER é substituído por um padrão, dependendo da operação. APIs de cliente de nível superior, como OracleAgentMemory.search(), podem exigir que isso permaneça True.

• Tipo: bool

exact_agent_match

Se deve corresponder exatamente ao agent_id resolvido. True corresponde exatamente, incluindo None. False deixa a dimensão do agente sem restrições. NOT_SET_MARKER é substituído por um padrão, dependendo da operação.

• Tipo: bool

exact_thread_match

Se deve corresponder exatamente ao thread_id resolvido. True corresponde exatamente, incluindo None. False deixa a dimensão de thread sem restrições. NOT_SET_MARKER é substituído por um padrão, dependendo da operação.

• Tipo: bool

Resultados

classe oracleagentmemory.core.OracleSearchResult

Bases: SearchResult

Resultado da pesquisa retornado por um thread Oracle.

• Parâmetros:
  • distância float – Distância do vetor de consulta (menor é melhor).
  • record Record – Um objeto de registro que contém as informações de metadados sobre a entrada persistente.
  • id str | None – Identificador opcional associado ao registro armazenado.

propriedade content

• Tipo de Retorno: str
• Descrição: Retorna o conteúdo textual principal do registro correspondente.

propriedade formatted_content

• Tipo de Retorno: str

• Descrição: Retorna a renderização padrão XML-safe usada em prompts.

• Retorna: Renderização segura para XML que inclui os campos visíveis padrão para um resultado de pesquisa.
• Tipo de retorno: str

propriedade id

• Tipo de Retorno: str | Nenhum
• Descrição: Retorna o identificador estável do registro correspondente, quando disponível.

propriedade metadata

• Tipo de Retorno: dict[str, Any] | Nenhum
• Descrição: Retorne metadados de registro, se disponíveis.

propriedade record

• Tipo de Retorno: Registro
• Descrição: Retorna o registro correspondente.

O valor retornado pode ser uma subclasse Record simples ou ScopedRecord. Use isinstance(result.record, ScopedRecord) antes de ler identificadores de escopo público.

propriedade timestamp

• Tipo de Retorno: str | Nenhum
• Descrição: Retorna o timestamp do registro, se disponível.