agents

Agent management: create, list, inspect, and delete agents, and manage their connections

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.

Agents are one level deep: an agent cannot create agents of its own, so create agents with a top-level user’s credentials, not with an agent’s API key. If the acting user has a parent_user_id (an agent from agents.create(), a plugin-provisioned agent, or a user created with create_user(..., parent_user_id=...)), the call raises PermissionDeniedError (HTTP 403 on POST /api/v1/agents/create). Requested datasets are checked first, so a dataset error (such as ValueError for a name the caller does not own) can surface before this one.

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": "[e-mail]",
    "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, along with its API keys and any sub-agents it created before agents were limited to one level. 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; a dataset the caller cannot read raises PermissionDeniedError (HTTP 403). The check lives in the shared backend operation, so POST /api/v1/agents/register applies the same rule and answers 403.

Three details of that check are worth knowing:

• Names resolve only among the caller’s own datasets, as everywhere else in Cognee. A dataset that was shared with the caller does not resolve by name — pass it in dataset_ids instead, or registration fails with 403. A name that does not exist yet fails the same way.
• A dataset id that is not a valid UUID counts as not accessible and raises PermissionDeniedError, rather than a ValueError.
• Ids are stored in canonical UUID form on the connection’s dataset references, so an uppercase or hyphenless spelling still links to its memory source.

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.

A connection belongs to its user. A caller sees a connection only when its owning user is the acting user, or one of the agent users the acting user is the parent of — so a parent still sees its agents’ connections, and nothing else does:

• Sharing a dataset does not expose its connections. A connection that lists a dataset is not shown to the other readers of that dataset; dataset overlap grants no visibility.
• A connection with no owning user is visible to nobody.
• A persisted connection is trusted only inside its owner’s configuration. An entry stored under one user’s agent_configuration but naming a different user_id is skipped, and an entry that fails validation is skipped with a debug log instead of failing the request.

total, has_more, and the connected_agent_ids on each memory source are all built from the same filtered list, so they follow the same scope.

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. The detail is resolved from the same list agents.list_connections() returns, so it carries the same scope: a connection outside the acting user’s scope resolves to None (HTTP 404 on GET /api/v1/agents/connections/{agent_id}), and the recent sessions, Q&A, and traces hydrated from the session cache are never read for it.

When agent_session_name is given, the lookup also matches connections that agents.unregister() has deactivated; they come back with ["agent"]["status"] set to "inactive" instead of None. Without agent_session_name, only active connections are considered, as with the active_only=True default of list_connections().

CLI

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