From 8c1e1f0ca2e23c1165695010044e568b926872a0 Mon Sep 17 00:00:00 2001 From: Jeffrey 'Alex' Clark Date: Wed, 22 Jul 2026 14:54:40 -0400 Subject: [PATCH 1/5] DRIVERS-3529 Add env.agent to handshake metadata for agentic client identification --- source/mongodb-handshake/handshake.md | 38 +++++++++++++-- source/mongodb-handshake/tests/README.md | 62 +++++++++++++++++++++++- 2 files changed, 96 insertions(+), 4 deletions(-) diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md index 07c326b5d4..efe71978e8 100644 --- a/source/mongodb-handshake/handshake.md +++ b/source/mongodb-handshake/handshake.md @@ -148,6 +148,7 @@ the following structure: timeout_sec: 42, /* OPTIONAL */ memory_mb: 1024, /* OPTIONAL */ region: "", /* OPTIONAL */ + agent: "", /* OPTIONAL */ /* OPTIONAL */ container: { runtime: "", /* OPTIONAL */ @@ -291,8 +292,8 @@ Example: This value is optional and is not application configurable. -Information about the execution environment, including Function-as-a-Service (FaaS) identification and container -runtime. +Information about the execution environment, including Function-as-a-Service (FaaS) identification, container runtime, +and agentic client (agent) identification. The contents of `client.env` MUST be adjusted to keep the handshake below the size limit; see [Limitations](#limitations) for specifics. @@ -329,6 +330,36 @@ Depending on which `client.env.name` has been selected, other FaaS fields in `cl Missing variables or variables with values not matching the expected type MUST cause the corresponding `client.env` field to be omitted and MUST NOT cause a user-visible error. +##### Agent + +Many AI coding assistants and agentic clients ("agents", e.g. Claude Code, Cursor, Gemini CLI) set an environment +variable in the process environment when they execute shell commands or code on a user's behalf. `client.env.agent` +captures which agent, if any, is driving the client, so that agent-mediated usage of MongoDB can be distinguished from +direct human usage. + +`client.env.agent` is a single string, determined by which of the following environment variables are populated. The +list MUST be evaluated in order, and the first match determines the value; subsequent entries MUST NOT be considered: + +| Order | Environment Variable | `client.env.agent` value | +| ----- | -------------------- | ------------------------ | +| 1 | `AI_AGENT` | The value of `AI_AGENT` | +| 2 | `AGENT` | The value of `AGENT` | +| 3 | `CLAUDECODE` | `claude-code` | +| 4 | `CURSOR_AGENT` | `cursor` | +| 5 | `GEMINI_CLI` | `gemini-cli` | +| 6 | `CODEX_SANDBOX` | `codex` | +| 7 | `AUGMENT_AGENT` | `augment` | +| 8 | `OPENCODE_CLIENT` | `opencode` | + +For entries 1 and 2 (`AI_AGENT` and `AGENT`), the value of `client.env.agent` is the value of the environment variable. +For entries 3 through 8, the value of `client.env.agent` is the fixed string in the table above, regardless of the value +of the environment variable. + +An environment variable is considered populated if it is present in the environment with a non-empty value. If none of +the above environment variables are populated, `client.env.agent` MUST be entirely omitted. + +Determination of `client.env.agent` MUST NOT cause a user-visible error. + ##### Container Container runtime information is captured in `client.env.container`. @@ -475,7 +506,7 @@ which will result in handshake failure. Drivers MUST validate these values and t if necessary. Implementers SHOULD cumulatively update fields in the following order until the document is under the size limit: -1. Omit fields from `env` except `env.name`. +1. Omit fields from `env` except `env.name` and `env.agent`. 2. Omit fields from `os` except `os.type`. 3. Omit the `env` document entirely. 4. Truncate `platform`. @@ -565,6 +596,7 @@ support the `hello` command, the `helloOk: true` argument is ignored and the leg ## Changelog +- 2026-07-22: Add `env.agent` to `client` document for agentic client identification. - 2026-06-25: Clarify the client backpressure component of the handshake. - 2026-06-11: Clarify that there is no new behavior as a result of only using OP_MSG for all handshakes. - 2026-06-05: Use OP_MSG for all handshakes. diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md index ed56e5dc46..c3ad897266 100644 --- a/source/mongodb-handshake/tests/README.md +++ b/source/mongodb-handshake/tests/README.md @@ -74,7 +74,67 @@ the following sets of environment variables: | `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` | `1024` | | `KUBERNETES_SERVICE_HOST` | `1` | -### Test 2: Test that the driver accepts an arbitrary auth mechanism +### Test 2: Test that agent metadata is properly captured + +Drivers that capture values for `client.env` should test that a connection and hello command succeeds in the presence of +the following sets of environment variables, and that `client.env.agent` is populated (or omitted) as described. + +1. Generic agent via `AI_AGENT`. `client.env.agent` MUST equal `custom-agent`. + + | Environment Variable | Value | + | -------------------- | -------------- | + | `AI_AGENT` | `custom-agent` | + +2. Generic agent via `AGENT`. `client.env.agent` MUST equal `custom-agent`. + + | Environment Variable | Value | + | -------------------- | -------------- | + | `AGENT` | `custom-agent` | + +3. Known agent. `client.env.agent` MUST equal `claude-code`. + + | Environment Variable | Value | + | -------------------- | ----- | + | `CLAUDECODE` | `1` | + +4. Precedence - generic wins over known. `client.env.agent` MUST equal `custom-agent` (the value of `AI_AGENT`), not + `claude-code`. + + | Environment Variable | Value | + | -------------------- | -------------- | + | `AI_AGENT` | `custom-agent` | + | `CLAUDECODE` | `1` | + +5. Precedence - first known wins. `client.env.agent` MUST equal `cursor`. + + | Environment Variable | Value | + | -------------------- | ----- | + | `CURSOR_AGENT` | `1` | + | `GEMINI_CLI` | `1` | + +6. Empty value is treated as unset. `client.env.agent` MUST be omitted. If no other `client.env` fields are populated, + `client.env` MUST be entirely omitted. + + | Environment Variable | Value | + | -------------------- | ------------------- | + | `AI_AGENT` | \`\` (empty string) | + +7. No agent variables. `client.env.agent` MUST be omitted. + + | Environment Variable | Value | + | -------------------- | ----- | + | | | + +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` | + +### Test 3: Test that the driver accepts an arbitrary auth mechanism 1. Mock the server response in a way that `saslSupportedMechs` array in the `hello` command response contains an arbitrary string. From 8e7ea81328cf7bf4ee26cff3adc06a61de2417f3 Mon Sep 17 00:00:00 2001 From: Jeffrey 'Alex' Clark Date: Tue, 4 Aug 2026 16:36:29 -0400 Subject: [PATCH 2/5] DRIVERS-3529 Address review: renumber agent prose test to Test 3, reflow Agent prose --- source/mongodb-handshake/handshake.md | 20 +++++++++----------- source/mongodb-handshake/tests/README.md | 20 ++++++++++---------- 2 files changed, 19 insertions(+), 21 deletions(-) diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md index efe71978e8..f52d5ecec6 100644 --- a/source/mongodb-handshake/handshake.md +++ b/source/mongodb-handshake/handshake.md @@ -332,13 +332,12 @@ field to be omitted and MUST NOT cause a user-visible error. ##### Agent -Many AI coding assistants and agentic clients ("agents", e.g. Claude Code, Cursor, Gemini CLI) set an environment -variable in the process environment when they execute shell commands or code on a user's behalf. `client.env.agent` -captures which agent, if any, is driving the client, so that agent-mediated usage of MongoDB can be distinguished from -direct human usage. +Agents are AI coding assistants and agentic clients, such as Claude Code, Cursor, and Gemini CLI. Most agents set an +environment variable when they execute shell commands or code on a user's behalf. `client.env.agent` captures which +agent, if any, is driving the client. This distinguishes agent-mediated usage of MongoDB from direct human usage. -`client.env.agent` is a single string, determined by which of the following environment variables are populated. The -list MUST be evaluated in order, and the first match determines the value; subsequent entries MUST NOT be considered: +`client.env.agent` is a single string. Its value is determined by the environment variables below. Drivers MUST evaluate +the list in order. The first populated variable determines the value, and subsequent entries MUST NOT be considered. | Order | Environment Variable | `client.env.agent` value | | ----- | -------------------- | ------------------------ | @@ -351,12 +350,11 @@ list MUST be evaluated in order, and the first match determines the value; subse | 7 | `AUGMENT_AGENT` | `augment` | | 8 | `OPENCODE_CLIENT` | `opencode` | -For entries 1 and 2 (`AI_AGENT` and `AGENT`), the value of `client.env.agent` is the value of the environment variable. -For entries 3 through 8, the value of `client.env.agent` is the fixed string in the table above, regardless of the value -of the environment variable. +For entries 1 and 2, `client.env.agent` is the value of the environment variable. For entries 3 through 8, +`client.env.agent` is the fixed string in the table above, regardless of the value of the environment variable. -An environment variable is considered populated if it is present in the environment with a non-empty value. If none of -the above environment variables are populated, `client.env.agent` MUST be entirely omitted. +A variable is considered populated if it is present in the environment with a non-empty value. If none of the variables +above are populated, `client.env.agent` MUST be entirely omitted. Determination of `client.env.agent` MUST NOT cause a user-visible error. diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md index c3ad897266..b5bf4ed808 100644 --- a/source/mongodb-handshake/tests/README.md +++ b/source/mongodb-handshake/tests/README.md @@ -74,7 +74,16 @@ the following sets of environment variables: | `AWS_LAMBDA_FUNCTION_MEMORY_SIZE` | `1024` | | `KUBERNETES_SERVICE_HOST` | `1` | -### Test 2: Test that agent metadata is properly captured +### Test 2: Test that the driver accepts an arbitrary auth mechanism + +1. Mock the server response in a way that `saslSupportedMechs` array in the `hello` command response contains an + arbitrary string. + +2. Create and connect a `Connection` object that connects to the server that returns the mocked response. + +3. Assert that no error is raised. + +### Test 3: Test that agent metadata is properly captured Drivers that capture values for `client.env` should test that a connection and hello command succeeds in the presence of the following sets of environment variables, and that `client.env.agent` is populated (or omitted) as described. @@ -134,15 +143,6 @@ the following sets of environment variables, and that `client.env.agent` is popu | `AWS_REGION` | `us-east-2` | | `CLAUDECODE` | `1` | -### Test 3: Test that the driver accepts an arbitrary auth mechanism - -1. Mock the server response in a way that `saslSupportedMechs` array in the `hello` command response contains an - arbitrary string. - -2. Create and connect a `Connection` object that connects to the server that returns the mocked response. - -3. Assert that no error is raised. - ## Client Metadata Update Prose Tests Drivers that do not emit events for commands issued as part of the handshake with the server will need to create a From 0821be020586ddb204bdd623350b35c34b1ffab2 Mon Sep 17 00:00:00 2001 From: Jeffrey 'Alex' Clark Date: Tue, 4 Aug 2026 16:44:03 -0400 Subject: [PATCH 3/5] DRIVERS-3529 Use "" for empty string in agent prose test table --- source/mongodb-handshake/tests/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md index b5bf4ed808..51be7e0225 100644 --- a/source/mongodb-handshake/tests/README.md +++ b/source/mongodb-handshake/tests/README.md @@ -126,7 +126,7 @@ the following sets of environment variables, and that `client.env.agent` is popu | Environment Variable | Value | | -------------------- | ------------------- | - | `AI_AGENT` | \`\` (empty string) | + | `AI_AGENT` | `""` (empty string) | 7. No agent variables. `client.env.agent` MUST be omitted. From 4b5c1604e0ffbbd22003042a441362e7f7caa718 Mon Sep 17 00:00:00 2001 From: Jeffrey 'Alex' Clark Date: Tue, 4 Aug 2026 16:49:45 -0400 Subject: [PATCH 4/5] DRIVERS-3529 Replace empty table with prose in "no agent variables" test --- source/mongodb-handshake/tests/README.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md index 51be7e0225..398adc5fb3 100644 --- a/source/mongodb-handshake/tests/README.md +++ b/source/mongodb-handshake/tests/README.md @@ -128,11 +128,8 @@ the following sets of environment variables, and that `client.env.agent` is popu | -------------------- | ------------------- | | `AI_AGENT` | `""` (empty string) | -7. No agent variables. `client.env.agent` MUST be omitted. - - | Environment Variable | Value | - | -------------------- | ----- | - | | | +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`. From feaec8d0ca332a80f457f75c6ef1600267e61d64 Mon Sep 17 00:00:00 2001 From: Jeffrey 'Alex' Clark Date: Tue, 4 Aug 2026 17:00:58 -0400 Subject: [PATCH 5/5] DRIVERS-3529 Fix subject-verb agreement in handshake prose test intros --- source/mongodb-handshake/tests/README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md index 398adc5fb3..aefea61c41 100644 --- a/source/mongodb-handshake/tests/README.md +++ b/source/mongodb-handshake/tests/README.md @@ -4,7 +4,7 @@ ### Test 1: Test that environment metadata is properly captured -Drivers that capture values for `client.env` should test that a connection and hello command succeeds in the presence of +Drivers that capture values for `client.env` should test that a connection and hello command succeed in the presence of the following sets of environment variables: 1. Valid AWS @@ -85,7 +85,7 @@ the following sets of environment variables: ### Test 3: Test that agent metadata is properly captured -Drivers that capture values for `client.env` should test that a connection and hello command succeeds in the presence of +Drivers that capture values for `client.env` should test that a connection and hello command succeed in the presence of the following sets of environment variables, and that `client.env.agent` is populated (or omitted) as described. 1. Generic agent via `AI_AGENT`. `client.env.agent` MUST equal `custom-agent`.