Add MessageOptions.agentMode and fix per-message mode misuse

MRayermannMSFT · MRayermannMSFT · commit fa4e46314c1a · 2026-05-26T16:30:30.000-07:00
Adds a public agentMode field on MessageOptions across .NET, Node, Python, and Go SDKs so callers can set the per-message UI mode (interactive/plan/autopilot/shell) without abusing the queue-delivery mode field. Fixes the misleading Mode XML doc in .NET, and updates the four E2E/unit tests that were setting mode=`plan` (via casts, type:ignore, or silently in .NET) to use the new agentMode field and assert the runtime echoes it back on user.message.
diff --git a/dotnet/src/Session.cs b/dotnet/src/Session.cs
@@ -276,6 +276,7 @@ public async Task<string> SendAsync(MessageOptions options, CancellationToken ca
             Prompt = options.Prompt,
             Attachments = options.Attachments,
             Mode = options.Mode,
+            AgentMode = options.AgentMode,
             Traceparent = traceparent,
             Tracestate = tracestate,
             RequestHeaders = options.RequestHeaders,
@@ -1665,6 +1666,8 @@ internal record SendMessageRequest
         public string Prompt { get; init; } = string.Empty;
         public IList<UserMessageAttachment>? Attachments { get; init; }
         public string? Mode { get; init; }
+        [JsonPropertyName("agentMode")]
+        public AgentMode? AgentMode { get; init; }
         public string? Traceparent { get; init; }
         public string? Tracestate { get; init; }
         public IDictionary<string, string>? RequestHeaders { get; init; }
diff --git a/dotnet/src/Types.cs b/dotnet/src/Types.cs
@@ -1711,6 +1711,29 @@ public enum SystemMessageMode
     Customize
 }
 
+/// <summary>
+/// The UI mode the agent is in for a given turn.
+/// </summary>
+/// <remarks>
+/// Set on <see cref="MessageOptions.AgentMode"/> to send a message in a specific mode; defaults to the session's current mode.
+/// </remarks>
+[JsonConverter(typeof(JsonStringEnumConverter<AgentMode>))]
+public enum AgentMode
+{
+    /// <summary>The agent is responding interactively to the user.</summary>
+    [JsonStringEnumMemberName("interactive")]
+    Interactive,
+    /// <summary>The agent is preparing a plan before making changes.</summary>
+    [JsonStringEnumMemberName("plan")]
+    Plan,
+    /// <summary>The agent is working autonomously toward task completion.</summary>
+    [JsonStringEnumMemberName("autopilot")]
+    Autopilot,
+    /// <summary>The agent is in shell-focused UI mode.</summary>
+    [JsonStringEnumMemberName("shell")]
+    Shell
+}
+
 /// <summary>
 /// Specifies the operation to perform on a system message section.
 /// </summary>
@@ -2645,6 +2668,7 @@ private MessageOptions(MessageOptions? other)
 
         Attachments = other.Attachments is not null ? [.. other.Attachments] : null;
         Mode = other.Mode;
+        AgentMode = other.AgentMode;
         Prompt = other.Prompt;
         RequestHeaders = other.RequestHeaders is not null
             ? new Dictionary<string, string>(other.RequestHeaders)
@@ -2660,10 +2684,16 @@ private MessageOptions(MessageOptions? other)
     /// </summary>
     public IList<UserMessageAttachment>? Attachments { get; set; }
     /// <summary>
-    /// Interaction mode for the message (e.g., "plan", "edit").
+    /// How to deliver the message. <c>"enqueue"</c> (default) appends to the message queue;
+    /// <c>"immediate"</c> interjects during an in-progress turn.
     /// </summary>
     public string? Mode { get; set; }
     /// <summary>
+    /// The UI mode the agent was in when this message was sent (for example "plan", "autopilot").
+    /// Defaults to the session's current mode when unset.
+    /// </summary>
+    public AgentMode? AgentMode { get; set; }
+    /// <summary>
     /// Custom per-turn HTTP headers for outbound model requests.
     /// </summary>
     public IDictionary<string, string>? RequestHeaders { get; set; }
