{"meta":{"title":"Direção e fila","intro":"Dois padrões de interação permitem que os usuários enviem mensagens enquanto o agente já está em operação: direcionamento redireciona o agente no meio do turno e enfileiramento armazena mensagens em buffer para processamento sequencial após a conclusão do turno atual.","product":"GitHub Copilot","breadcrumbs":[{"href":"/pt/copilot","title":"GitHub Copilot"},{"href":"/pt/copilot/how-tos","title":"Instruções"},{"href":"/pt/copilot/how-tos/copilot-sdk","title":"SDK do Copilot"},{"href":"/pt/copilot/how-tos/copilot-sdk/features","title":"Features"},{"href":"/pt/copilot/how-tos/copilot-sdk/features/steering-and-queueing","title":"Direção e fila"}],"documentType":"article"},"body":"# Direção e fila\n\nDois padrões de interação permitem que os usuários enviem mensagens enquanto o agente já está em operação: direcionamento redireciona o agente no meio do turno e enfileiramento armazena mensagens em buffer para processamento sequencial após a conclusão do turno atual.\n\n\n\n\n\n## Overview\n\nQuando uma sessão está processando ativamente um turno, as mensagens de entrada podem ser entregues em um dos dois modos por meio do campo `mode` no `MessageOptions`:\n\n| Modo | Behavior | Caso de uso |\n| ---------------------------- | ------------------------------------------------------------ | ----------------------------------------------------------------- |\n| `\"immediate\"` (direção) | Injetado no turno LLM **atual** | \"Na verdade, não crie esse arquivo — use uma abordagem diferente\" |\n| `\"enqueue\"` (enfileiramento) | Enfileirado e processado **após** a conclusão do turno atual | \"Depois disso, corrija também os testes\" |\n\n![Diagrama: diagrama de sequência mostrando o processo descrito.](/assets/images/help/copilot/copilot-sdk/features-steering-and-queueing-diagram-0.png)\n\n## Direção (modo imediato)\n\nO direcionamento envia uma mensagem que é injetada diretamente no turno atual do agente. O agente vê a mensagem em tempo real e ajusta sua resposta adequadamente, sendo útil para correção de curso sem anular o turno.\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### Como a direção funciona internamente\n\n1. A mensagem é adicionada à fila `ImmediatePromptProcessor` do runtime\n2. Antes da próxima solicitação do LLM no turno atual, o processador injeta a mensagem na conversa\n3. O agente vê a mensagem de direção como uma nova mensagem de usuário e ajusta sua resposta\n4. Se a curva for concluída antes que a mensagem de direção seja processada, ela será movida automaticamente para a fila regular para a próxima curva\n\n> \\[!NOTE]\n> As mensagens de direcionamento são o melhor esforço no turno atual. Se o agente já tiver se comprometido com uma chamada da ferramenta, o direcionamento entrará em vigor após a conclusão dessa chamada, mas ainda dentro do mesmo turno.\n\n## Fila (modo de enfileiramento)\n\nO enfileiramento armazena em buffer as mensagens a serem processadas sequencialmente após a conclusão do turno atual. Cada mensagem enfileirada inicia seu próprio turno completo. Esse é o modo padrão, se você omitir `mode`, o SDK usará `\"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### Como a fila funciona internamente\n\n1. A mensagem é adicionada ao `itemQueue` da sessão como um `QueuedItem`\n2. Quando o turno atual terminar e a sessão ficar ociosa, `processQueuedItems()` será executado\n3. Os itens são removidos da fila na ordem FIFO, cada mensagem dispara um turno de agente completo\n4. Se uma mensagem de direcionamento estava pendente quando o turno terminou, ela é movida para a frente da fila\n5. O processamento continua até que a fila esteja vazia e, em seguida, a sessão emitirá um evento ocioso\n\n## Combinar direcionamento e enfileiramento\n\nVocê pode usar os dois padrões juntos em uma única sessão. O direcionamento afeta o turno atual enquanto as mensagens enfileiradas esperam sua vez:\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## Escolher entre direcionamento e enfileiramento\n\n| Scenario | Pattern | Por que |\n| -------------------------------------------------------- | ----------------------------------------------------------- | ------- |\n| O agente está indo pelo caminho errado | | |\n| **Direcção** | Redireciona o turno atual sem perder o progresso | |\n| Você pensou em algo que o agente também deveria fazer | | |\n| **Enfileiramento** | Não interrompe o trabalho atual; é executado em seguida | |\n| O agente está prestes a cometer um erro | | |\n| **Direcção** | Intervém antes que o erro seja cometido | |\n| Você deseja encadear várias tarefas | | |\n| **Enfileiramento** | A ordenação FIFO garante uma execução previsível | |\n| Você deseja adicionar contexto à tarefa atual | | |\n| **Direcção** | O Agente incorpora-o ao seu raciocínio atual | |\n| Você deseja enviar em lote solicitações não relacionadas | | |\n| **Enfileiramento** | Cada um obtém seu próprio turno completo com contexto limpo | |\n\n## Criar uma interface de usuário com direcionamento e enfileiramento\n\nAqui está um padrão para criar uma interface do usuário interativa que dá suporte a ambos os modos:\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## Referência de API\n\n### Opções de Mensagem\n\n| Linguagem | Campo | Tipo | Default | Description |\n| --------- | ------ | --------------------------------- | ----------- | ---------------------------- |\n| Node.js | `mode` | `\"enqueue\" \\| \"immediate\"` | `\"enqueue\"` | Modo de entrega de mensagens |\n| Python | `mode` | `Literal[\"enqueue\", \"immediate\"]` | `\"enqueue\"` | Modo de entrega de mensagens |\n| Go | `Mode` | `string` | `\"enqueue\"` | Modo de entrega de mensagens |\n| .NET | `Mode` | `string?` | `\"enqueue\"` | Modo de entrega de mensagens |\n\n### Modos de entrega\n\n| Modo | Efeito | Durante o turno ativo | Durante a inatividade |\n| ------------- | ------------------------- | ------------------------------------- | ----------------------------------- |\n| `\"enqueue\"` | Fila para a próxima curva | Esperas na fila FIFO | Inicia uma nova curva imediatamente |\n| `\"immediate\"` | Injetar no turno atual | Injetado antes da próxima chamada LLM | Inicia uma nova curva imediatamente |\n\n> \\[!NOTE]\n> Quando a sessão está ociosa (não processando), ambos os modos se comportam de forma idêntica– a mensagem inicia um novo turno imediatamente.\n\n## Práticas recomendadas\n\n1. **Definir como padrão o enfileiramento** — usar `\"enqueue\"` (ou omitir `mode`) para a maioria das mensagens. É previsível e não corre o risco de interromper o trabalho em andamento.\n\n2. **Reservar o direcionamento para correções** — usar `\"immediate\"` quando o agente estiver fazendo algo errado ativamente e for necessário redirecioná-lo antes que ele avance ainda mais.\n\n3. **Manter as mensagens de direcionamento concisas** — o agente precisa entender rapidamente a correção do curso. Mensagens de direção longas e complexas podem confundir o contexto atual.\n\n4. **Não direcione demais**— várias mensagens de direção rápidas podem prejudicar a qualidade da curva. Se você precisar alterar significativamente a direção, considere anular a curva e iniciar novamente.\n\n5. **Mostrar o estado da fila na interface do usuário** — exiba o número de mensagens enfileiradas para que os usuários saibam o que está pendente. Monitore eventos de inatividade para limpar a tela.\n\n6. **Manipular o fallback de direcionamento para fila** — se uma mensagem de direcionamento chegar após a conclusão do turno, ela será movida automaticamente para a fila. Crie sua interface do usuário para refletir essa transição.\n\n## Consulte também\n\n* [Crie seu primeiro aplicativo com tecnologia do Copilot](/pt/copilot/how-tos/copilot-sdk/getting-started): Configurar uma sessão e enviar mensagens\n* [Agentes personalizados e orquestração de subagentes](/pt/copilot/how-tos/copilot-sdk/features/custom-agents): Defina agentes especializados com ferramentas de escopo definido\n* [Ganchos de sessão](/pt/copilot/how-tos/copilot-sdk/hooks/hooks-overview): Reagir a eventos do ciclo de vida da sessão\n* [Retomada e persistência da sessão](/pt/copilot/how-tos/copilot-sdk/features/session-persistence): Retomar sessões entre reinicializações"}