Skip to content

DRIVERS-3529 Add env.agent to handshake metadata for agentic client identification #1967

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
aclark4life wants to merge 5 commits into
base: master
Choose a base branch
from
Open

DRIVERS-3529 Add env.agent to handshake metadata for agentic client identification #1967

Show file tree
Hide file tree
Changes from 1 commit
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
8c1e1f0
DRIVERS-3529 Add env.agent to handshake metadata for agentic client i…
aclark4life Jul 22, 2026
8e7ea81
DRIVERS-3529 Address review: renumber agent prose test to Test 3, ref…
aclark4life Aug 4, 2026
0821be0
DRIVERS-3529 Use "" for empty string in agent prose test table
aclark4life Aug 4, 2026
4b5c160
DRIVERS-3529 Replace empty table with prose in "no agent variables" test
aclark4life Aug 4, 2026
feaec8d
DRIVERS-3529 Fix subject-verb agreement in handshake prose test intros
aclark4life Aug 4, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
38 changes: 35 additions & 3 deletions source/mongodb-handshake/handshake.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -148,6 +148,7 @@ the following structure:
timeout_sec: 42, /* OPTIONAL */
memory_mb: 1024, /* OPTIONAL */
region: "<string>", /* OPTIONAL */
agent: "<string>", /* OPTIONAL */
/* OPTIONAL */
container: {
runtime: "<string>", /* OPTIONAL */
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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

@blink1073 blink1073 Aug 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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

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`.
Expand Down Expand Up @@ -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`.
Expand Down Expand Up @@ -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.
Expand Down
62 changes: 61 additions & 1 deletion source/mongodb-handshake/tests/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

@blink1073 blink1073 Aug 4, 2026

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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


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) |
Comment thread
aclark4life marked this conversation as resolved.
Outdated

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.
Expand Down
Loading