diff --git a/dotnet/test/E2E/ModeHandlersE2ETests.cs b/dotnet/test/E2E/ModeHandlersE2ETests.cs
@@ -53,7 +53,7 @@ public async Task Should_Invoke_Exit_Plan_Mode_Handler_When_Model_Uses_Tool()
 
         var response = await session.SendAndWaitAsync(new MessageOptions
         {
-            Mode = "plan",
+            AgentMode = AgentMode.Plan,
             Prompt = "Create a brief implementation plan for adding a greeting.txt file, then request approval with exit_plan_mode.",
         }, timeout: TimeSpan.FromSeconds(120));
 
diff --git a/dotnet/test/E2E/SessionE2ETests.cs b/dotnet/test/E2E/SessionE2ETests.cs
@@ -851,20 +851,19 @@ await session.SendAndWaitAsync(new MessageOptions
     }
 
     [Fact]
-    public async Task Should_Send_With_Mode_Property()
+    public async Task Should_Send_With_AgentMode_Property()
     {
         var session = await CreateSessionAsync();
 
         await session.SendAndWaitAsync(new MessageOptions
         {
             Prompt = "Say mode ok.",
-            Mode = "plan",
+            AgentMode = AgentMode.Plan,
         });
 
         var userMessage = (await session.GetEventsAsync()).OfType<UserMessageEvent>().Last();
         Assert.Equal("Say mode ok.", userMessage.Data.Content);
-        // The current runtime accepts the per-message mode option but does not echo it on user.message.
-        Assert.Null(userMessage.Data.AgentMode);
+        Assert.Equal(UserMessageAgentMode.Plan, userMessage.Data.AgentMode);
     }
 
     [Fact]
diff --git a/dotnet/test/Unit/SerializationTests.cs b/dotnet/test/Unit/SerializationTests.cs
@@ -57,21 +57,21 @@ public void MessageOptions_CanSerializeRequestHeaders_WithSdkOptions()
         var original = new MessageOptions
         {
             Prompt = "real prompt",
-            Mode = "plan",
+            Mode = "enqueue",
             RequestHeaders = new Dictionary<string, string> { ["X-Trace"] = "trace-value" }
         };
 
         var json = JsonSerializer.Serialize(original, options);
         using var document = JsonDocument.Parse(json);
         var root = document.RootElement;
         Assert.Equal("real prompt", root.GetProperty("prompt").GetString());
-        Assert.Equal("plan", root.GetProperty("mode").GetString());
+        Assert.Equal("enqueue", root.GetProperty("mode").GetString());
         Assert.Equal("trace-value", root.GetProperty("requestHeaders").GetProperty("X-Trace").GetString());
 
         var deserialized = JsonSerializer.Deserialize<MessageOptions>(json, options);
         Assert.NotNull(deserialized);
         Assert.Equal("real prompt", deserialized.Prompt);
-        Assert.Equal("plan", deserialized.Mode);
+        Assert.Equal("enqueue", deserialized.Mode);
         Assert.Equal("trace-value", deserialized.RequestHeaders!["X-Trace"]);
     }
 
@@ -84,15 +84,15 @@ public void SendMessageRequest_CanSerializeRequestHeaders_WithSdkOptions()
             requestType,
             ("SessionId", "session-id"),
             ("Prompt", "real prompt"),
-            ("Mode", "plan"),
+            ("Mode", "enqueue"),
             ("RequestHeaders", new Dictionary<string, string> { ["X-Trace"] = "trace-value" }));
 
         var json = JsonSerializer.Serialize(request, requestType, options);
         using var document = JsonDocument.Parse(json);
         var root = document.RootElement;
         Assert.Equal("session-id", root.GetProperty("sessionId").GetString());
         Assert.Equal("real prompt", root.GetProperty("prompt").GetString());
-        Assert.Equal("plan", root.GetProperty("mode").GetString());
+        Assert.Equal("enqueue", root.GetProperty("mode").GetString());
         Assert.Equal("trace-value", root.GetProperty("requestHeaders").GetProperty("X-Trace").GetString());
     }
 
