{"meta":{"title":"Steering and queueing","intro":"Two interaction patterns let users send messages while the agent is already working: steering redirects the agent mid-turn, and queueing buffers messages for sequential processing after the current turn completes.","product":"GitHub Copilot","breadcrumbs":[{"href":"/en/enterprise-cloud@latest/copilot","title":"GitHub Copilot"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos","title":"How-tos"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk","title":"Copilot SDK"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features","title":"Features"},{"href":"/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/steering-and-queueing","title":"Steering And Queueing"}],"documentType":"article"},"body":"# Steering and queueing\n\nTwo interaction patterns let users send messages while the agent is already working: steering redirects the agent mid-turn, and queueing buffers messages for sequential processing after the current turn completes.\n\n\n\n\n\n## Overview\n\nWhen a session is actively processing a turn, incoming messages can be delivered in one of two modes via the `mode` field on `MessageOptions`:\n\n| Mode | Behavior | Use case |\n| ------------------------ | -------------------------------------------------------- | ----------------------------------------------------------- |\n| `\"immediate\"` (steering) | Injected into the **current** LLM turn | \"Actually, don't create that file—use a different approach\" |\n| `\"enqueue\"` (queueing) | Queued and processed **after** the current turn finishes | \"After this, also fix the tests\" |\n\n![Diagram: Sequence diagram showing the described process.](/assets/images/help/copilot/copilot-sdk/features-steering-and-queueing-diagram-0.png)\n\n## Steering (immediate mode)\n\nSteering sends a message that is injected directly into the agent's current turn. The agent sees the message in real time and adjusts its response accordingly—useful for course-correcting without aborting the turn.\n\n
\n
TypeScript
\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient();\nawait client.start();\n\nconst session = await client.createSession({\n model: \"gpt-5.4\",\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n\n// Start a long-running task\nconst msgId = await session.send({\n prompt: \"Refactor the authentication module to use sessions\",\n});\n\n// While the agent is working, steer it\nawait session.send({\n prompt: \"Actually, use JWT tokens instead of sessions\",\n mode: \"immediate\",\n});\n```\n\n
\n\n
Python
\n\n```python\nfrom copilot import CopilotClient, PermissionDecisionApproveOnce\n\nasync def main():\n client = CopilotClient()\n await client.start()\n\n session = await client.create_session(\n on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n model=\"gpt-5.4\",\n )\n\n # Start a long-running task\n msg_id = await session.send(\n \"Refactor the authentication module to use sessions\",\n )\n\n # While the agent is working, steer it\n await session.send(\n \"Actually, use JWT tokens instead of sessions\",\n mode=\"immediate\",\n )\n\n await client.stop()\n```\n\n
\n\n
Go
\n\n```golang\npackage main\n\nimport (\n \"context\"\n \"log\"\n copilot \"github.com/github/copilot-sdk/go\"\n \"github.com/github/copilot-sdk/go/rpc\"\n)\n\nfunc main() {\n ctx := context.Background()\n client := copilot.NewClient(nil)\n if err := client.Start(ctx); err != nil {\n log.Fatal(err)\n }\n defer client.Stop()\n\n session, err := client.CreateSession(ctx, &copilot.SessionConfig{\n Model: \"gpt-5.4\",\n OnPermissionRequest: func(req copilot.PermissionRequest, inv copilot.PermissionInvocation) (rpc.PermissionDecision, error) {\n return &rpc.PermissionDecisionApproveOnce{}, nil\n },\n })\n if err != nil {\n log.Fatal(err)\n }\n\n // Start a long-running task\n _, err = session.Send(ctx, copilot.MessageOptions{\n Prompt: \"Refactor the authentication module to use sessions\",\n })\n if err != nil {\n log.Fatal(err)\n }\n\n // While the agent is working, steer it\n _, err = session.Send(ctx, copilot.MessageOptions{\n Prompt: \"Actually, use JWT tokens instead of sessions\",\n Mode: \"immediate\",\n })\n if err != nil {\n log.Fatal(err)\n }\n}\n```\n\n
\n\n
.NET
\n\n```csharp\nusing GitHub.Copilot;\nusing GitHub.Copilot.Rpc;\n\nawait using var client = new CopilotClient();\nawait using var session = await client.CreateSessionAsync(new SessionConfig\n{\n Model = \"gpt-5.4\",\n OnPermissionRequest = (req, inv) =>\n Task.FromResult(PermissionDecision.ApproveOnce()),\n});\n\n// Start a long-running task\nvar msgId = await session.SendAsync(new MessageOptions\n{\n Prompt = \"Refactor the authentication module to use sessions\"\n});\n\n// While the agent is working, steer it\nawait session.SendAsync(new MessageOptions\n{\n Prompt = \"Actually, use JWT tokens instead of sessions\",\n Mode = \"immediate\"\n});\n```\n\n
\n\n
Java
\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\n\ntry (var client = new CopilotClient()) {\n client.start().get();\n\n var session = client.createSession(\n new SessionConfig()\n .setModel(\"gpt-5.4\")\n .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n ).get();\n\n // Start a long-running task\n session.send(new MessageOptions()\n .setPrompt(\"Refactor the authentication module to use sessions\")\n ).get();\n\n // While the agent is working, steer it\n session.send(new MessageOptions()\n .setPrompt(\"Actually, use JWT tokens instead of sessions\")\n .setMode(\"immediate\")\n ).get();\n}\n```\n\n
\n\n
\n\n### How steering works internally\n\n1. The message is added to the runtime's `ImmediatePromptProcessor` queue\n2. Before the next LLM request within the current turn, the processor injects the message into the conversation\n3. The agent sees the steering message as a new user message and adjusts its response\n4. If the turn completes before the steering message is processed, it is automatically moved to the regular queue for the next turn\n\n> \\[!NOTE]\n> Steering messages are best-effort within the current turn. If the agent has already committed to a tool call, the steering takes effect after that call completes but still within the same turn.\n\n## Queueing (enqueue mode)\n\nQueueing buffers messages to be processed sequentially after the current turn finishes. Each queued message starts its own full turn. This is the default mode—if you omit `mode`, the SDK uses `\"enqueue\"`.\n\n
\n
TypeScript
\n\n```typescript\nimport { CopilotClient } from \"@github/copilot-sdk\";\n\nconst client = new CopilotClient();\nawait client.start();\n\nconst session = await client.createSession({\n model: \"gpt-5.4\",\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n\n// Send an initial task\nawait session.send({ prompt: \"Set up the project structure\" });\n\n// Queue follow-up tasks while the agent is busy\nawait session.send({\n prompt: \"Add unit tests for the auth module\",\n mode: \"enqueue\",\n});\n\nawait session.send({\n prompt: \"Update the README with setup instructions\",\n mode: \"enqueue\",\n});\n\n// Messages are processed in FIFO order after each turn completes\n```\n\n
\n\n
Python
\n\n```python\nfrom copilot import CopilotClient, PermissionDecisionApproveOnce\n\nasync def main():\n client = CopilotClient()\n await client.start()\n\n session = await client.create_session(\n on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n model=\"gpt-5.4\",\n )\n\n # Send an initial task\n await session.send(\"Set up the project structure\")\n\n # Queue follow-up tasks while the agent is busy\n await session.send(\n \"Add unit tests for the auth module\",\n mode=\"enqueue\",\n )\n\n await session.send(\n \"Update the README with setup instructions\",\n mode=\"enqueue\",\n )\n\n # Messages are processed in FIFO order after each turn completes\n await client.stop()\n```\n\n
\n\n
Go
\n\n```golang\n// Send an initial task\nsession.Send(ctx, copilot.MessageOptions{\n Prompt: \"Set up the project structure\",\n})\n\n// Queue follow-up tasks while the agent is busy\nsession.Send(ctx, copilot.MessageOptions{\n Prompt: \"Add unit tests for the auth module\",\n Mode: \"enqueue\",\n})\n\nsession.Send(ctx, copilot.MessageOptions{\n Prompt: \"Update the README with setup instructions\",\n Mode: \"enqueue\",\n})\n\n// Messages are processed in FIFO order after each turn completes\n```\n\n
\n\n
.NET
\n\n```csharp\n// Send an initial task\nawait session.SendAsync(new MessageOptions\n{\n Prompt = \"Set up the project structure\"\n});\n\n// Queue follow-up tasks while the agent is busy\nawait session.SendAsync(new MessageOptions\n{\n Prompt = \"Add unit tests for the auth module\",\n Mode = \"enqueue\"\n});\n\nawait session.SendAsync(new MessageOptions\n{\n Prompt = \"Update the README with setup instructions\",\n Mode = \"enqueue\"\n});\n\n// Messages are processed in FIFO order after each turn completes\n```\n\n
\n\n
Java
\n\n```java\nimport com.github.copilot.CopilotClient;\nimport com.github.copilot.rpc.*;\n\ntry (var client = new CopilotClient()) {\n client.start().get();\n\n var session = client.createSession(\n new SessionConfig()\n .setModel(\"gpt-5.4\")\n .setOnPermissionRequest(PermissionHandler.APPROVE_ALL)\n ).get();\n\n // Send an initial task\n session.send(new MessageOptions().setPrompt(\"Set up the project structure\")).get();\n\n // Queue follow-up tasks while the agent is busy\n session.send(new MessageOptions()\n .setPrompt(\"Add unit tests for the auth module\")\n .setMode(\"enqueue\")\n ).get();\n\n session.send(new MessageOptions()\n .setPrompt(\"Update the README with setup instructions\")\n .setMode(\"enqueue\")\n ).get();\n\n // Messages are processed in FIFO order after each turn completes\n}\n```\n\n
\n\n
\n\n### How queueing works internally\n\n1. The message is added to the session's `itemQueue` as a `QueuedItem`\n2. When the current turn completes and the session becomes idle, `processQueuedItems()` runs\n3. Items are dequeued in FIFO order—each message triggers a full agentic turn\n4. If a steering message was pending when the turn ended, it is moved to the front of the queue\n5. Processing continues until the queue is empty, then the session emits an idle event\n\n## Combining steering and queueing\n\nYou can use both patterns together in a single session. Steering affects the current turn while queued messages wait for their own turns:\n\n
\n
TypeScript
\n\n```typescript\nconst session = await client.createSession({\n model: \"gpt-5.4\",\n onPermissionRequest: async () => ({ kind: \"approve-once\" }),\n});\n\n// Start a task\nawait session.send({ prompt: \"Refactor the database layer\" });\n\n// Steer the current work\nawait session.send({\n prompt: \"Make sure to keep backwards compatibility with the v1 API\",\n mode: \"immediate\",\n});\n\n// Queue a follow-up for after this turn\nawait session.send({\n prompt: \"Now add migration scripts for the schema changes\",\n mode: \"enqueue\",\n});\n```\n\n
\n\n
Python
\n\n```python\nsession = await client.create_session(\n on_permission_request=lambda req, inv: PermissionDecisionApproveOnce(),\n model=\"gpt-5.4\",\n)\n\n# Start a task\nawait session.send(\"Refactor the database layer\")\n\n# Steer the current work\nawait session.send(\n \"Make sure to keep backwards compatibility with the v1 API\",\n mode=\"immediate\",\n)\n\n# Queue a follow-up for after this turn\nawait session.send(\n \"Now add migration scripts for the schema changes\",\n mode=\"enqueue\",\n)\n```\n\n
\n\n
\n\n## Choosing between steering and queueing\n\n| Scenario | Pattern | Why |\n| ------------------------------------------------- | ------------ | -------------------------------------------------- |\n| Agent is going down the wrong path | **Steering** | Redirects the current turn without losing progress |\n| You thought of something the agent should also do | **Queueing** | Doesn't disrupt current work; runs next |\n| Agent is about to make a mistake | **Steering** | Intervenes before the mistake is committed |\n| You want to chain multiple tasks | **Queueing** | FIFO ordering ensures predictable execution |\n| You want to add context to the current task | **Steering** | Agent incorporates it into its current reasoning |\n| You want to batch unrelated requests | **Queueing** | Each gets its own full turn with clean context |\n\n## Building a UI with steering and queueing\n\nHere's a pattern for building an interactive UI that supports both modes:\n\n```typescript\nimport { CopilotClient, CopilotSession } from \"@github/copilot-sdk\";\n\ninterface PendingMessage {\n prompt: string;\n mode: \"immediate\" | \"enqueue\";\n sentAt: Date;\n}\n\nclass InteractiveChat {\n private session: CopilotSession;\n private isProcessing = false;\n private pendingMessages: PendingMessage[] = [];\n\n constructor(session: CopilotSession) {\n this.session = session;\n\n session.on((event) => {\n if (event.type === \"session.idle\") {\n this.isProcessing = false;\n this.onIdle();\n }\n if (event.type === \"assistant.message\") {\n this.renderMessage(event);\n }\n });\n }\n\n async sendMessage(prompt: string): Promise {\n if (!this.isProcessing) {\n this.isProcessing = true;\n await this.session.send({ prompt });\n return;\n }\n\n // Session is busy — let the user choose how to deliver\n // Your UI would present this choice (e.g., buttons, keyboard shortcuts)\n }\n\n async steer(prompt: string): Promise {\n this.pendingMessages.push({\n prompt,\n mode: \"immediate\",\n sentAt: new Date(),\n });\n await this.session.send({ prompt, mode: \"immediate\" });\n }\n\n async enqueue(prompt: string): Promise {\n this.pendingMessages.push({\n prompt,\n mode: \"enqueue\",\n sentAt: new Date(),\n });\n await this.session.send({ prompt, mode: \"enqueue\" });\n }\n\n private onIdle(): void {\n this.pendingMessages = [];\n // Update UI to show session is ready for new input\n }\n\n private renderMessage(event: unknown): void {\n // Render assistant message in your UI\n }\n}\n```\n\n## API reference\n\n### MessageOptions\n\n| Language | Field | Type | Default | Description |\n| -------- | ------ | --------------------------------- | ----------- | --------------------- |\n| Node.js | `mode` | `\"enqueue\" \\| \"immediate\"` | `\"enqueue\"` | Message delivery mode |\n| Python | `mode` | `Literal[\"enqueue\", \"immediate\"]` | `\"enqueue\"` | Message delivery mode |\n| Go | `Mode` | `string` | `\"enqueue\"` | Message delivery mode |\n| .NET | `Mode` | `string?` | `\"enqueue\"` | Message delivery mode |\n\n### Delivery modes\n\n| Mode | Effect | During active turn | During idle |\n| ------------- | ------------------------ | ----------------------------- | ----------------------------- |\n| `\"enqueue\"` | Queue for next turn | Waits in FIFO queue | Starts a new turn immediately |\n| `\"immediate\"` | Inject into current turn | Injected before next LLM call | Starts a new turn immediately |\n\n> \\[!NOTE]\n> When the session is idle (not processing), both modes behave identically—the message starts a new turn immediately.\n\n## Best practices\n\n1. **Default to queueing**—Use `\"enqueue\"` (or omit `mode`) for most messages. It's predictable and doesn't risk disrupting in-progress work.\n\n2. **Reserve steering for corrections**—Use `\"immediate\"` when the agent is actively doing the wrong thing and you need to redirect it before it goes further.\n\n3. **Keep steering messages concise**—The agent needs to quickly understand the course correction. Long, complex steering messages may confuse the current context.\n\n4. **Don't over-steer**—Multiple rapid steering messages can degrade turn quality. If you need to change direction significantly, consider aborting the turn and starting fresh.\n\n5. **Show queue state in your UI**—Display the number of queued messages so users know what's pending. Listen for idle events to clear the display.\n\n6. **Handle the steering-to-queue fallback**—If a steering message arrives after the turn completes, it's automatically moved to the queue. Design your UI to reflect this transition.\n\n## See also\n\n* [Build your first Copilot-powered app](/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/getting-started): Set up a session and send messages\n* [Custom agents and sub-agent orchestration](/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/custom-agents): Define specialized agents with scoped tools\n* [Session hooks](/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/hooks/hooks-overview): React to session lifecycle events\n* [Session resume and persistence](/en/enterprise-cloud@latest/copilot/how-tos/copilot-sdk/features/session-persistence): Resume sessions across restarts"}