diff --git a/source/mongodb-handshake/handshake.md b/source/mongodb-handshake/handshake.md index 07c326b5d4..f52d5ecec6 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,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`. @@ -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`. @@ -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. diff --git a/source/mongodb-handshake/tests/README.md b/source/mongodb-handshake/tests/README.md index ed56e5dc46..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 @@ -83,6 +83,63 @@ the following sets of environment variables: 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 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`. + + | 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. 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` | + ## 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