diff --git a/go/internal/e2e/mode_handlers_e2e_test.go b/go/internal/e2e/mode_handlers_e2e_test.go
@@ -84,8 +84,8 @@ func TestModeHandlersE2E(t *testing.T) {
 		)
 
 		response, err := session.SendAndWait(t.Context(), copilot.MessageOptions{
-			Prompt: planPrompt,
-			Mode:   "plan",
+			Prompt:    planPrompt,
+			AgentMode: copilot.AgentModePlan,
 		})
 		if err != nil {
 			t.Fatalf("Failed to send message: %v", err)
diff --git a/go/internal/e2e/session_e2e_test.go b/go/internal/e2e/session_e2e_test.go
@@ -1499,7 +1499,7 @@ func TestSessionMessageOptionsE2E(t *testing.T) {
 		t.Fatalf("Failed to start client: %v", err)
 	}
 
-	t.Run("should send with mode property", func(t *testing.T) {
+	t.Run("should send with agentMode property", func(t *testing.T) {
 		ctx.ConfigureForTest(t)
 
 		session, err := client.CreateSession(t.Context(), &copilot.SessionConfig{
@@ -1510,8 +1510,8 @@ func TestSessionMessageOptionsE2E(t *testing.T) {
 		}
 
 		_, err = session.SendAndWait(t.Context(), copilot.MessageOptions{
-			Prompt: "Say mode ok.",
-			Mode:   "plan",
+			Prompt:    "Say mode ok.",
+			AgentMode: copilot.AgentModePlan,
 		})
 		if err != nil {
 			t.Fatalf("SendAndWait failed: %v", err)
@@ -1535,10 +1535,8 @@ func TestSessionMessageOptionsE2E(t *testing.T) {
 		if userMsg.Content != "Say mode ok." {
 			t.Errorf("Expected Content 'Say mode ok.', got %q", userMsg.Content)
 		}
-		// The current runtime accepts the per-message mode option but does not
-		// echo it back on the user.message event.
-		if userMsg.AgentMode != nil {
-			t.Errorf("Expected AgentMode=nil, got %v", *userMsg.AgentMode)
+		if userMsg.AgentMode == nil || *userMsg.AgentMode != copilot.UserMessageAgentModePlan {
+			t.Errorf("Expected AgentMode=plan, got %v", userMsg.AgentMode)
 		}
 	})
 
diff --git a/go/session.go b/go/session.go
@@ -289,6 +289,7 @@ func (s *Session) Send(ctx context.Context, options MessageOptions) (string, err
 		Prompt:         options.Prompt,
 		Attachments:    options.Attachments,
 		Mode:           options.Mode,
+		AgentMode:      options.AgentMode,
 		Traceparent:    traceparent,
 		Tracestate:     tracestate,
 		RequestHeaders: options.RequestHeaders,
diff --git a/go/types.go b/go/types.go
@@ -1316,10 +1316,26 @@ type MessageOptions struct {
 	Attachments []Attachment
 	// Mode is the message delivery mode (default: "enqueue")
 	Mode string
+	// AgentMode is the UI mode the agent was in when this message was sent
+	// (for example "plan" or "autopilot"). Defaults to the session's current
+	// mode when empty.
+	AgentMode AgentMode
 	// RequestHeaders are custom per-turn HTTP headers for outbound model requests.
 	RequestHeaders map[string]string
 }
 
+// AgentMode is the UI mode the agent is in for a given turn. See
+// [MessageOptions.AgentMode].
+type AgentMode = rpc.SendAgentMode
+
+// AgentMode values supported by the runtime.
+const (
+	AgentModeInteractive = rpc.SendAgentModeInteractive
+	AgentModePlan        = rpc.SendAgentModePlan
+	AgentModeAutopilot   = rpc.SendAgentModeAutopilot
+	AgentModeShell       = rpc.SendAgentModeShell
+)
+
 // SessionEventHandler is a callback for session events
 type SessionEventHandler func(event SessionEvent)
 
@@ -1685,6 +1701,7 @@ type sessionSendRequest struct {
 	Prompt         string            `json:"prompt"`
 	Attachments    []Attachment      `json:"attachments,omitempty"`
 	Mode           string            `json:"mode,omitempty"`
+	AgentMode      AgentMode         `json:"agentMode,omitempty"`
 	Traceparent    string            `json:"traceparent,omitempty"`
 	Tracestate     string            `json:"tracestate,omitempty"`
 	RequestHeaders map[string]string `json:"requestHeaders,omitempty"`
diff --git a/java/src/main/java/com/github/copilot/sdk/CopilotSession.java b/java/src/main/java/com/github/copilot/sdk/CopilotSession.java
@@ -475,6 +475,7 @@ public CompletableFuture<String> send(MessageOptions options) {
         request.setPrompt(options.getPrompt());
         request.setAttachments(options.getAttachments());
         request.setMode(options.getMode());
+        request.setAgentMode(options.getAgentMode());
         request.setRequestHeaders(options.getRequestHeaders());
 
         return rpc.invoke("session.send", request, SendMessageResponse.class).thenApply(SendMessageResponse::messageId);
diff --git a/java/src/main/java/com/github/copilot/sdk/json/AgentMode.java b/java/src/main/java/com/github/copilot/sdk/json/AgentMode.java
@@ -0,0 +1,47 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *--------------------------------------------------------------------------------------------*/
+
+package com.github.copilot.sdk.json;
+
+import com.fasterxml.jackson.annotation.JsonValue;
+
+/**
+ * The UI mode the agent is in for a given turn.
+ * <p>
+ * Set on {@link MessageOptions#setAgentMode(AgentMode)} to send a message in a specific mode;
+ * defaults to the session's current mode when unset.
+ *
+ * @see MessageOptions
+ * @since 1.0.0
+ */
+public enum AgentMode {
+
+    /** The agent is responding interactively to the user. */
+    INTERACTIVE("interactive"),
+
+    /** The agent is preparing a plan before making changes. */
+    PLAN("plan"),
+
+    /** The agent is working autonomously toward task completion. */
+    AUTOPILOT("autopilot"),
+
+    /** The agent is in shell-focused UI mode. */
+    SHELL("shell");
+
+    private final String value;
+
+    AgentMode(String value) {
+        this.value = value;
+    }
+
+    /**
+     * Returns the JSON value for this agent mode.
+     *
+     * @return the string value used in JSON serialization
+     */
+    @JsonValue
+    public String getValue() {
+        return value;
+    }
+}
diff --git a/java/src/main/java/com/github/copilot/sdk/json/MessageOptions.java b/java/src/main/java/com/github/copilot/sdk/json/MessageOptions.java
@@ -45,6 +45,7 @@ public class MessageOptions {
     private String prompt;
     private List<MessageAttachment> attachments;
     private String mode;
+    private AgentMode agentMode;
     private Map<String, String> requestHeaders;
 
     /**
@@ -126,6 +127,29 @@ public String getMode() {
         return mode;
     }
 
+    /**
+     * Sets the per-message agent UI mode.
+     * <p>
+     * Defaults to the session's current mode when unset.
+     *
+     * @param agentMode
+     *            the agent mode (for example {@link AgentMode#PLAN} or {@link AgentMode#AUTOPILOT})
+     * @return this options instance for method chaining
+     */
+    public MessageOptions setAgentMode(AgentMode agentMode) {
+        this.agentMode = agentMode;
+        return this;
+    }
+
+    /**
+     * Gets the per-message agent UI mode.
+     *
+     * @return the agent mode, or {@code null} if not set
+     */
+    public AgentMode getAgentMode() {
+        return agentMode;
+    }
+
     /**
      * Gets the custom per-turn HTTP headers for outbound model requests.
      *
@@ -167,6 +191,7 @@ public MessageOptions clone() {
         copy.prompt = this.prompt;
         copy.attachments = this.attachments != null ? new ArrayList<>(this.attachments) : null;
         copy.mode = this.mode;
+        copy.agentMode = this.agentMode;
         copy.requestHeaders = this.requestHeaders != null ? new HashMap<>(this.requestHeaders) : null;
         return copy;
     }
diff --git a/java/src/main/java/com/github/copilot/sdk/json/SendMessageRequest.java b/java/src/main/java/com/github/copilot/sdk/json/SendMessageRequest.java
@@ -37,6 +37,9 @@ public final class SendMessageRequest {
     @JsonProperty("mode")
     private String mode;
 
+    @JsonProperty("agentMode")
+    private AgentMode agentMode;
+
     @JsonProperty("requestHeaders")
     private Map<String, String> requestHeaders;
 
@@ -80,6 +83,16 @@ public void setMode(String mode) {
         this.mode = mode;
     }
 
+    /** Gets the per-message agent UI mode. @return the agent mode */
+    public AgentMode getAgentMode() {
+        return agentMode;
+    }
+
+    /** Sets the per-message agent UI mode. @param agentMode the agent mode */
+    public void setAgentMode(AgentMode agentMode) {
+        this.agentMode = agentMode;
+    }
+
     /** Gets the per-turn request headers. @return the headers map */
     public Map<String, String> getRequestHeaders() {
         return requestHeaders == null ? null : Collections.unmodifiableMap(requestHeaders);
diff --git a/nodejs/src/session.ts b/nodejs/src/session.ts
@@ -214,6 +214,7 @@ export class CopilotSession {
             prompt: options.prompt,
             attachments: options.attachments,
             mode: options.mode,
+            agentMode: options.agentMode,
             requestHeaders: options.requestHeaders,
         });
 
diff --git a/nodejs/src/types.ts b/nodejs/src/types.ts
@@ -1928,6 +1928,12 @@ export interface MessageOptions {
      */
     mode?: "enqueue" | "immediate";
 
+    /**
+     * The UI mode the agent was in when this message was sent (for example "plan" or "autopilot").
+     * Defaults to the session's current mode when unset.
+     */
+    agentMode?: "interactive" | "plan" | "autopilot" | "shell";
+
     /**
      * Custom HTTP headers to include in outbound model requests for this turn.
      */
diff --git a/nodejs/test/e2e/mode_handlers.e2e.test.ts b/nodejs/test/e2e/mode_handlers.e2e.test.ts
@@ -104,7 +104,7 @@ describe("Mode handlers", async () => {
 
             const response = await session.sendAndWait({
                 prompt: PLAN_PROMPT,
-                mode: "plan" as unknown as NonNullable<Parameters<typeof session.send>[0]["mode"]>,
+                agentMode: "plan",
             });
 
             expect(exitPlanModeRequests).toHaveLength(1);
diff --git a/nodejs/test/e2e/session.e2e.test.ts b/nodejs/test/e2e/session.e2e.test.ts
diff --git a/python/copilot/session.py b/python/copilot/session.py
diff --git a/python/e2e/test_mode_handlers_e2e.py b/python/e2e/test_mode_handlers_e2e.py
diff --git a/python/e2e/test_session_e2e.py b/python/e2e/test_session_e2e.py
diff --git a/rust/src/session.rs b/rust/src/session.rs
diff --git a/rust/src/types.rs b/rust/src/types.rs

Original file line number	Diff line number	Diff line change
`@@ -53,7 +53,7 @@ public async Task Should_Invoke_Exit_Plan_Mode_Handler_When_Model_Uses_Tool()`
`53`	`53`
`54`	`54`	`var response = await session.SendAndWaitAsync(new MessageOptions`
`55`	`55`	`{`
`56`		`- Mode = "plan",`
	`56`	`+ AgentMode = AgentMode.Plan,`
`57`	`57`	`Prompt = "Create a brief implementation plan for adding a greeting.txt file, then request approval with exit_plan_mode.",`
`58`	`58`	`}, timeout: TimeSpan.FromSeconds(120));`
`59`	`59`
Original file line number	Diff line number	Diff line change
`@@ -851,20 +851,19 @@ await session.SendAndWaitAsync(new MessageOptions`
`851`	`851`	`}`
`852`	`852`
`853`	`853`	`[Fact]`
`854`		`- public async Task Should_Send_With_Mode_Property()`
	`854`	`+ public async Task Should_Send_With_AgentMode_Property()`
`855`	`855`	`{`
`856`	`856`	`var session = await CreateSessionAsync();`
`857`	`857`
`858`	`858`	`await session.SendAndWaitAsync(new MessageOptions`
`859`	`859`	`{`
`860`	`860`	`Prompt = "Say mode ok.",`
`861`		`- Mode = "plan",`
	`861`	`+ AgentMode = AgentMode.Plan,`
`862`	`862`	`});`
`863`	`863`
`864`	`864`	`var userMessage = (await session.GetEventsAsync()).OfType<UserMessageEvent>().Last();`
`865`	`865`	`Assert.Equal("Say mode ok.", userMessage.Data.Content);`
`866`		`- // The current runtime accepts the per-message mode option but does not echo it on user.message.`
`867`		`- Assert.Null(userMessage.Data.AgentMode);`
	`866`	`+ Assert.Equal(UserMessageAgentMode.Plan, userMessage.Data.AgentMode);`
`868`	`867`	`}`
`869`	`868`
`870`	`869`	`[Fact]`