Skip to content

agent

Agent service module

Attributes

MemoryOrderByType module-attribute 

MemoryOrderByType = Literal[
    "ACCESSED", "CREATED", "UPDATED"
]

S module-attribute 

S = TypeVar('S')

Classes

AgentService 

AgentService(
    sa_session: SASession, neo4j_session: NJSession
)

Bases: BaseService

Agent service layer

Attributes

activity_session_dao instance-attribute 
activity_session_dao = ActivitySessionDao(
    session=sa_session
)
activity_session_participant_dao instance-attribute 
activity_session_participant_dao = (
    ActivitySessionParticipantDao(session=sa_session)
)
agent_dao instance-attribute 
agent_dao = AgentDao(session=sa_session)
agent_memory_collection_dao instance-attribute 
agent_memory_collection_dao = AgentMemoryCollectionDao(
    session=sa_session
)
memory_collection_dao instance-attribute 
memory_collection_dao = MemoryCollectionDao(
    session=sa_session
)
memory_collection_service instance-attribute 
memory_collection_service = MemoryCollectionService(
    sa_session=sa_session, neo4j_session=neo4j_session
)
memory_dao instance-attribute 
memory_dao = MemoryDao(session=sa_session)
memory_graph_dao instance-attribute 
memory_graph_dao = MemoryGraphDao(session=sa_session)
memory_service instance-attribute 
memory_service = MemoryService(
    sa_session=sa_session, neo4j_session=neo4j_session
)
namespace_service instance-attribute 
namespace_service = NamespaceService(
    sa_session=sa_session, neo4j_session=neo4j_session
)
participant_dao instance-attribute 
participant_dao = ParticipantDao(session=sa_session)

Functions

bind_memory_collection 
bind_memory_collection(
    namespace: str,
    agent: str,
    memory_collection: str,
    db_transact: bool = True,
) -> None

Binds a memory collection to an agent.

Parameters:

  • agent_pkid (str) –

    The primary key of the agent.

  • memory_collection_pkid (str) –

    The primary key of the memory collection

  • db_transact (bool, default: True ) –

    Whether to commit/rollback the transaction. Defaults to True.

Raises:

  • ServiceError –

    If an error occurs while binding the memory collection.

create_agent 
create_agent(
    *,
    namespace: str,
    name: str,
    enabled: bool = True,
    description: str | None = None,
    settings: AgentResourceSettings | None = None,
    managed: bool = False,
    episodic_memory_collection_config: str | None = None,
    episodic_read_only=False,
    create_vectordb: bool = True,
    db_transact: bool = True
) -> Agent

Creates a new agent in the specified namespace.

Parameters:

  • namespace_pkid (str) –

    The primary key ID of the namespace.

  • name (str) –

    The name of the agent.

  • enabled (bool, default: True ) –

    Whether the agent is enabled. Defaults to True.

  • description (str, default: None ) –

    The description of the agent. Defaults to None.

  • create_episodic_memory_collection (bool) –

    Whether to create an episodic memory collection for the agent. Defaults to True.

  • settings (AgentResourceSettings, default: None ) –

    The resource settings for the agent. Defaults to None.

  • managed (bool, default: False ) –

    Flag indicating whether the agent is managed. Defaults to False.

  • vectordb_name (str) –

    The name of the VectorDB instance to use. Defaults to None.

  • episodic_memory_collection_config (str, default: None ) –

    The configuration for the episodic memory collection. Defaults to None.

  • episodic_read_only (bool, default: False ) –

    Flag indicating whether the episodic memory collection is read-only. Defaults to False.

  • db_transact (bool, default: True ) –

    Flag indicating whether to commit the transaction. Defaults to True.

Returns:

  • Agent –

    orm.Agent: The newly created agent.

Raises:

  • ServiceError –

    If an error occurs while creating the agent.

get_agent 
get_agent(
    *,
    namespace: str,
    agent: str,
    error_deleted: bool = True,
    error_disabled: bool = True
) -> Agent

Retrieve an agent by its primary key.

Parameters:

  • agent_pkid (str) –

    The primary key of the agent.

Returns:

  • Agent –

    orm.Agent: The agent object.

get_memories 
get_memories(
    namespace: str,
    agent: str,
    accessed_after: Optional[datetime] = None,
    type_filter: Optional[MemoryType] = None,
    memory_collection_filter: Optional[List[str]] = None,
    order_by: MemoryOrderByType = "ACCESSED",
    ordering: OrderByType = "DESC",
    limit: int = 100,
    touch: bool = False,
    db_transact: bool = True,
) -> List[Memory]

Retrieves a list of recent memories based on the provided parameters.

Derive a list of memory_collection_pkids based on the agent’s memory collections and the provided. If memory_collection_pkids is None then assume we will use all memory collections

Parameters:

  • agent_pkid (str) –

    The primary key of the agent.

  • accessed_after (Optional[datetime], default: None ) –

    Only retrieve memories accessed after this datetime. Defaults to None.

  • type_filter (Optional[MemoryType], default: None ) –

    Only retrieve memories of the specified type. Defaults to None.

  • limit (int, default: 100 ) –

    The maximum number of memories to retrieve. Defaults to 100.

  • memory_collection_filter (Optional[List[str]], default: None ) –

    Only retrieve memories from the specified memory collections. Defaults to None.

