Skip to main content

​
cognee.agents

Static class for managing agents and their connections. Each agent is backed by its own agent user with a one-time API key, and every operation is scoped to the acting user — permissions are enforced per acting user before any agent is created or any dataset is granted. 
import cognee

# Create an agent with read/write on a dataset
agent = await cognee.agents.create("my-agent", datasets=["my_project"])

# List your agents
all_agents = await cognee.agents.list()
Agent emails are displayed in their {slug}@cognee.agent form. Internally each agent user is minted with a unique {slug}+{parent_id}@cognee.agent address; the SDK strips the +{parent_id} segment before returning the email.

​
Methods

​
agents.create()

await cognee.agents.create(
    name: str,
    datasets: Optional[list[str | UUID]] = None,
    user: Optional[User] = None,
) -> dict
Create a new agent and, optionally, grant it read and write access to one or more datasets. Each requested dataset is resolved and the calling user’s read access to it is verified before the agent user is minted, so a failed authorization never leaves an orphaned agent user with a live API key.
ParameterTypeDefaultNotes
namestrrequiredDisplay name for the agent.
datasetsOptional[list[str | UUID]]NoneDataset names or UUIDs to grant the agent read/write on. The calling user must already have read access to each.
userOptional[User]NoneActing user. If omitted, Cognee resolves the default user.
Returns a dict with the agent id, display email, and the one-time API key: 
{
    "agent_id": "…",
    "agent_email": "my-agent@cognee.agent",
    "agent_api_key": "…",  # shown once — store it now
}
agent_api_key is returned only on creation and cannot be retrieved again. Store it at creation time.

​
agents.list()

await cognee.agents.list(user=None) -> list[dict]
List the agents owned by the resolved user. Each entry contains agent_id, agent_email, and api_key_label.

​
agents.get()

await cognee.agents.get(agent_id: str | UUID, user=None) -> dict
Return details (agent_id, agent_email, api_key_label) for a single agent. Raises ValueError if the agent does not exist, or PermissionDeniedError if the acting user is not authorized to view it.

​
agents.delete()

await cognee.agents.delete(agent_id: str | UUID, user=None) -> None
Delete an agent by id. Raises ValueError if the agent does not exist, or PermissionDeniedError if the acting user is not authorized to delete it.

​
agents.register()

await cognee.agents.register(
    agent_session_name: str,
    user: Optional[User] = None,
    type: AgentConnectionType = "api",
    memory_mode: AgentMemoryMode = "unknown",
    session_id: Optional[str] = None,
    dataset_ids: Optional[list[str]] = None,
    dataset_names: Optional[list[str]] = None,
    source: AgentSource = "api",
    origin_function: Optional[str] = None,
    metadata: Optional[dict] = None,
) -> dict
Register an agent connection (session). The acting user’s read access to every supplied dataset (by id and by name) is validated before the connection is created. Returns the connection as a JSON-serializable dict.
ParameterTypeDefaultNotes
agent_session_namestrrequiredName of the agent session/connection.
typeAgentConnectionType"api"One of sdk, api, mcp, claude_code, workflow, unknown.
memory_modeAgentMemoryMode"unknown"One of session, cognee, hybrid, none, unknown.
session_idOptional[str]NoneOptional session id to associate.
dataset_idsOptional[list[str]]NoneDataset UUIDs to associate; calling user must have read on each.
dataset_namesOptional[list[str]]NoneDataset names to associate; calling user must have read on each.
sourceAgentSource"api"One of agent_memory, session_trace, serve, api_key, mcp, api.
origin_functionOptional[str]NoneOptional originating function label.
metadataOptional[dict]NoneArbitrary metadata stored with the connection.
userOptional[User]NoneActing user. If omitted, Cognee resolves the default user.

​
agents.unregister()

await cognee.agents.unregister(agent_session_name: str, user=None) -> int
Unregister an agent connection by session name. Returns the number of remaining active connections.

​
agents.list_connections()

await cognee.agents.list_connections(
    user: Optional[User] = None,
    agent_id: Optional[str | UUID] = None,
    range_key: RangeLiteral = "30d",
    status_filter: Optional[str] = None,
    include_sources: bool = True,
    active_only: bool = True,
    limit: int = 50,
    offset: int = 0,
) -> dict
List active agent connections and their memory sources, scoped to the acting user. Connections that are bound neither to an owning user nor to any dataset are filtered out of the result so a caller never sees connections outside their own scope, and total/has_more are adjusted accordingly.
ParameterTypeDefaultNotes
agent_idOptional[str | UUID]NoneFilter to a single agent.
range_keyRangeLiteral"30d"Time window: one of 24h, 7d, 30d, all.
status_filterOptional[str]NoneFilter by connection status.
include_sourcesboolTrueInclude memory sources in the response.
active_onlyboolTrueReturn only active connections.
limitint50Maximum number of connections to return.
offsetint0Result offset for pagination.
userOptional[User]NoneActing user. If omitted, Cognee resolves the default user.

​
agents.get_connection()

await cognee.agents.get_connection(
    agent_id: str | UUID,
    user: Optional[User] = None,
    agent_session_name: Optional[str] = None,
) -> Optional[dict]
Return the detail for a single agent connection, or None if no matching connection is found.

​
CLI

The same operations are available from the command line via the cognee-cli agents command.