DRIVERS-3529 Add env.agent to handshake metadata for agentic client identification by aclark4life · Pull Request #1967 · mongodb/specifications

aclark4life · 2026-07-22T18:55:09Z

Summary

Adds client.env.agent to the MongoDB Handshake metadata, so agent-mediated usage of MongoDB (Claude Code, Cursor, Gemini CLI, …) can be distinguished from direct human usage. See DRIVERS-3529.

Detection matches what mongosh already ships, except for AI_AGENT normalization. mongosh alignment: MONGOSH-3696.

Changes

Add env.agent to the client document, with an ordered environment-variable table for detection.
Evaluate the generic AI_AGENT last, so a versioned value such as claude-code_2-1-238_agent cannot mask a known agent. Normalize it: trim, lowercase, truncate to the largest valid UTF-8 prefix of 64 bytes, and map 1/true to ai_agent.
Omit env.agent before env.name in the size-limit cascade.
Append Test 3 to the Client Metadata prose tests, leaving Test 1 and Test 2 numbering unchanged.
Record the three AI_AGENT normalization divergences from mongosh, tracked by MONGOSH-3696.

Notes

v1 targets Node and Python. Other language tickets are split from DRIVERS-3529 and blocked on this spec change. Implementations: PYTHON-5929, NODE-7666.

Please complete the following before merging:

Is the relevant DRIVERS ticket in the PR title?
Update changelog.
Test changes in at least one language driver.
Test these changes against all server versions and topologies (including standalone, replica set, and sharded clusters).

codeowners-service-app · 2026-08-04T02:28:24Z

Assigned blink1073 for team dbx-spec-maintainers-connection-establishment because vbabanin is out of office.

blink1073 · 2026-08-04T10:32:46Z

    | `KUBERNETES_SERVICE_HOST`         | `1`                |

-### Test 2: Test that the driver accepts an arbitrary auth mechanism
+### Test 2: Test that agent metadata is properly captured


I think this should be added as Test 3, to prevent drivers from having to change existing test code

Fixed in 196c6b05.

blink1073 · 2026-08-04T10:36:29Z


+##### Agent
+
+Many AI coding assistants and agentic clients ("agents", e.g. Claude Code, Cursor, Gemini CLI) set an environment


The word wrapping here feels unnatural. I suggest either a soft-fixed length or sentence per line

Fixed in 196c6b05.

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (1)

source/mongodb-handshake/tests/README.md:135

This table is intended to represent “no environment variables set”, but an all-empty row renders oddly and can be confusing (or trigger table-formatting checks). Consider replacing the table with a short sentence stating that no variables are set.

    | Environment Variable | Value |
    | -------------------- | ----- |
    |                      |       |

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (1)

source/mongodb-handshake/tests/README.md:88

Subject–verb agreement: “a connection and hello command succeeds” should be plural (“…command succeed”).

Drivers that capture values for `client.env` should test that a connection and hello command succeeds in the presence of

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (1)

source/mongodb-handshake/tests/README.md:129

In Test 3 case 6, the table shows the AI_AGENT value as "" (two quote characters), which is not an empty string. This could cause implementers to set the variable to a non-empty value and accidentally treat it as populated, defeating the intent of the test case (empty value treated as unset). Consider leaving the table value cell blank (or otherwise unambiguously indicating an empty value) while keeping the bullet text as the normative requirement.

    | Environment Variable | Value               |
    | -------------------- | ------------------- |
    | `AI_AGENT`           | `""` (empty string) |

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated no new comments.

Suppressed comments (1)

source/mongodb-handshake/tests/README.md:143

The new Agent prose test cases cover generic-vs-known precedence, but they don’t include a case asserting the precedence between the two generic variables themselves (AI_AGENT must win over AGENT, since it is earlier in the ordered table in the spec). Without this, a driver could accidentally flip the generic precedence and still pass these tests.

7. No agent variables. None of the environment variables in the `client.env.agent` table are set. `client.env.agent`
    MUST be omitted.

8. Agent alongside FaaS. This test MUST verify that both the AWS Lambda metadata and `client.env.agent` (equal to
    `claude-code`) are present in `client.env`.

    | Environment Variable | Value              |
    | -------------------- | ------------------ |
    | `AWS_EXECUTION_ENV`  | `AWS_Lambda_java8` |
    | `AWS_REGION`         | `us-east-2`        |
    | `CLAUDECODE`         | `1`                |

…dentification

…low Agent prose

…tion Address review feedback from PavelSafronov and johnmtll: - Evaluate known agent variables before the generic AI_AGENT, so a versioned AI_AGENT value cannot mask a known agent. - Adopt the environment variables and snake_case agent names that mongosh already uses, so drivers and the shell agree. - Drop the generic AGENT variable, which is common outside agents. - Specify normalization: trim, lowercase, map 1/true to ai_agent, and truncate to 64 characters. - Treat a whitespace-only value as unset. - Omit env.agent before env.name in the size-limit cascade.

Entries 1 through 11 report a fixed name from the table, but a value derived from AI_AGENT is reported by the agent itself. Say so, so that the two value spaces of client.env.agent are distinguishable.

Truncate to the largest valid UTF-8 prefix of 64 bytes, never splitting a character or substituting U+FFFD. State why the cap exists. Scope the mongosh parity claim to the variable list and names, and record the three normalization divergences. Add prose tests for a boolean value with whitespace and for truncation on a character boundary.

PavelSafronov · 2026-09-23T17:13:42Z

