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.

Parameter	Type	Default	Notes
`name`	`str`	required	Display name for the agent.
`datasets`	`Optional[list[str \| UUID]]`	`None`	Dataset names or UUIDs to grant the agent `read`/`write` on. The calling user must already have `read` access to each.
`user`	`Optional[User]`	`None`	Acting 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.

Parameter	Type	Default	Notes
`agent_session_name`	`str`	required	Name of the agent session/connection.
`type`	`AgentConnectionType`	`"api"`	One of `sdk`, `api`, `mcp`, `claude_code`, `opencode`, `workflow`, `unknown`.
`memory_mode`	`AgentMemoryMode`	`"unknown"`	One of `session`, `cognee`, `hybrid`, `none`, `unknown`.
`session_id`	`Optional[str]`	`None`	Optional session id to associate.
`dataset_ids`	`Optional[list[str]]`	`None`	Dataset UUIDs to associate; calling user must have `read` on each.
`dataset_names`	`Optional[list[str]]`	`None`	Dataset names to associate; calling user must have `read` on each.
`source`	`AgentSource`	`"api"`	One of `agent_memory`, `session_trace`, `serve`, `api_key`, `mcp`, `api`.
`origin_function`	`Optional[str]`	`None`	Optional originating function label.
`metadata`	`Optional[dict]`	`None`	Arbitrary metadata stored with the connection.
`user`	`Optional[User]`	`None`	Acting 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.

Parameter	Type	Default	Notes
`agent_id`	`Optional[str \| UUID]`	`None`	Filter to a single agent.
`range_key`	`RangeLiteral`	`"30d"`	Time window: one of `24h`, `7d`, `30d`, `all`.
`status_filter`	`Optional[str]`	`None`	Filter by connection status.
`include_sources`	`bool`	`True`	Include memory sources in the response.
`active_only`	`bool`	`True`	Return only active connections.
`limit`	`int`	`50`	Maximum number of connections to return.
`offset`	`int`	`0`	Result offset for pagination.
`user`	`Optional[User]`	`None`	Acting 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.

​cognee.agents

​Methods

​agents.create()

​agents.list()

​agents.get()

​agents.delete()

​agents.register()

​agents.unregister()

​agents.list_connections()

​agents.get_connection()

​CLI

cognee.agents

Methods

agents.create()

agents.list()

agents.get()

agents.delete()

agents.register()

agents.unregister()

agents.list_connections()

agents.get_connection()

CLI