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 3 commits
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
36 changes: 33 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,34 @@ 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

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. 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 |
| ----- | -------------------- | ------------------------ |
| 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, `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.

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.

##### Container

Container runtime information is captured in `client.env.container`.
Expand Down Expand Up @@ -475,7 +504,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 +594,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
60 changes: 60 additions & 0 deletions source/mongodb-handshake/tests/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -83,6 +83,66 @@ the following sets of environment variables:

3. Assert that no error is raised.

### Test 3: Test that agent metadata is properly captured
Comment thread
aclark4life marked this conversation as resolved.

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` |

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