> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognee.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```python theme={null}
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()
```

<Note>
  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.
</Note>

## Methods

### agents.create()

```python theme={null}
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:

```python theme={null}
{
    "agent_id": "…",
    "agent_email": "my-agent@cognee.agent",
    "agent_api_key": "…",  # shown once — store it now
}
```

<Warning>
  `agent_api_key` is returned only on creation and cannot be retrieved again. Store
  it at creation time.
</Warning>

### agents.list()

```python theme={null}
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()

```python theme={null}
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()

```python theme={null}
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()

```python theme={null}
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`, `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()

```python theme={null}
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()

```python theme={null}
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()

```python theme={null}
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`](/cognee-cli/overview#manage-agents) command.