Add a GraphQL field to list external agent identities
What does this MR do and why?
The AI governance dashboard needs a "Connected agents" tab that lists each external agent connected through glab: one row per ai_agent_identities record. See https://gitlab.com/gitlab-org/gitlab/-/work_items/633495. This adds the backend for it, an aiAgentIdentities field on Group and Project.
Stacked on !261976 (merged), which adds last_synced_at. I'll retarget to master once that merges.
Each node has:
| Field | Notes |
|---|---|
agentType |
CLAUDE_CODE, OPENCODE, CURSOR or CODEX. There's no agent name column, so the frontend maps this to a display name. |
user, project |
Who connected it, and where |
createdAt |
First connected |
lastSyncedAt |
Last active. Null until the identity syncs after !261976 (merged) is deployed. |
revokedAt |
Set by glab govern disable |
status |
ACTIVE (synced in the last 30 days, or registered in the last 30 days and not synced yet), INACTIVE, or REVOKED |
sessionCount |
Batched, one query per page. Counts up to 1,000, plus one to show there are more, like Ci::Runner.jobCount. |
- On a group, it lists identities in the group's projects and its subgroups' projects. On a project, just that project.
- Filters:
agentTypes,userId,status. Sorted bylastSyncedAtdescending, nulls last, then ID. - Same access as
aiGovernanceSessions: the parent field requiresread_agent_artifacts, and it returns nothing whenai_governance_sessions_apiis disabled. Granular tokens are checked on the parent too, so a token withread_grouporread_projecton it can read this, the same asaiGovernanceSessionstoday. - Revoked identities are listed with status
REVOKEDrather than hidden, so the dashboard can show them as disconnected. The frontend can filter them out.
Database
The group query scopes identities to the group's projects and sorts by last_synced_at DESC NULLS LAST, id DESC. There's no index for that order, so it's a top-N sort over the group's identities. The table has one row per user, project, agent type and machine, so I didn't add one. Local plan (tiny data, so it mainly shows the access path):
Limit
-> Sort
Sort Key: ai_agent_identities.last_synced_at DESC NULLS LAST, ai_agent_identities.id DESC
-> Nested Loop
-> HashAggregate
Group Key: projects.id
-> Nested Loop
-> Index Scan using index_namespaces_on_traversal_ids_for_groups_btree on namespaces
-> Index Only Scan using index_projects_on_namespace_id_and_id on projects
-> Index Scan using idx_ai_agent_identities_on_project_id on ai_agent_identities
Filter: ((revoked_at IS NULL) AND (COALESCE(last_synced_at, created_at) >= ...))Group query, with the status: ACTIVE and agentTypes filters, first page:
SELECT "ai_agent_identities".* FROM "ai_agent_identities"
WHERE "ai_agent_identities"."project_id" IN (
SELECT "projects"."id" FROM "projects" WHERE "projects"."namespace_id" IN (
SELECT "namespaces"."id" FROM "namespaces"
WHERE "namespaces"."type" = 'Group' AND (traversal_ids @> ('{22}'))))
AND "ai_agent_identities"."agent_type" = 'claude-code'
AND "ai_agent_identities"."revoked_at" IS NULL
AND COALESCE("ai_agent_identities"."last_synced_at", "ai_agent_identities"."created_at") >= '2026-09-23 01:28:57.231940'
ORDER BY "ai_agent_identities"."last_synced_at" DESC NULLS LAST, "ai_agent_identities"."id" DESC
LIMIT 101Project query, first page:
SELECT "ai_agent_identities".* FROM "ai_agent_identities"
WHERE "ai_agent_identities"."project_id" = 1
ORDER BY "ai_agent_identities"."last_synced_at" DESC NULLS LAST, "ai_agent_identities"."id" DESC
LIMIT 101Limit
-> Sort
Sort Key: last_synced_at DESC NULLS LAST, id DESC
-> Index Scan using idx_ai_agent_identities_on_project_id on ai_agent_identities
Index Cond: (project_id = 1)sessionCount, once for each page:
SELECT "ai_agent_identities"."id", COUNT(*) FROM "ai_agent_identities"
JOIN LATERAL (
SELECT 1 FROM "ai_governance_sessions"
WHERE "ai_governance_sessions"."agent_identity_id" = "ai_agent_identities"."id"
LIMIT 1001
) limited_sessions ON true
WHERE "ai_agent_identities"."id" IN (1, 2, 3)
GROUP BY "ai_agent_identities"."id"GroupAggregate (cost=0.28..10.73 rows=3 width=16) (actual time=0.024..0.025 rows=0 loops=1)
Group Key: ai_agent_identities.id
-> Nested Loop (cost=0.28..10.69 rows=3 width=8)
-> Index Only Scan using ai_agent_identities_pkey on ai_agent_identities
Index Cond: (id = ANY ('{1,2,3}'::bigint[]))
-> Limit (cost=0.12..2.14 rows=1 width=4)
-> Index Only Scan using index_ai_governance_sessions_on_agent_identity_id on ai_governance_sessions
Index Cond: (agent_identity_id = ai_agent_identities.id)sessionCount uses the existing partial index on ai_governance_sessions.agent_identity_id and reads at most 1,001 index entries for each identity on the page. It counts PostgreSQL rows, while aiGovernanceSessions reads ClickHouse, so the two can differ briefly while Siphon catches up.
References
https://gitlab.com/gitlab-org/gitlab/-/work_items/633495
How to set up and validate locally
query {
group(fullPath: "my-group") {
aiAgentIdentities(status: ACTIVE) {
nodes { agentType user { username } project { fullPath } createdAt lastSyncedAt status sessionCount }
}
}
}bundle exec rspec ee/spec/requests/api/graphql/ai/external_agents/agent_identities_spec.rb ee/spec/finders/ai/external_agents/agent_identities_finder_spec.rb ee/spec/models/ai/external_agents/agent_identity_spec.rbMR acceptance checklist
Evaluate this MR against the MR acceptance checklist.