Returns:

  • List[Memory] –

    List[orm.Memory]: A list of recent memories.

hard_delete_agent 
hard_delete_agent(
    namespace: str,
    agent: str,
    delete_vectors: bool = True,
    dry_run: bool = True,
    db_transact: bool = True,
    raise_on_missing: bool = True,
) -> None

Hard delete an agent and all associated resources.

This method is designed to be robust and designed to clean up all associated records and resources for a given agent. To this end automated cascading deleted have been avoided to ensure the hard deletion works properly even with orphaned records should they occur.

Agent records will be deleted regardless of state; enablement or soft delete status will be ignored.

By default, dry_run is set to True, which will prevent the deletion of any records by rolling back at the end of the transaction.

Danger

This method is destructive and will permanently delete all data, memories, and resources associated with the specified agent.

Warning

Since memory records are deleted from the RDBMS, it is possible that non-episodic memory collections (ex from the Corpus Reader agent) may appear to be empty. It is recommended that memory collection maintenance is executed periodically to clean up the VectorDB since records may still exist there.

Parameters:

  • agent_pkid (str) –

    The primary key of the agent to be deleted.

  • delete_vectors (bool, default: True ) –

    Whether to delete the agent’s episodic memory collection in the vector database. Defaults to True.

  • dry_run (bool, default: True ) –

    Whether to perform a dry run. Defaults to True.

  • db_transact (bool, default: True ) –

    Whether to commit/rollback the transaction. Defaults to True.

  • raise_on_missing (bool, default: True ) –

    Whether to raise an exception if the agent is not found.

Raises:

  • ServiceError –

    If the agent with the specified PKID is not found.

Returns:

  • None –

    None

soft_delete_agent 
soft_delete_agent(
    namespace: str, agent: str, db_transact: bool = True
) -> None

Soft deletes the agents with the specified primary key IDs.

Parameters:

  • agent_pkids (Union[str, List[str]]) –

    The primary key ID(s) of the agent(s) to be deleted.

  • db_transact (bool, default: True ) –

    Whether to commit/rollback the transaction. Defaults to True.

Raises:

  • ServiceError –

    If the agent with the specified primary key ID is already deleted.

Returns:

  • None –

    None

unbind_memory_collection 
unbind_memory_collection(
    namespace: str,
    agent: str,
    memory_collection: str,
    db_transact: bool = True,
) -> None

Unbinds a memory collection from an agent.

Parameters:

  • agent_pkid (str) –

    The primary key of the agent.

  • memory_collection_pkid (str) –

    The primary key of the memory collection

  • db_transact (bool, default: True ) –

    Whether to commit/rollback the transaction. Defaults to True.

Raises:

  • ServiceError –

    If an error occurs while unbinding the memory collection

undelete_agent 
undelete_agent(
    namespace: str, agent: str, db_transact: bool = True
) -> None

Undelete the agents with the specified primary key IDs.

Parameters:

  • agent_pkids (Union[str, List[str]]) –

    The primary key ID(s) of the agent(s) to be undeleted.

  • db_transact (bool, default: True ) –

    Whether to commit/rollback the transaction. Defaults to True.

Raises:

  • ServiceError –

    If the agent with the specified primary key ID is not deleted.

Returns:

  • None –

    None

update_agent 
update_agent(
    namespace: str,
    agent: str,
    name: Optional[str] = None,
    description: Optional[str] = None,
    dynamic_persona: Optional[str] = None,
    settings: Optional[AgentResourceSettings] = None,
    managed: Optional[bool] = None,
    enabled: Optional[bool] = None,
    db_transact: bool = True,
) -> Agent

Update an agent with the specified attributes.

Parameters:

  • agent_pkid (str) –

    The primary key of the agent to be updated.

  • name (str, default: None ) –

    The new name of the agent. Defaults to None.

  • description (str, default: None ) –

    The new description of the agent. Defaults to None.

  • enabled (bool, default: None ) –

    The new enabled status of the agent. Defaults to None.

  • settings (AgentResourceSettings, default: None ) –

    The new resource settings of the agent. Defaults to None.

  • managed (bool, default: None ) –

    The new managed status of the agent. Defaults to None.

  • db_transact (bool, default: True ) –

    Whether to commit/rollback the transaction. Defaults to True.

Returns:

  • Agent –

    orm.Agent: The updated agent object.

update_agent_dynamic_persona 
update_agent_dynamic_persona(
    namespace: str,
    agent: str,
    dynamic_persona: str,
    db_transact: bool = True,
) -> Agent

Update the dynamic persona of an agent.

Parameters:

  • agent_pkid (str) –

    The primary key of the agent to be updated.

  • dynamic_persona (str) –

    The new dynamic persona of the agent.

  • db_transact (bool, default: True ) –

    Whether to commit/rollback the transaction. Defaults to True.

Returns:

  • Agent –

    orm.Agent: The updated agent object.

Functions