-3. Omit the `env` document entirely.
-4. Truncate `platform`.
+1. Omit fields from `env` except `env.name` and `env.agent`.
+2. Omit `env.agent`.


On an agent-only host (no FaaS, no container), steps 1+2 result in an empty env, and if this now fits, env: {} gets sent, which contradicts line 295

If no fields of client.env would be populated, client.env MUST be entirely omitted.

Suggest step 2 be changed to:

2. Omit `env.agent`; if `env` then has no remaining fields, omit `env` entirely.”

Fixed in 8958aa12.

aclark4life force-pushed the DRIVERS-3529 branch from f32a3df to 8c1e1f0 Compare July 22, 2026 18:58

aclark4life marked this pull request as ready for review July 22, 2026 19:05

aclark4life requested a review from a team as a code owner July 22, 2026 19:05

aclark4life requested a review from vbabanin July 22, 2026 19:05

codeowners-service-app Bot requested a review from blink1073 August 4, 2026 02:28

blink1073 requested changes Aug 4, 2026

View reviewed changes

aclark4life requested a review from Copilot August 4, 2026 20:38

Copilot started reviewing on behalf of aclark4life August 4, 2026 20:38 View session

This comment was marked as outdated.

Sign in to view

aclark4life requested a review from Copilot August 4, 2026 20:45

Copilot started reviewing on behalf of aclark4life August 4, 2026 20:45 View session

Copilot AI reviewed Aug 4, 2026

View reviewed changes

aclark4life requested a review from Copilot August 4, 2026 20:52

Copilot started reviewing on behalf of aclark4life August 4, 2026 20:53 View session

Copilot AI reviewed Aug 4, 2026

View reviewed changes

aclark4life requested a review from Copilot August 4, 2026 21:04

Copilot started reviewing on behalf of aclark4life August 4, 2026 21:05 View session

Copilot AI reviewed Aug 4, 2026

View reviewed changes

aclark4life requested review from blink1073 and Copilot August 4, 2026 21:10

Copilot started reviewing on behalf of aclark4life August 4, 2026 21:11 View session

Copilot AI reviewed Aug 4, 2026

View reviewed changes

johnmtll mentioned this pull request Sep 14, 2026

(WIP) NODE-7666(feat): environment variables in the handshake metadata mongodb/node-mongodb-native#5052

Draft

5 tasks

PavelSafronov reviewed Sep 15, 2026

View reviewed changes

Comment thread source/mongodb-handshake/handshake.md Outdated

Comment thread source/mongodb-handshake/handshake.md Outdated

johnmtll requested changes Sep 15, 2026

View reviewed changes

Comment thread source/mongodb-handshake/handshake.md Outdated

aclark4life and others added 4 commits September 22, 2026 12:21

DRIVERS-3529 Add env.agent to handshake metadata for agentic client i…

c3b4231

…dentification

DRIVERS-3529 Address review: renumber agent prose test to Test 3, ref…

196c6b0

…low Agent prose

DRIVERS-3529 Use "" for empty string in agent prose test table

4b45cd7

DRIVERS-3529 Replace empty table with prose in "no agent variables" test

1a3ee09

aclark4life added 2 commits September 22, 2026 12:21

DRIVERS-3529 Fix subject-verb agreement in handshake prose test intros

5220511

aclark4life force-pushed the DRIVERS-3529 branch from feaec8d to d5adec0 Compare September 22, 2026 16:22

DRIVERS-3529 Note that AI_AGENT values are not generically queryable

68c7c04

Entries 1 through 11 report a fixed name from the table, but a value derived from AI_AGENT is reported by the agent itself. Say so, so that the two value spaces of client.env.agent are distinguishable.

aclark4life requested review from PavelSafronov and johnmtll September 22, 2026 17:09

PavelSafronov reviewed Sep 22, 2026

View reviewed changes

Comment thread source/mongodb-handshake/handshake.md Outdated

Comment thread source/mongodb-handshake/tests/README.md Outdated

Comment thread source/mongodb-handshake/handshake.md Outdated

johnmtll reviewed Sep 23, 2026

View reviewed changes

Comment thread source/mongodb-handshake/handshake.md Outdated

aclark4life added 3 commits September 23, 2026 12:29

DRIVERS-3529 Link MONGOSH-3696 for the AI_AGENT normalization divergence

fbfdc63

DRIVERS-3529 Say MONGOSH-3696 proposes mongosh alignment

0cec457

aclark4life requested review from PavelSafronov and johnmtll September 23, 2026 16:52

PavelSafronov requested changes Sep 23, 2026

View reviewed changes

DRIVERS-3529 Omit empty env after omitting env.agent

8958aa1

aclark4life requested a review from PavelSafronov September 23, 2026 19:39


		##### Agent

		Many AI coding assistants and agentic clients ("agents", e.g. Claude Code, Cursor, Gemini CLI) set an environment

Conversation

aclark4life commented Jul 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Changes

Notes

Uh oh!

codeowners-service-app Bot commented Aug 4, 2026

Uh oh!

blink1073 Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

aclark4life Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

blink1073 Aug 4, 2026

Choose a reason for hiding this comment

Uh oh!

aclark4life Sep 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as outdated.

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

PavelSafronov Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

aclark4life Sep 23, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

aclark4life commented Jul 22, 2026 •

edited

Loading

aclark4life Sep 22, 2026 •

edited

Loading

aclark4life Sep 22, 2026 •

edited

Loading