Managing Connections

View connected agents, manage datasets, and share data across your workspace

To connect an agent to your workspace, open the Integrations page under CONNECT in the sidebar (route /integrations). It walks you through the connect flow for each supported framework. See Integrations for the available options and Sessions to review agent activity.

This page covers the connection concepts that apply once an agent is connected: its identity, status, and how to share datasets with it.

Connected agents

Each agent user connected to your tenant has:

• Agent type — The framework or integration name (e.g., LangGraph, CrewAI).
• Status — LIVE, INACTIVE, or NEVER_CONNECTED. Status is computed from the agent’s most recent activity, not from the presence of an API key.
  • LIVE — the agent has produced activity (data added, data accessed, or a search query) within the last 30 minutes.
  • INACTIVE — the agent has activity on record, but the most recent event is older than 30 minutes.
  • NEVER_CONNECTED — the agent user exists (and may even have an API key) but has no recorded activity yet.
• Datasets — Number of datasets the agent has access to.
• Last active — Timestamp of the agent’s most recent activity, derived from the latest data ingestion, data access, or search query. Empty for agents in NEVER_CONNECTED state.

Connection identity

Each connection is identified by an agent_session_name chosen by the agent. The server combines that name with the authenticated user’s ID to derive the underlying connection ID, so the same agent_session_name always resolves to the same connection for a given user. The connection API response includes this agent_session_name so clients can match rows and details back to the session name they registered.

To inspect connections for the currently authenticated user without knowing the agent ID, call GET /agents/connections/me (optionally filtered by ?agent_session_name=<name>). See the Cloud SDK reference for request/response examples.

Per-plugin agent identities

Instead of sharing one tenant API key across every plugin, a supported plugin can be provisioned its own agent sub-user and its own labeled API key. Each plugin then shows up as a distinct connection, and its keys can be rotated or revoked without touching the others.

These plugin keys are accepted; any other value returns 404:

Plugin key	Label
claude-code	Claude Code
codex	Codex
opencode	OpenCode
openclaw	Openclaw
mcp	MCP
api	API/SDK

Provision an identity

curl -X POST https://your-tenant.aws.cognee.ai/api/v1/integrations/plugins/claude-code/provision \
  -H "X-Api-Key: <your-user-api-key>"

{
  "pluginKey": "claude-code",
  "agentId": "0f1c2d3e-4a5b-6c7d-8e9f-0a1b2c3d4e5f",
  "apiKey": "<the-plugin-api-key>",
  "created": true
}

The call is authenticated and idempotent as a get-or-create:

• The first call creates the agent sub-user for this user and plugin and returns created: true.
• Every later call returns the same agentId with created: false and a rotated key — minting a new key revokes all of the plugin agent’s previous keys. Re-provisioning is the rotation flow.
• apiKey is returned once and cannot be retrieved again. Store it before you close the response.
• An unknown plugin key returns 404. A 409 means an agent for that plugin already exists but could not be resolved as one of your agents.

Provisioning also registers the plugin in the agent-connection registry, under the parent account’s tenant, with the connection name plugin:<plugin_key> and a connection type of claude_code, opencode, mcp, or api (other plugin keys register as a generic sdk connection). Because registration happens at provision time rather than on first traffic, the plugin appears in the connections list immediately, in NEVER_CONNECTED state until it produces its first activity.

GET /api/v1/integrations/status returns the current state of every known plugin (key, connected, agentId, provisionedAt, lastActiveAt, sessionCount, source) alongside OAuth integration status.

Disconnect a plugin

curl -X DELETE https://your-tenant.aws.cognee.ai/api/v1/integrations/plugins/claude-code \
  -H "X-Api-Key: <your-user-api-key>"

{ "disconnected": true }

This revokes every API key held by the plugin agent and deactivates its connection. The agent user and everything it wrote are kept — disconnecting is not deleting. The response is {"disconnected": false} when the plugin was never provisioned.

Re-provisioning later revives the same identity with a fresh key. To remove the agent entirely, use DELETE /api/v1/agents/{agent_id}.

Share a dataset with an agent

You can give a connected agent read access to a dataset you own. This grants access via the dataset permissions endpoint, after which the dataset appears in the agent’s dataset list.

To connect a new agent, open the Integrations page under CONNECT.